API reference

Every /api/v1/* endpoint, generated from the OpenAPI spec.

The reference pages here are generated from docs/openapi.yaml — the single source of truth that also drives @flowkoi/sdk and the Postman collection.

At a glance

Flows

  • GET /api/v1/flows — list flows in the key’s project.

Runs

  • POST /api/v1/flows/{flowId}/runs — trigger a new run.
  • GET /api/v1/runs/{runId} — current state.
  • GET /api/v1/runs/{runId}/logs — persisted log slice.
  • GET /api/v1/runs/{runId}/files — list flow files.
  • GET /api/v1/runs/{runId}/files/{filePath} — download one file.
  • GET /api/v1/runs/{runId}/stream — Server-Sent Events.
  • POST /api/v1/runs/{runId}/stop — graceful stop.
  • DELETE /api/v1/runs/{runId} — terminate + delete.

Interactions

  • POST /api/v1/runs/{runId}/messages — follow-up message into the PTY.
  • POST /api/v1/runs/{runId}/files — inject files mid-run.

Webhooks

  • run.finished — POSTed to your callbackUrl exactly once when a run reaches a terminal state.

Conventions

  • Auth — every endpoint requires Authorization: Bearer flo_.... See Authentication.
  • Versioning — all endpoints sit under /api/v1/. Breaking changes go to /api/v2/ and are announced in the Changelog.
  • Responses — successful bodies are wrapped in { "data": ... }. Errors share the error envelope.
  • Dates — ISO 8601 strings, UTC, milliseconds when relevant (2026-06-01T16:42:01.000Z).
  • IDs — UUID v4 for runId and flowId; opaque strings for projectId.

Downloads