Skip to content
Factflow

API reference

The REST API is served by factflow-server. 91 endpoints across 14 tags, covering every operation the CLI performs plus the live streaming and chat endpoints used by the frontend.

Two ways to browse:

  • API explorer — interactive Scalar UI with try-it-now clients, schema tree, and code samples. Opens in a new tab.
  • Per-endpoint pages — linkable, searchable, SEO-friendly. One page per operation under the Factflow API group in the sidebar below.

Canonical specification: the live server's /openapi.json. This docsite renders a committed snapshot of that spec.

How the API is organised

Section titled “How the API is organised”
TagPurposeCorresponding CLI
systemHealth, metrics, config, version, reloadfactflow system *
configsPipeline configuration CRUD + runfactflow config *
executionsExecution lifecycle + replay + DAG + streamingfactflow execution *
pipelinesRunning route control (pause/resume globally)factflow pipeline *
storageBrowse, read, stream storage objectsfactflow storage *
contentArchive + bulk download (async job model)factflow storage download
lineageTrace message flow, chains, failuresfactflow lineage *
searchSemantic, hybrid, RRF, multi-model searchfactflow search *
embeddingsManaged embedding storage metadata—
indexesVector index managementfactflow index *
chatStateful RAG chat threads + messages— (frontend)
replayReplay runner internal control—
webhooksSubscription CRUD + delivery historyfactflow webhook *
adaptersAdapter catalogue + schema introspection—

Conventions

Section titled “Conventions”

Response envelopes

Section titled “Response envelopes”

Success responses are plain JSON objects, not wrapped. Lists include a top-level array plus pagination when paginated:

{
  "items": [...],
  "pagination": {"limit": 50, "offset": 0, "total": 123}
}

Error responses

Section titled “Error responses”
{
  "detail": "Human-readable message",
  "code": "STABLE_ERROR_CODE",
  "trace_id": "req-uuid-for-log-correlation"
}

Error code values are stable across versions. trace_id lets you find the server log for the failed request.

Streaming

Section titled “Streaming”

Live updates use Server-Sent Events (SSE):

  • GET /executions/{id}/events — status changes
  • GET /executions/{id}/storage-stream — live storage writes
  • POST /chat/threads/{id}/messages — streaming LLM response

SSE clients: most HTTP libraries support them; the CLI uses Go's native SSE handling.

Idempotency

Section titled “Idempotency”

Several mutating endpoints accept Idempotency-Key headers:

  • POST /executions — dedupes repeated starts
  • POST /executions/{id}/replay — dedupes repeated replay attempts
  • POST /webhooks — dedupes repeated subscription creates

The key is scoped to the endpoint + config (not global). Retention: 24 hours.

Pagination

Section titled “Pagination”

List endpoints accept ?limit=N&offset=N. Default limit=50, max 1000.

Authentication

Section titled “Authentication”

Deployment-dependent. Typical setup: ingress enforces DNB SSO; the server reads the authenticated user from forwarded headers and uses the identity for row-level authorisation (e.g., chat threads are per-user).

For local embedded mode, there's no auth — everything is wide open. Don't expose embedded mode to a network.

Versioning

Section titled “Versioning”

All endpoints are under /api/v1. Breaking changes require a new version prefix. Non-breaking additions (new fields, new endpoints) land under v1.

Browsing the endpoints

Section titled “Browsing the endpoints”

Every endpoint has its own page in the Factflow API sidebar group — click into a tag to see the operations and their schemas.

Section titled “Related”