The locked FastAPI surface

Local and hosted deployments use the same API shape. Hosted routes may add a project prefix later, but the request bodies and semantics stay aligned.

Project API key or console JWT

Authorization: Bearer <project_api_key | supabase_jwt>

Project API keys resolve to workspace_id and project_id on the server. Console calls use the user's Supabase session JWT.

Supabase session JWT

Authorization: Bearer <supabase_jwt>

JWT requests are workspace-filtered. Optional project_id and session_id filters narrow the visible data, never broaden it.

Server-only credential

Internal FastAPI or trusted server token

Service-role credentials and provider tokens never leave server-side FastAPI or trusted Next.js routes, and still pass explicit workspace checks.

Method	Endpoint	Group	Auth	Purpose
POST	/api/traces	Ingestion	API key or JWT	Create a trace_session for an agent run.The SDK calls this before event delivery when starting a session.
POST	/api/traces/{id}/events	Ingestion	API key or JWT	Append one event or a batch of events, validate schema, persist rows, and rebroadcast SSE.Valid events in a mixed batch are accepted even when other events are rejected.
POST	/api/traces/{id}/artifacts	Artifacts	API key or JWT	Upload or register replay and screenshot artifacts in private Supabase Storage.Artifact event payloads carry artifact_id and storage_path, never public URLs.
GET	/api/sessions	Replay	JWT	List workspace/project-scoped sessions for the console.This is a read endpoint; trace mutations still go through FastAPI write routes.
GET	/api/traces/{id}/events	Replay	JWT	Read ordered events for replay and inspection.Timeline order never depends on client timestamp.
GET	/api/traces/{id}/analysis	Analysis	JWT	Read the stored analysis result for a session.The console renders this result; detection logic runs in FastAPI.
PUT	/api/traces/{id}/analysis	Analysis	Server-only	Persist analysis results and incident links from server-side analysis workflow.This endpoint is not callable by browser clients.
GET	/api/stream	Stream	JWT	Open a workspace-filtered SSE stream for live trace updates.Global stream means workspace-global, not public-global.
GET	/artifacts/{artifact_id}	Artifacts	JWT	Redirect an authorized console request to a short-lived signed artifact URL.Clients never receive raw public artifact URLs.
POST	/api/traces/{id}/analyze	Analysis	JWT	Run deterministic detectors on a session in FastAPI.Same ordered events in means same detector labels, confidences, and critical step.
GET	/api/incidents	Incidents	JWT	List workspace-scoped incident clusters.Incidents cluster trace failures; they are not generic analytics rows.
PATCH	/api/incidents/{id}	Incidents	JWT	Update incident status or owner.Workspace and project checks apply before mutation.
POST	/api/incidents/{id}/fix-agent	Fix	JWT	Dispatch FixAgentRunner and return a plan plus diff or a labeled fallback.GitHub installation tokens stay server-side.
POST	/api/incidents/{id}/regression-runs	Regression	JWT	Trigger before/after regression replay for an incident.Regression persistence goes through FastAPI with audit logging.

Ingestion

POST/api/tracesCreate a trace_session for an agent run.

POST/api/traces/{id}/eventsAppend one event or a batch of events, validate schema, persist rows, and rebroadcast SSE.

Artifacts

POST/api/traces/{id}/artifactsUpload or register replay and screenshot artifacts in private Supabase Storage.

GET/artifacts/{artifact_id}Redirect an authorized console request to a short-lived signed artifact URL.

Replay

GET/api/sessionsList workspace/project-scoped sessions for the console.

GET/api/traces/{id}/eventsRead ordered events for replay and inspection.

Analysis

GET/api/traces/{id}/analysisRead the stored analysis result for a session.

PUT/api/traces/{id}/analysisPersist analysis results and incident links from server-side analysis workflow.

POST/api/traces/{id}/analyzeRun deterministic detectors on a session in FastAPI.

Stream

GET/api/streamOpen a workspace-filtered SSE stream for live trace updates.

Incidents

GET/api/incidentsList workspace-scoped incident clusters.

PATCH/api/incidents/{id}Update incident status or owner.

Fix

POST/api/incidents/{id}/fix-agentDispatch FixAgentRunner and return a plan plus diff or a labeled fallback.

Regression

POST/api/incidents/{id}/regression-runsTrigger before/after regression replay for an incident.

Batch response

batch-response.jsonjson

{
  "accepted": 1,
  "rejected": [
    {
      "index": 1,
      "idempotency_key": "trace_curl_1:dev:1",
      "reason": "seq must be monotonic for this session"
    }
  ]
}

SSE stream

stream.shbash

curl "http://127.0.0.1:4318/api/stream?project_id=proj_acmemeet&after_seq=18" \
  -H "Authorization: Bearer $SUPABASE_SESSION_JWT" \
  -H "Accept: text/event-stream"

SSE reconnect behavior

Use Last-Event-ID or after_seq; the server backfills missed events before live events.

Standard errors

400	after_fix	Bad request: Malformed request body.
401	after_fix	Unauthorized: Missing or invalid authentication.
403	after_fix	Forbidden: Workspace or project mismatch.
404	after_fix	Not found: Trace or artifact is not visible in the caller's workspace.
409	conditional	Conflict: Duplicate seq or idempotency conflict.
413	after_fix	Payload too large: Artifact exceeds configured size limits.
415	after_fix	Unsupported media type: Artifact content type is not supported.
422	after_fix	Validation error: Schema validation failed for the event or request.
429	backoff	Rate limited: Burst or backpressure limit.
500	backoff	Server error: Unexpected server error with request id.