HTTP API
API overview
Base URL, authentication, conventions, and errors for the /v1 HTTP API.
The HTTP API exposes the Blitflow contract over plain REST + Server-Sent Events. Use it from any language; the TypeScript SDK and MCP server are typed wrappers over exactly these operations.
Base URL & auth
https://studio.blitflow.com/apiAll endpoints require a bearer token:
curl "https://studio.blitflow.com/api/v1/nodes" \
-H "Authorization: Bearer $BLITFLOW_TOKEN"See Authentication for token types. When calling a
Studio deployment directly, the API lives under the /api prefix
(https://<studio-host>/api/v1/…).
Operations
| Operation | Method & path | Scope | Response |
|---|---|---|---|
nodes.list | GET /v1/nodes | read | NodeSpec[] |
nodes.get | GET /v1/nodes/:id | read | NodeSpec |
workflows.get | GET /v1/workflows/:id | read | Published version + definition |
runs.create | POST /v1/runs | run | SSE stream of run events |
runs.node | POST /v1/runs/node | run | { outputs } |
Conventions
- Request and response bodies are JSON (
Content-Type: application/json), exceptruns.create, which responds withtext/event-stream. GEToperations take parameters as query strings;POSToperations take a JSON body.- Inputs are validated against the contract schemas — unknown fields are rejected, not ignored.
Errors
Errors are JSON with a human-readable message:
{ "error": "workflow abc123@9.9.9 not found" }| Status | Meaning |
|---|---|
400 | Invalid JSON, failed schema validation, bad version selector, or both/neither of workflow/workflowRef provided |
401 | Missing, invalid, expired, or revoked token |
403 | Cross-origin cookie-authenticated mutation (use a bearer token) |
404 | Workflow, version, or node not found |
For streaming runs, failures after the stream starts arrive as a
run.failed event on the stream, not as an HTTP error status.