API reference

The full reference is at superflows.app/docs/api. It lists every route with its parameters, request body, response and errors.

The same document is available as OpenAPI 3.1 JSON at superflows.app/docs/openapi.json. Import it into an API client or a code generator.

Both are generated from the route definitions the server runs, so they match what the API accepts.

Conventions

Topic	Rule
Base URL	https://superflows.app. Routes start with /api/v1/
Auth	Authorization: Bearer sf_..., an organization key. See API keys
Rate limit	1,000 requests an hour per key
Bodies	JSON, sent with Content-Type: application/json
Paging	limit (1 to 100, default 20) and cursor. Pages return data and nextCursor
Health check	GET /api/health answers {"status": "ok"} and needs no key

To read every page of a list, pass each response’s nextCursor as the next request’s cursor until nextCursor is null.

Errors

Every error answers the same shape:

{
  "error": {
    "code": "workflow_not_found",
    "message": "Workflow not found"
  }
}

code is stable and meant for your code to branch on. message is for people. details is there only when a route has more to say, such as details.issues for a body that failed validation.

Status	Common codes
400	invalid_request, plus route codes such as trigger_required
401	unauthorized
402	plan_limit_reached, with details.resource and details.limit
403	forbidden, no_active_organization
404	<resource>_not_found, such as run_not_found
409	Conflicts such as not_published or agent_name_taken
500	internal, a fault on our side

Each route’s entry in the reference lists the codes it can answer.

What the reference leaves out

The app calls a few routes that are not in the reference, such as agent chat, the assistant and connecting apps. They serve signed-in members in the browser and are not part of the API. Build only on the routes the reference lists.

Next

• Starting runs
• Talking to agents