API & SDK Access

Programmatic access for connected runtimes, workspace exports, and governed automation flows.

Two public programmatic surfaces#

LumenFlow exposes two programmatic surfaces today:

Control-plane SDK v1 for connected runtimes that enroll into the hosted control plane
Workspace product routes for authenticated exports, billing, and dashboard-managed operations

Authentication#

Connected runtime auth (API key)#

Connected runtimes authenticate with a workspace API key passed as a Bearer token in the Authorization header. You receive the plaintext token when you create a workspace or regenerate the key. Routes below marked API key use this pattern via authenticateRequest. The auth object exposes workspaceId, orgId, policyMode, and config.

Operator-facing product routes use your authenticated dashboard session cookie. These routes call authenticateDashboardRequest and are intended for the hosted product surfaces, not for long-running external runtimes. Routes below marked Dashboard use this pattern.

Enterprise operator auth (Supabase user)#

Enterprise admin routes authenticate via the Supabase session (getUser()) and then verify workspace owner/admin access. Routes below marked Enterprise operator use this pattern.

Unauthenticated#

The ops health endpoint requires no authentication.

Endpoint Reference#

All routes are relative to /api/v1.

1. Sessions#

Manage agent session registration and fleet topology.

`POST /sessions`

Auth: API key
Request body: { session_id, agent_id, agent_type, wu_id?, lane?, client_type?, agent_version?, host_id?, capabilities?, started_at?, bridge_identity?, governance_context? }
Response: { ok: true }
Errors: 400 (missing session_id, agent_id, or agent_type), 500

`GET /sessions`

List active fleet sessions with topology summary.

Auth: API key
Query params: lane?, wu_id?, include_stale? (boolean)
Response: { sessions: FleetSessionReadModel[], topology: FleetTopologySummary }
Errors: 500

`DELETE /sessions/:id`

Deregister a session by ID.

Auth: API key
Response: { ok: true } with desired-state contract headers
Errors: 500

2. Heartbeat#

Agent liveness check-in with assignment dispatch and signal coalescing.

`POST /heartbeat`

Send a heartbeat from a connected agent session.

Auth: API key
Request body: { agent_id, session_id?, lane?, wu_id?, health?, bridge_identity?, governance_context? }
Response: { ok: true, next_heartbeat_ms, assignment, budget_remaining_usd, coalesced_signals, enterprise_governance }
Errors: 400 (missing agent_id), 500

3. Events#

Governed kernel event ingestion and retrieval (evidence vault boundary).

`POST /events`

Ingest a batch of kernel events.

Auth: API key
Request body: { events: Array<{ kind, task_id?, timestamp, ... } | { eventKind, taskId?, eventTs, payload }> }
Max batch size: 1000
Response: { accepted: number }
Errors: 400 (empty/oversized batch, operator-control validation), 429 (quota exceeded with Retry-After), 500

`GET /events`

Query stored kernel events.

Auth: API key
Query params: taskId?, eventKind?, since? (ISO 8601), limit? (1-200, default 50)
Response: { evidenceVault, filters, events }
Errors: 400 (invalid limit or since), 500

4. Evidence#

Evidence receipt ingestion and retrieval (evidence vault boundary).

`POST /evidence`

Ingest a batch of evidence receipts.

Auth: API key
Request body: { receipts: Array<{ taskId?, receiptType, toolName?, scopeRequested?, scopeAllowed?, scopeEnforced?, inputHash?, outputHash?, payload?, eventTs }> }
Max batch size: 1000
Response: { accepted: number }
Errors: 400 (empty/oversized batch, operator-control validation), 429 (quota exceeded), 500

`GET /evidence`

Query stored evidence receipts.

Auth: API key
Query params: taskId?, receiptType?, since? (ISO 8601), limit? (1-200, default 50)
Response: { evidenceVault, filters, receipts }
Errors: 400 (invalid limit or since), 500

5. Telemetry#

Runtime telemetry and cost metric ingestion with fan-out to cost tracking.

`POST /telemetry`

Ingest a batch of telemetry metrics.

Auth: API key
Request body: { metrics | records: Array<{ metric, value, tags?, eventTs? | timestamp? }> }
Max batch size: 1000
Response: { accepted, costInserted, telemetryInserted }
Errors: 400 (invalid payload or validation errors), 429 (quota exceeded), 500

6. Telemetry Pipeline#

Aggregated pipeline telemetry query.

`GET /telemetry/pipeline`

Auth: API key
Query params: days? (default 30)
Response: pipeline metrics object
Errors: 500

7. Telemetry DORA#

DORA (DevOps Research and Assessment) metrics query.

`GET /telemetry/dora`

Auth: API key
Query params: days? (default 30)
Response: DORA metrics object
Errors: 500

8. Traces#

Task-level execution trace queries.

`GET /traces`

List execution traces.

Auth: API key
Query params: days? (default 30)
Response: { traces }
Errors: 500

`GET /traces/:taskId`

Get detailed trace entries for a single task.

Auth: API key
Query params: days? (default 30)
Response: { entries }
Errors: 400 (missing taskId), 500

9. Signals (Push)#

Inter-agent coordination signals with notification materialization.

`POST /signals`

Push a new signal.

Auth: API key
Request body: { local_id, message, type, sender, target?, created_at? }
Response: { accepted: 1, cloud_id }
Errors: 400 (missing local_id, message, type, or sender), 429 (quota exceeded), 500

`GET /signals`

List signals with filters.

Auth: Dashboard
Query params: since?, type?, unacked? (true/false), wu_id?, lane?, target_agent?
Response: { signals }
Errors: 500

10. Signals (Ack)#

Acknowledge a signal.

`POST /signals/:id/ack`

Mark a signal as acknowledged.

Auth: API key
Response: { ok: true }
Errors: 500

11. Signals (Stream)#

Server-Sent Events stream for real-time signal delivery.

`GET /signals/stream`

Open an SSE connection for live signals.

Auth: API key
Query params: wu_id?, lane?, target_agent?
Headers: Last-Event-ID for reconnection
Response: SSE stream (text/event-stream) with signal events, max duration 55 seconds, auto-retry 1 second
Errors: stream closes on error

12. Memory (Nodes)#

Project-scoped memory node retrieval.

`GET /memory/nodes`

List all memory nodes for the workspace.

Auth: API key
Response: { nodes }
Errors: none (standard DB errors)

13. Memory (Sync)#

Bidirectional memory synchronization with conflict detection.

`POST /memory/sync`

Push and pull memory nodes with version-based conflict resolution.

Auth: API key
Request body: { push_nodes?: Array<{ local_id, lifecycle, version, content_hash, node, updated_at }>, pull_since?: string }
Conflict rules: client version > server = accept; client < server = conflict; equal version + same hash = no-op; equal version + different hash = conflict
Response: { pushed: { accepted }, pulled, conflicts }
Errors: 400 (non-project lifecycle, invalid push_nodes), 429 (quota exceeded)

14. Config#

Workspace configuration with desired-state envelope.

`GET /config`

Retrieve workspace configuration.

Auth: API key
Response: { config, desired_state } with control-plane SDK headers
Errors: none (standard auth errors)

15. Policies#

Governance policy retrieval with authority context and desired-state envelope.

`GET /policies`

Retrieve active policies for the workspace.

Auth: API key
Response: { policies, mode, rollout_target, enterprise_governance, desired_state } with control-plane SDK headers
Errors: 500

16. Export#

Compliance export for evidence, events, telemetry, and access reviews.

`GET /export`

Export workspace data for compliance.

Auth: API key
Required query params: format (csv | json), source (evidence | events | telemetry | access_review)
Optional query params: since?, until? (ISO 8601). For access_review, both since and until are required plus reviewer signoff params.
Response (JSON): { complianceExport, data } with compliance contract headers
Response (CSV): file download with Content-Disposition header
Errors: 400 (invalid format, source, date range, or missing reviewer signoff)

17. Ops (Health & Status)#

System health and workspace operational status.

`GET /ops/health`

Unauthenticated database liveness probe.

Auth: None
Response: { ok: true, db: "up", timestamp } or { ok: false, db: "down", timestamp } (503)

`GET /ops/status`

Workspace operational status summary.

Auth: API key
Response: operational status object (varies)
Errors: standard auth errors

18. Costs#

Cost analytics with group-by aggregation.

`GET /costs`

Query cost data with flexible grouping.

Auth: API key
Required query params: group_by (model | agent | wu | session | operation | day), since (ISO 8601), until (ISO 8601)
Optional query params: wu_id?, agent_id?, model?, session_id?
Response: grouped cost data
Errors: 400 (missing/invalid group_by, since, until), 500

19. Approvals#

Operator-control approval workflow with comments and transitions.

`POST /approvals`

Request a new approval.

Auth: Dashboard
Request body: { type, title, description?, requested_by?, metadata? }
Response: { approval, enterprise_controls }
Errors: 400 (missing type/title, invalid operator-control payload), 500

`GET /approvals`

List approvals with optional filters.

Auth: Dashboard
Query params: status? (pending | approved | rejected | expired), type?
Response: { approvals, enterprise_controls }
Errors: 400 (invalid status), 500

`GET /approvals/:id`

Get approval detail with comments and transition history.

Auth: Dashboard
Response: { approval, comments, transitions, enterprise_controls }
Errors: 404 (not found), 500

`POST /approvals/:id`

Approve or reject an approval.

Auth: Dashboard
Request body: { action: "approve" | "reject", decided_by?, comment?, reason? }
Response: { approval, enterprise_controls }
Errors: 400 (invalid action or transition), 404 (not found), 500

`POST /approvals/:id/comments`

Add a comment to an approval.

Auth: Dashboard
Request body: { comment, created_by? }
Response: { comment }
Errors: 400 (missing comment), 404 (not found), 500

20. Enterprise#

Enterprise SSO/SAML/SCIM configuration and metadata.

`GET /enterprise`

Get enterprise auth configuration and trust surface.

Auth: Enterprise operator
Response: { enterpriseAuth: { orgId, operatorWorkspaceIds, config, contract, readiness } }
Errors: 401 (unauthenticated), 403 (not owner/admin)

`PUT /enterprise`

Update enterprise auth configuration.

Auth: Enterprise operator
Request body: { ssoEnabled, samlEnabled, scimEnabled, samlEntityId?, samlAcsUrl?, scimBaseUrl? }
Response: same shape as GET
Errors: 400 (invalid booleans or URLs), 401, 403

`GET /enterprise/saml/metadata`

Download SP SAML metadata XML.

Auth: Enterprise operator
Response: application/samlmetadata+xml
Errors: 401, 403, 409 (SAML not configured)

`POST /enterprise/scim/Users`

SCIM user provisioning stub.

Auth: Enterprise operator
Request body: { userName? }
Response (202): { status: "accepted", provisioning: "stub", orgId, userName }
Errors: 401, 403, 409 (SCIM not configured)

21. Delivery#

Delivery initiative management and WU dispatch.

`POST /delivery/initiatives`

Create a delivery initiative graph.

Auth: API key
Request body: { external_id, title, wus: Array<{ wu_id, lane, priority, depends_on[] }> }
Response (201): initiative create result
Errors: 400 (missing fields, input validation), 500

`GET /delivery/initiatives`

List delivery initiatives.

Auth: API key
Query params: status? (active | completed | cancelled)
Response: { initiatives }
Errors: 400 (invalid status), 500

`GET /delivery/initiatives/:id`

Get initiative detail.

Auth: Dashboard
Response: initiative detail object
Errors: 400, 404 (not found), 500

`GET /delivery/dispatch`

Get delivery dispatch view (queue status and pending assignments).

Auth: Dashboard
Response: dispatch view object
Errors: 500

`POST /delivery/dispatch`

Apply a WU operator action (release, requeue, or reassign).

Auth: API key
Request body: { wu_id, action: "release" | "requeue" | "reassign", reason? }
Response: operator action result
Errors: 400 (invalid input), 404 (not found), 409 (conflict), 500

`POST /delivery/wus/:wuId/complete`

Mark a delivery WU as complete.

Auth: API key
Request body: { session_id?, completed_at? } (both optional)
Response: WU completion result
Errors: 400, 404 (not found), 409 (conflict), 500

22. Runtime#

Hosted runtime session management and operator actions.

`GET /runtime/sessions`

List hosted runtime sessions.

Auth: API key
Response: { sessions }
Errors: 500

`GET /runtime/sessions/:id`

Get hosted runtime session detail.

Auth: API key
Response: session detail object
Errors: 400, 404 (not found), 500

`PUT /runtime/sessions/:id`

Upsert hosted runtime workflow state.

Auth: API key
Request body: full workflow state object with schema_version, session_id, status, timestamps, messages, history, counters, and continuations
Response: session detail object
Errors: 400 (invalid state), 500

`POST /runtime/sessions/:id/actions`

Apply a hosted runtime operator action (resume, retry, or abort).

Auth: API key
Request body: { action: "resume" | "retry" | "abort", continuation_messages?, continuation_messages_by_node_id?, reason? }
Response: operator action result
Errors: 400, 404 (not found), 409 (state conflict), 500

Common response headers#

Most control-plane SDK routes include these headers:

Header	Purpose
`Cache-Control`	`no-store` for writes, `private, max-age=30` for reads
`X-LumenFlow-Authority-Mode`	Current authority mode (authoritative, tighten-only, dev-override)
`X-LumenFlow-Contract-Version`	Control-plane contract version
`X-LumenFlow-Runtime-Model`	Runtime governance model identifier

Rate limits and availability#

Traffic limits vary by plan and workspace. Quota-enforced routes (events, evidence, telemetry, signals, memory) return 429 with a Retry-After header when the daily limit is exceeded. Free is intended for evaluation, Team supports sustained operator traffic, and Enterprise is the path for higher-volume governed runtimes or custom throughput needs.

Next step#

If you want to connect your own runtime, start with Governed Runtimes Overview and then follow the Control-Plane SDK Quickstart.

Two public programmatic surfaces#

Authentication#

Connected runtime auth (API key)#

Dashboard auth (session cookie)#

Enterprise operator auth (Supabase user)#

Unauthenticated#

Endpoint Reference#

1. Sessions#

POST /sessions

GET /sessions

DELETE /sessions/:id

2. Heartbeat#

POST /heartbeat

3. Events#

POST /events

GET /events

4. Evidence#

POST /evidence

GET /evidence

5. Telemetry#

POST /telemetry

6. Telemetry Pipeline#

GET /telemetry/pipeline

7. Telemetry DORA#

GET /telemetry/dora

8. Traces#

GET /traces

GET /traces/:taskId

9. Signals (Push)#

POST /signals

GET /signals

10. Signals (Ack)#

POST /signals/:id/ack

11. Signals (Stream)#

GET /signals/stream

12. Memory (Nodes)#

GET /memory/nodes

13. Memory (Sync)#

POST /memory/sync

14. Config#

GET /config

15. Policies#

GET /policies