OpenAPI

FlowRunner generates a standard OpenAPI 3.0 document for each project, describing every flow endpoint it exposes. You can feed that spec to API clients, code generators, or documentation tools to work with your flows like any other REST API.

Where to get it

GET /api/openapi/<projectId>

The response is a JSON OpenAPI 3.0.3 document. Unlike the Run API, this endpoint is not public — it's scoped to your workspace:

You must be signed in, and you must have at least viewer access to the project.
A signed-out request returns 401; a request without project access returns 403.
The response is sent with Cache-Control: no-store and no wildcard CORS, because the spec describes your workspace's internals.

NOTE

An opt-in "publish API docs" flag that would expose a scoped public view of the spec is planned, but for now the document is private to workspace members.

What the spec describes

The generator walks the project and turns every Start node into an OpenAPI operation. For each one it produces:

Paths and methods

Each operation's path mirrors the live Run API URL: /api/run/<projectId>/<flow-file-slug>, with any declared path inputs appended as {param} placeholders. The HTTP method is the one the Start node is configured for (get, post, put, patch, or delete).

Parameters and request body

Path parameters (always marked required), query parameters, and header parameters are emitted from the Start node's input schemas.
A JSON requestBody is included for non-GET methods when the Start node declares body fields, under application/json.

FlowRunner's internal schema extensions (like value bindings) are stripped, so what you get is clean, portable JSON Schema — types, enum, format, string length, numeric bounds, array bounds, required, and descriptions.

Responses

The success response is taken from the End node connected downstream of the Start node: its configured status code (defaulting to 200) and its response body schema. The generator also always documents a 400 (validation error), and adds a 401 when the Start node requires auth.

Security schemes

If a Start node uses authentication, a matching OpenAPI security scheme is added under components.securitySchemes and referenced by the operation:

Node auth	OpenAPI scheme
`bearer`	`http`, scheme `bearer`
`basic`	`http`, scheme `basic`
`apiKey`	`apiKey` in a header (default `X-API-Key`)

Document shape

The top-level document looks like this (abridged):

json

{
  "openapi": "3.0.3",
  "info": { "title": "My Project", "version": "1.0.0" },
  "servers": [{ "url": "https://your-host" }],
  "paths": {
    "/api/run/proj_abc/users/create-user": {
      "post": {
        "summary": "Create user",
        "operationId": "node_2_post",
        "tags": ["My Project"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": {
          "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "description": "Validation error" }
        }
      }
    }
  }
}

info.title is your project name; the version is fixed at 1.0.0.
servers[0].url is the origin the spec was fetched from, so the paths are directly callable.
Each operation is tagged with the project name, gets an operationId of <startNodeId>_<method>, and uses the Start node's name as its summary.

TIP

Point a client generator (or an interactive docs viewer) at /api/openapi/<projectId> to get typed request builders for every flow in the project. Because the paths match the Run API exactly, generated clients call your flows with no extra wiring.

OpenAPI ​

Where to get it ​

What the spec describes ​

Paths and methods ​

Parameters and request body ​

Responses ​

Security schemes ​

Document shape ​

See also ​