Quickstart

Create an access token

In the Studio, open Settings → API tokens and create a personal access token. It looks like blit_… and is shown once — store it somewhere safe (an environment variable, a secret manager).

export BLITFLOW_TOKEN="blit_..."

All authenticated calls send it as a bearer token: Authorization: Bearer $BLITFLOW_TOKEN. See Authentication for the details (and for blitflow login, the browser-based alternative for your dev machine).

Explore the node palette

Nodes are the units of work: image models, LLMs, media utilities. Search the palette to find what you need:

curl "https://studio.blitflow.com/api/v1/nodes?q=image&limit=5" \
  -H "Authorization: Bearer $BLITFLOW_TOKEN"

import { BlitClient, searchNodes } from "@blitflow/sdk";

const client = new BlitClient({ apiKey: process.env.BLITFLOW_TOKEN });
const specs = await searchNodes(client, { query: "image", limit: 5 });

Each result is a node spec listing the node's exact input and output ports, including defaults and allowed enum values. Always read the spec before calling a node — enum values are not guessable, and a wrong value fails validation. See Nodes & specs.

Run a workflow

A run takes either an inline workflow definition or a reference to a published workflow (<id>@<version>), plus input values. The response is a stream of events, ending in run.completed with the outputs.

import { BlitClient, run } from "@blitflow/sdk";

const client = new BlitClient({ apiKey: process.env.BLITFLOW_TOKEN });

// Run a workflow you published from the Studio editor:
const outputs = await run(
  client,
  "abc123@latest", // or "abc123@2.1.0", or an inline Workflow object
  { prompt: { kind: "text", value: "a brass key on black velvet" } },
  { maxCostUsd: 0.25 },
);

curl -N -X POST "https://studio.blitflow.com/api/v1/runs" \
  -H "Authorization: Bearer $BLITFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowRef": "abc123@latest",
    "inputs": { "prompt": { "kind": "text", "value": "a brass key on black velvet" } },
    "maxCostUsd": 0.25
  }'

Read the outputs

Outputs are Artifacts. Small values (text, numbers) arrive inline; binary results (images, audio, video) arrive as a ref — a URL you fetch to get the bytes:

{
  "image": {
    "kind": "image",
    "ref": "https://…/output.png",
    "mimeType": "image/png"
  }
}

const artifact = outputs.image;
if ("ref" in artifact) {
  const bytes = await fetch(artifact.ref).then((r) => r.arrayBuffer());
}