Gateway API¶

The Obra gateway exposes a workflow-native local control plane over HTTP and WebSocket:

packaged Workflow Studio browser routes under /studio/*
canonical HTTP routes under /api/*
typed event streaming on WS /api/events/stream
authenticated diagnostics on /api/health/details
a generated OpenAPI artifact at openapi.json

Legacy /v1/* routes are not part of the supported public contract.

Install¶

uv tool install obra

The gateway runtime and its dependencies are included in the base package.

Start the server¶

obra gateway start

Override defaults with flags:

obra gateway start --host 0.0.0.0 --port 9000 --token my-secret --max-sessions 10

Check status:

obra gateway status

`obra studio` vs `obra gateway start`¶

obra studio is the default customer launch path. It handles setup and login preflight, starts or reuses the local gateway, and opens the packaged browser UI under /studio/*.

Use obra gateway start directly when you intentionally want API-only automation, custom token management, or gateway-only debugging.

Authentication¶

The gateway supports:

bearer auth for automation and direct API clients
a same-origin browser session for Workflow Studio launched through obra studio

Bearer requests use:

Authorization: Bearer <token>

/health and /ready are the only unauthenticated routes.

Discovery¶

GET /api is the API-first entry point. It returns the current gateway version, an inventory of route groups, and discovery links for the most useful next steps.

curl http://127.0.0.1:18790/api \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/domains/ \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/runners/kinds \
  -H "Authorization: Bearer <token>"

Example discovery response:

{
  "version": "3.2.32",
  "route_groups": [
    {
      "name": "assistant",
      "base_path": "/api/assistant",
      "route_count": 21
    },
    {
      "name": "workflow-runs",
      "base_path": "/api/workflow-runs",
      "route_count": 18
    },
    {
      "name": "workflows",
      "base_path": "/api/workflows",
      "route_count": 14
    }
  ],
  "_links": {
    "self": "/api",
    "domains": "/api/domains",
    "runners_kinds": "/api/runners/kinds",
    "sessions": "/api/sessions"
  }
}

GET /api uses _links. Most resource payloads use links.

Cross-cutting API patterns¶

Pagination¶

List routes support cursor pagination with ?cursor=<opaque>&limit=<int>.

default limit comes from gateway config
max limit comes from gateway config
the pagination block appears only when cursor or limit is requested
collection keys stay stable for backward compatibility

curl "http://127.0.0.1:18790/api/workflow-runs/?limit=2" \
  -H "Authorization: Bearer <token>"

{
  "workflow_runs": [
    {"run_id": "run-1"},
    {"run_id": "run-2"}
  ],
  "pagination": {
    "next_cursor": "Mg",
    "has_more": true,
    "total_count": 8
  }
}

Rate limit headers¶

All /api/* responses include rate-limit headers. 429 responses also include Retry-After.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1
Retry-After: 1

Resource links¶

Workflow, run, session, derivation, and thread payloads expose route-backed links objects so API clients can follow next actions directly.

{
  "session": {
    "session_id": "gateway-session-123",
    "status": "running",
    "links": {
      "self": "/api/sessions/gateway-session-123",
      "repair": "/api/sessions/gateway-session-123/repair",
      "force_complete": "/api/sessions/gateway-session-123/force-complete"
    }
  }
}

Error payload shapes¶

Some routes use structured GatewayAPIError envelopes:

{
  "error_code": "unknown_runner_kind",
  "message": "Unknown runner kind: workflow_runner",
  "hint": "Valid kinds: command, http, python"
}

Other surfaces still return plain FastAPI detail payloads, including rate limiting and parts of the callbacks and webhooks surface:

{
  "detail": "Rate limit exceeded"
}

{
  "detail": "Webhook not found"
}

Workflows¶

Workflow routes cover listing, revisions, create, validate, archive, restore, patch, delete, contract inspection, and snapshot export/import.

curl "http://127.0.0.1:18790/api/workflows/?view=active&limit=20" \
  -H "Authorization: Bearer <token>"

curl -X POST http://127.0.0.1:18790/api/workflows/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Claims exception review",
    "stages": [],
    "transitions": []
  }'

curl -X PATCH http://127.0.0.1:18790/api/workflows/WORKFLOW-CLAIMS-001 \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: rev-12" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {"op": "replace", "path": "/title", "value": "Claims exception review v2"}
    ]
  }'

Use X-Force-Delete: true on DELETE /api/workflows/{workflow_id} only when you intend a permanent delete instead of a soft-delete-to-trash flow.

Inspect a workflow's input/output contract:

curl http://127.0.0.1:18790/api/workflows/WORKFLOW-CLAIMS-001/contract \
  -H "Authorization: Bearer <token>"

Export and import workflow snapshots for backup or migration:

curl http://127.0.0.1:18790/api/workflows/export \
  -H "Authorization: Bearer <token>" \
  -o workflows-snapshot.json

curl -X POST http://127.0.0.1:18790/api/workflows/import \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @workflows-snapshot.json

Workflow runs¶

Workflow-run routes cover launch, inspection, per-stage visibility, lineage, review-state inspection, and operator control.

curl -X POST http://127.0.0.1:18790/api/workflow-runs/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Review the claims exception workflow and implement the approved fix",
    "project_id": "claims-ops",
    "working_dir": "~/obra-projects/claims-ops",
    "workflow_id": "WORKFLOW-CLAIMS-001",
    "revision_id": "rev-12",
    "domain_id": "business"
  }'

curl http://127.0.0.1:18790/api/workflow-runs/<run_id>/stages \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/workflow-runs/<run_id>/summary \
  -H "Authorization: Bearer <token>"

For comparisons, use:

curl "http://127.0.0.1:18790/api/workflow-runs/compare?run_ids=run-a,run-b" \
  -H "Authorization: Bearer <token>"

Validate run inputs before launch:

curl -X POST http://127.0.0.1:18790/api/workflow-runs/validate-input \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "WORKFLOW-CLAIMS-001",
    "revision_id": "rev-12",
    "objective": "Run the nightly claims triage"
  }'

Fetch stage-grouped outputs from a completed run:

curl http://127.0.0.1:18790/api/workflow-runs/<run_id>/outputs \
  -H "Authorization: Bearer <token>"

Workflow derivations¶

Derivations cover workflow creation, inspection, operator actions, resume, and acceptance.

curl -X POST http://127.0.0.1:18790/api/workflow-derivations/ \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: derive-claims-001" \
  -H "Content-Type: application/json" \
  -d '{
    "mission": "Derive a revised claims exception workflow",
    "project_id": "claims-ops",
    "working_dir": "~/obra-projects/claims-ops",
    "domain_id": "business"
  }'

curl -X POST http://127.0.0.1:18790/api/workflow-derivations/<derivation_id>/accept \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_baseline_ref": {
      "workflow_id": "WORKFLOW-CLAIMS-001",
      "revision_id": "rev-12"
    }
  }'

Sessions¶

Gateway sessions let API clients inspect and recover bound hybrid sessions for the authenticated owner.

curl "http://127.0.0.1:18790/api/sessions/?status=active" \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/sessions/<session_id> \
  -H "Authorization: Bearer <token>"

curl -X POST http://127.0.0.1:18790/api/sessions/<session_id>/repair \
  -H "Authorization: Bearer <token>"

curl -X POST http://127.0.0.1:18790/api/sessions/<session_id>/force-complete \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Operator approved closeout after partial recovery"}'

curl -X POST http://127.0.0.1:18790/api/sessions/<session_id>/reset-review \
  -H "Authorization: Bearer <token>"

Repair returns structured diagnostics:

{
  "issues_found": 2,
  "actions_taken": ["phase:updated", "status:updated"],
  "new_status": "running",
  "new_phase": "execution"
}

The HTTP contract does not include a separate confirmation field for destructive mutations. Any confirmation step is a caller or UI concern, not a request parameter.

Assistant¶

Assistant routes expose durable threads, turns, pipelines, models, action execution, and audit history.

curl -X POST http://127.0.0.1:18790/api/assistant/threads \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Claims workflow repair"}'

curl -X POST http://127.0.0.1:18790/api/assistant/threads/<thread_id>/turns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "Propose a safer escalation resolution path."}'

curl http://127.0.0.1:18790/api/assistant/pipelines \
  -H "Authorization: Bearer <token>"

Model discovery and refresh are available under /api/assistant/models and /api/assistant/models/refresh.

Runners¶

Runner routes cover catalog lookup, runner-kind discovery, config-schema inspection, and compatibility checks.

curl http://127.0.0.1:18790/api/runners/ \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/runners/kinds \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/runners/kinds/http/config-schema \
  -H "Authorization: Bearer <token>"

curl -X POST http://127.0.0.1:18790/api/runners/compatibility-check \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "runner_id": "software.test.pytest",
    "platform": "linux"
  }'

The public config-schema route is GET /api/runners/kinds/{runner_kind}/config-schema.

Interpolation¶

Interpolation validation is available through the authoring API.

curl -X POST "http://127.0.0.1:18790/api/interpolation/validate?resolve=true" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "${stage.validate_invoice.output.exit_code}",
    "context_hint": {
      "available_stages": ["validate_invoice", "publish_result"]
    }
  }'

Callbacks¶

Callback routes provide read-only visibility into persisted callback metadata.

curl http://127.0.0.1:18790/api/callbacks/ \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/callbacks/<callback_id> \
  -H "Authorization: Bearer <token>"

Events¶

The gateway supports both per-resource SSE streams and a multiplexed WebSocket stream.

curl -N http://127.0.0.1:18790/api/workflow-runs/<run_id>/events \
  -H "Authorization: Bearer <token>"

curl -N http://127.0.0.1:18790/api/workflow-derivations/<derivation_id>/events \
  -H "Authorization: Bearer <token>"

curl -N http://127.0.0.1:18790/api/workflows/<workflow_id>/events \
  -H "Authorization: Bearer <token>"

wscat -c ws://127.0.0.1:18790/api/events/stream

{"type":"auth","token":"<token>"}
{"type":"subscribe","workflow_id":"WORKFLOW-CLAIMS-001"}

Subscriptions may target exactly one of run_id, derivation_id, or workflow_id.

For a complete reference including reconnection, sequence tracking, and keepalive patterns, see Event Stream Client Reference.

Webhooks¶

Webhooks let automation receive signed workflow, derivation, and run events without holding open stream connections.

curl -X POST http://127.0.0.1:18790/api/webhooks/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://automation.example.com/hooks/obra",
    "resource_type": "workflow_run",
    "resource_id": "run-123",
    "events": ["workflow_run.completed", "workflow_run.failed"],
    "secret": "replace-with-32-char-minimum-secret"
  }'

curl -X POST http://127.0.0.1:18790/api/webhooks/<webhook_id>/test \
  -H "Authorization: Bearer <token>"

Registrable events come from the canonical resource-type event sets. The synthetic webhook.test payload is emitted only by the test endpoint and is not a valid registration event.

Automation¶

Automation routes provide a loopback-oriented launch and watch surface for workflow runs and derivations.

curl -X POST http://127.0.0.1:18790/api/automation/runs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Run the nightly claims triage",
    "project_id": "claims-ops",
    "working_dir": "~/obra-projects/claims-ops",
    "domain_id": "business"
  }'

curl -N http://127.0.0.1:18790/api/automation/runs/<run_id>/events \
  -H "Authorization: Bearer <token>"

Knowledge documents¶

Knowledge routes let operators upload reference material for assistant context.

curl -X POST http://127.0.0.1:18790/api/knowledge/documents \
  -H "Authorization: Bearer <token>" \
  -F "file=@policies/claims-review.md"

curl http://127.0.0.1:18790/api/knowledge/documents \
  -H "Authorization: Bearer <token>"

Artifacts and template assets¶

Artifact and template-asset routes expose persisted execution evidence and authoring assets.

curl http://127.0.0.1:18790/api/artifacts/<artifact_id>/content \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/template-assets/templates/review.md/revisions \
  -H "Authorization: Bearer <token>"

Transcription¶

Voice transcription routes are available when the optional voice runtime is installed.

curl http://127.0.0.1:18790/api/transcription/providers \
  -H "Authorization: Bearer <token>"

curl -X POST http://127.0.0.1:18790/api/transcription/transcribe \
  -H "Authorization: Bearer <token>" \
  -F "audio=@note.wav"

Settings¶

Settings routes expose the gateway configuration catalog and allow operators to inspect and override editable settings.

curl http://127.0.0.1:18790/api/settings/catalog \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/settings \
  -H "Authorization: Bearer <token>"

curl -X PATCH http://127.0.0.1:18790/api/settings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orchestration.budgets.enabled": true
  }'

The catalog returns sections, fields, tiers, and validation metadata. PATCH applies user-layer overrides; project- and session-locked fields are read-only.

Filesystem¶

Filesystem routes support working-directory browsing and creation from Workflow Studio and API clients.

curl "http://127.0.0.1:18790/api/filesystem/browse?path=~/obra-projects" \
  -H "Authorization: Bearer <token>"

curl -X POST http://127.0.0.1:18790/api/filesystem/mkdir \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"path": "~/obra-projects/new-project"}'

curl "http://127.0.0.1:18790/api/filesystem/validate-path?path=~/obra-projects/claims" \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/filesystem/defaults \
  -H "Authorization: Bearer <token>"

All paths are validated against traversal and symlink attacks. browse returns directory listings; validate-path checks existence and characterizes missing path segments; defaults returns the default projects and home directories.

Onboarding¶

Onboarding routes power the first-run provider setup flow in Obra Desktop and Workflow Studio.

curl http://127.0.0.1:18790/api/onboarding/status \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/onboarding/providers \
  -H "Authorization: Bearer <token>"

curl -X POST http://127.0.0.1:18790/api/onboarding/providers/claude/authenticate \
  -H "Authorization: Bearer <token>"

curl http://127.0.0.1:18790/api/onboarding/providers/claude/auth-status \
  -H "Authorization: Bearer <token>"

curl -X POST http://127.0.0.1:18790/api/onboarding/complete \
  -H "Authorization: Bearer <token>"

Providers can be dismissed and later re-enabled with POST .../providers/{provider_id}/dismiss and .../undismiss.

Health¶

curl http://127.0.0.1:18790/health

curl http://127.0.0.1:18790/ready

curl http://127.0.0.1:18790/api/health/details \
  -H "Authorization: Bearer <token>"

/health is the unauthenticated liveness probe. /ready reports subsystem initialization status without authentication. /api/health/details is the authenticated diagnostic surface.

Endpoint summary by capability¶

Discovery¶

Method	Path	Purpose
`GET`	`/api`	Capabilities manifest and discovery links
`GET`	`/api/domains/`	List installed domains
`GET`	`/api/runners/kinds`	List gateway-exposed runner kinds

Workflows¶

Method	Path	Purpose
`GET`	`/api/workflows/`	List workflows
`GET`	`/api/workflows/export`	Export workflow snapshot
`POST`	`/api/workflows/import`	Import workflows from snapshot
`GET`	`/api/workflows/{workflow_id}`	Inspect one workflow
`GET`	`/api/workflows/{workflow_id}/contract`	Inspect workflow I/O contract
`GET`	`/api/workflows/{workflow_id}/revisions`	List workflow revisions
`GET`	`/api/workflows/{workflow_id}/revisions/{revision_id}`	Inspect one workflow revision
`POST`	`/api/workflows/`	Create a workflow
`POST`	`/api/workflows/{workflow_id}/validate`	Validate a workflow draft
`POST`	`/api/workflows/{workflow_id}/archive`	Archive a workflow
`POST`	`/api/workflows/{workflow_id}/restore`	Restore an archived workflow
`PATCH`	`/api/workflows/{workflow_id}`	Apply revision-guarded workflow changes
`DELETE`	`/api/workflows/{workflow_id}`	Soft delete or hard delete a workflow

Workflow Runs¶

Method	Path	Purpose
`GET`	`/api/workflow-runs/`	List workflow runs
`GET`	`/api/workflow-runs/compare`	Compare multiple runs
`POST`	`/api/workflow-runs/`	Launch a workflow run
`POST`	`/api/workflow-runs/validate-input`	Pre-flight input validation
`GET`	`/api/workflow-runs/{run_id}`	Inspect one workflow run
`GET`	`/api/workflow-runs/{run_id}/lineage`	Inspect parent-child run lineage
`GET`	`/api/workflow-runs/{run_id}/outputs`	Get stage-grouped run outputs
`POST`	`/api/workflow-runs/{run_id}/cancel`	Cancel a run
`POST`	`/api/workflow-runs/{run_id}/resume`	Resume a run
`POST`	`/api/workflow-runs/{run_id}/operator-actions`	Dispatch a run operator action
`POST`	`/api/workflow-runs/{run_id}/escalations/{escalation_id}/resolve`	Resolve a run escalation
`GET`	`/api/workflow-runs/{run_id}/stages`	List stage status for a run
`GET`	`/api/workflow-runs/{run_id}/stages/{stage_name}`	Inspect one stage
`GET`	`/api/workflow-runs/{run_id}/summary`	Get run summary metrics
`GET`	`/api/workflow-runs/{run_id}/escalations`	List escalations for a run
`GET`	`/api/workflow-runs/{run_id}/review-state`	Inspect review-state payload
`GET`	`/api/workflow-runs/{run_id}/replay`	Fetch replay payload for the run

Workflow Derivations¶

Method	Path	Purpose
`GET`	`/api/workflow-derivations/`	List derivations
`POST`	`/api/workflow-derivations/`	Create a derivation
`GET`	`/api/workflow-derivations/{derivation_id}`	Inspect one derivation
`POST`	`/api/workflow-derivations/{derivation_id}/cancel`	Cancel a derivation
`POST`	`/api/workflow-derivations/{derivation_id}/resume`	Resume a derivation
`POST`	`/api/workflow-derivations/{derivation_id}/operator-actions`	Dispatch a derivation operator action
`POST`	`/api/workflow-derivations/{derivation_id}/accept`	Accept a derivation result

Sessions¶

Method	Path	Purpose
`GET`	`/api/sessions/`	List gateway sessions
`GET`	`/api/sessions/{session_id}`	Inspect one gateway session
`POST`	`/api/sessions/{session_id}/repair`	Repair a bound hybrid session
`POST`	`/api/sessions/{session_id}/force-complete`	Force-complete a session
`POST`	`/api/sessions/{session_id}/reset-review`	Reset review state

Assistant¶

Method	Path	Purpose
`GET`	`/api/assistant/pipelines`	List assistant pipelines
`GET`	`/api/assistant/pipelines/{pipeline_id}`	Inspect one assistant pipeline
`POST`	`/api/assistant/pipelines/execute`	Execute an assistant pipeline
`POST`	`/api/assistant/pipelines/{pipeline_id}/cancel`	Cancel a pipeline run
`POST`	`/api/assistant/threads`	Create a thread
`GET`	`/api/assistant/threads`	List threads
`GET`	`/api/assistant/threads/{thread_id}`	Inspect one thread
`PATCH`	`/api/assistant/threads/{thread_id}`	Update thread metadata
`POST`	`/api/assistant/threads/{thread_id}/restore`	Restore an archived thread
`DELETE`	`/api/assistant/threads/{thread_id}`	Archive a thread
`POST`	`/api/assistant/threads/{thread_id}/carry-forward`	Create a carried-forward thread
`POST`	`/api/assistant/threads/{thread_id}/turns`	Append a turn
`PATCH`	`/api/assistant/threads/{thread_id}/turns/{turn_id}`	Update a turn
`GET`	`/api/assistant/threads/{thread_id}/audit`	Read thread audit history
`GET`	`/api/assistant/models`	List available assistant models
`POST`	`/api/assistant/models/refresh`	Refresh model registry state
`POST`	`/api/assistant/actions/{action_id}/execute`	Execute one assistant action
`POST`	`/api/assistant/actions/execute-batch`	Execute a batch of assistant actions
`POST`	`/api/assistant/actions/{audit_id}/revert`	Revert one applied assistant action
`GET`	`/api/assistant/pipelines/active`	List active pipeline sessions
`POST`	`/api/assistant/pipelines/sessions/{session_id}/cancel`	Cancel a pipeline session
`GET`	`/api/assistant/pipelines/sessions/{session_id}/events`	Stream pipeline session events

Runners¶

Method	Path	Purpose
`GET`	`/api/runners/`	List catalog-backed runners
`GET`	`/api/runners/kinds`	List gateway-exposed runner kinds
`GET`	`/api/runners/kinds/{runner_kind}/config-schema`	Inspect runner config schema
`GET`	`/api/runners/{runner_id}`	Inspect one runner
`POST`	`/api/runners/compatibility-check`	Check runner compatibility

Interpolation¶

Method	Path	Purpose
`POST`	`/api/interpolation/validate`	Validate interpolation syntax and optional stage resolution

Callbacks¶

Method	Path	Purpose
`GET`	`/api/callbacks/`	List persisted callback records
`GET`	`/api/callbacks/{callback_id}`	Inspect one callback record

Events¶

Method	Path	Purpose
`GET`	`/api/workflow-runs/{run_id}/events`	Stream run events over SSE
`GET`	`/api/workflow-derivations/{derivation_id}/events`	Stream derivation events over SSE
`GET`	`/api/workflows/{workflow_id}/events`	Stream workflow events over SSE
`WS`	`/api/events/stream`	Multiplexed event stream with subscriptions

Webhooks¶

Method	Path	Purpose
`POST`	`/api/webhooks/`	Register a webhook
`GET`	`/api/webhooks/`	List webhook registrations
`GET`	`/api/webhooks/{webhook_id}`	Inspect one webhook
`DELETE`	`/api/webhooks/{webhook_id}`	Delete a webhook
`POST`	`/api/webhooks/{webhook_id}/test`	Send a synthetic test delivery

Automation¶

Method	Path	Purpose
`POST`	`/api/automation/runs`	Launch an automation run
`GET`	`/api/automation/runs/{run_id}`	Inspect an automation run
`GET`	`/api/automation/runs/{run_id}/events`	Stream automation run events
`POST`	`/api/automation/runs/{run_id}/cancel`	Cancel an automation run
`POST`	`/api/automation/runs/{run_id}/actions`	Dispatch an automation run action
`POST`	`/api/automation/derivations`	Launch an automation derivation
`GET`	`/api/automation/derivations/{derivation_id}`	Inspect an automation derivation
`GET`	`/api/automation/derivations/{derivation_id}/events`	Stream automation derivation events
`POST`	`/api/automation/derivations/{derivation_id}/cancel`	Cancel an automation derivation
`POST`	`/api/automation/derivations/{derivation_id}/actions`	Dispatch an automation derivation action
`GET`	`/api/automation/bootstrap-template`	Get the bootstrap template for automation clients

Knowledge¶

Method	Path	Purpose
`POST`	`/api/knowledge/documents`	Upload a knowledge document
`GET`	`/api/knowledge/documents`	List knowledge documents
`GET`	`/api/knowledge/documents/{doc_id}`	Inspect one knowledge document
`DELETE`	`/api/knowledge/documents/{doc_id}`	Delete a knowledge document

Artifacts¶

Method	Path	Purpose
`GET`	`/api/artifacts/`	List artifacts
`GET`	`/api/artifacts/{artifact_id}`	Inspect one artifact
`GET`	`/api/artifacts/{artifact_id}/content`	Get artifact content
`GET`	`/api/artifacts/{artifact_id}/references`	Inspect artifact references
`GET`	`/api/artifacts/{artifact_id}/provenance`	Inspect artifact provenance

Template Assets¶

Method	Path	Purpose
`GET`	`/api/template-assets/`	List template assets
`GET`	`/api/template-assets/{asset_id}`	Inspect one template asset
`GET`	`/api/template-assets/{asset_id}/revisions`	List template asset revisions
`GET`	`/api/template-assets/{asset_id}/bindings`	List template asset bindings

Transcription¶

Method	Path	Purpose
`POST`	`/api/transcription/transcribe`	Transcribe uploaded audio
`GET`	`/api/transcription/providers`	List available transcription providers

Settings¶

Method	Path	Purpose
`GET`	`/api/settings/catalog`	Get settings catalog with fields and metadata
`GET`	`/api/settings`	Get editable settings with origins
`PATCH`	`/api/settings`	Update gateway settings

Filesystem¶

Method	Path	Purpose
`GET`	`/api/filesystem/browse`	Browse directory contents
`POST`	`/api/filesystem/mkdir`	Create a directory
`GET`	`/api/filesystem/validate-path`	Validate a path
`GET`	`/api/filesystem/defaults`	Get default project and home directories

Onboarding¶

Method	Path	Purpose
`GET`	`/api/onboarding/status`	Get onboarding status with provider states
`GET`	`/api/onboarding/providers`	List available providers
`POST`	`/api/onboarding/providers/{provider_id}/authenticate`	Start provider auth flow
`GET`	`/api/onboarding/providers/{provider_id}/auth-status`	Check provider auth completion
`POST`	`/api/onboarding/providers/{provider_id}/dismiss`	Dismiss a provider
`POST`	`/api/onboarding/providers/{provider_id}/undismiss`	Re-enable a dismissed provider
`POST`	`/api/onboarding/complete`	Mark onboarding complete

Health¶

Method	Path	Purpose
`GET`	`/health`	Liveness probe
`GET`	`/ready`	Readiness probe with subsystem status
`GET`	`/api/health/details`	Authenticated diagnostics

The published OpenAPI artifact is available at openapi.json.

For event payload schemas and the full event name taxonomy, see docs/api/event-catalog.md and the AsyncAPI specification at docs/api/asyncapi.yaml in the repository.

Gateway API¶

Install¶

Start the server¶

obra studio vs obra gateway start¶

Authentication¶

Discovery¶

Cross-cutting API patterns¶

Pagination¶

Rate limit headers¶

Resource links¶

Error payload shapes¶

Workflows¶

Workflow runs¶

Workflow derivations¶

Sessions¶

Assistant¶

Runners¶

Interpolation¶

Callbacks¶

Events¶

Webhooks¶

Automation¶

Knowledge documents¶

Artifacts and template assets¶

Transcription¶

Settings¶

Filesystem¶

Onboarding¶

Health¶

Endpoint summary by capability¶

Discovery¶

Workflows¶

Workflow Runs¶

Workflow Derivations¶

Sessions¶

Assistant¶

Runners¶

Interpolation¶

Callbacks¶

Events¶

Webhooks¶

Automation¶

Knowledge¶

Artifacts¶

Template Assets¶

Transcription¶

Settings¶

Filesystem¶

Onboarding¶

Health¶

`obra studio` vs `obra gateway start`¶