SDK setup
Install the TypeScript SDK and create a client.
@blitflow/sdk is a typed TypeScript client for the Blitflow API. It works in
Node.js, Bun, and the browser, and covers the full contract: node discovery,
workflow runs with streamed events, published-workflow fetching, and a
programmatic workflow builder.
The SDK currently ships from the Blitflow monorepo as the workspace package
@blitflow/sdk; npm publication is on the way (the blitflow npm name is
already reserved).
Create a client
import { BlitClient } from "@blitflow/sdk";
const client = new BlitClient({
apiKey: process.env.BLITFLOW_TOKEN, // "blit_…" PAT or session token
});Options
| Option | Default | Description |
|---|---|---|
apiKey | — | Bearer token. When set, requests go to the public API with Authorization: Bearer … |
baseUrl | https://studio.blitflow.com/api (with apiKey), /api (without) | API origin override — point it at a Studio host's /api if needed |
credentials | "include" in session mode | fetch credentials mode |
Two auth modes
- API-key mode — pass
apiKey; defaults to the public API. This is what scripts, servers, and CI use. - Session mode — construct with no
apiKeyin a browser that's signed in to the Studio: requests go to the same-origin/apiwith cookies. This is how the Studio's own frontend uses the SDK.
The ops surface
Every contract operation is available, fully typed, on client.ops — inputs
are validated before sending and outputs parsed on receipt:
const specs = await client.ops["nodes.list"]({ q: "image", limit: 5 });
const version = await client.ops["workflows.get"]({
id: "abc123",
version: "2",
});
const events = await client.ops["runs.create"]({ workflowRef: "abc123@2" }); // AsyncIterable<RunEvent>On top of ops, the SDK exports ergonomic helpers — start with these:
| Helper | Purpose |
|---|---|
run(client, workflow, inputs, opts?) | Run to completion, return outputs |
startRun(client, workflow, inputs, opts?) | Start a run, iterate events yourself |
getWorkflow(client, ref) | Fetch a published definition by <id>@<version> |
searchNodes(client, opts?) / getNode(client, id) | Node palette discovery |
createWorkflow() / graphToWorkflow(…) | Build workflow definitions in code |
Errors from non-OK responses throw with the HTTP status and message — catch and inspect rather than retrying blindly.
@blitflow/sdk is a client — it never touches model providers directly.
The server-side execution engine (providers, node definitions) lives in
@blitflow/backend-sdk and is a separate, self-hosting concern.