Skip to main content

​
State & Metrics

Core orchestrator state, runtime metadata, real-time events, and observability.
MethodPathDescription
GET/api/v1/stateFull orchestrator snapshot — queued, running, completed issues and token totals
GET/api/v1/runtimeRuntime info — version, data directory, feature flags
POST/api/v1/refreshTrigger an immediate poll/reconciliation cycle
GET/api/v1/transitionsAvailable state machine transitions per issue
GET/metricsPrometheus-format service metrics
GET/api/v1/eventsSSE stream of real-time orchestrator events
GET/api/v1/modelsList available AI models from the configured provider
POST /api/v1/refresh returns 202 Accepted, not 200. The reconciliation runs asynchronously.
curl http://127.0.0.1:4000/api/v1/state

​
Issue Management

Inspect individual issues, control running agents, override models and templates, and transition issue state.
MethodPathDescription
GET/api/v1/:idIssue detail with recent events and attempts
POST/api/v1/:id/abortAbort a running issue
POST/api/v1/:id/modelSet per-issue model override
POST/api/v1/:id/steerSend mid-turn guidance to the running agent
POST/api/v1/:id/templateOverride the prompt template for this issue
DELETE/api/v1/:id/templateClear the template override
POST/api/v1/:id/transitionTransition issue to a new workflow state
The :id parameter is the Linear issue identifier (e.g. ENG-123).

​
Model Override

​
model
string
required
The model identifier to use for this issue (e.g. o4-mini, gpt-4.1).
curl -X POST http://127.0.0.1:4000/api/v1/ENG-123/model \
  -H "Content-Type: application/json" \
  -d '{"model": "o4-mini"}'

​
Mid-Turn Steering

​
message
string
required
Guidance text injected into the running agent’s context.
curl -X POST http://127.0.0.1:4000/api/v1/ENG-123/steer \
  -H "Content-Type: application/json" \
  -d '{"message": "Focus on the auth module first, skip the tests for now."}'

​
State Transition

​
to
string
required
Target state name. Use GET /api/v1/transitions to see valid transitions.
​
reason
string
Optional human-readable reason for the transition.
curl -X POST http://127.0.0.1:4000/api/v1/ENG-123/transition \
  -H "Content-Type: application/json" \
  -d '{"to": "queued", "reason": "Retry after fix"}'

​
Attempts

Each issue can have multiple attempts. An attempt represents a single agent execution run.
MethodPathDescription
GET/api/v1/:id/attemptsList all attempts for an issue
GET/api/v1/attempts/:aidDetail for a specific attempt including event timeline
curl http://127.0.0.1:4000/api/v1/ENG-123/attempts

​
Configuration

Read the effective merged config, inspect the schema, and manage runtime overlay overrides.
MethodPathDescription
GET/api/v1/configEffective merged configuration (base + overlay)
GET/api/v1/config/schemaConfig JSON schema with example payloads
GET/api/v1/config/overlayCurrent overlay values only
PUT/api/v1/config/overlayReplace the entire overlay
DELETE/api/v1/config/overlay/:pathDelete a specific overlay path
The overlay is persisted to disk and survives restarts. It merges on top of the base config file and environment variables.
curl http://127.0.0.1:4000/api/v1/config

​
Secrets

Manage runtime secrets without restarting the service. Secrets are encrypted at rest.
MethodPathDescription
GET/api/v1/secretsList configured secret keys (values are not exposed)
POST/api/v1/secrets/:keyStore a secret
DELETE/api/v1/secrets/:keyDelete a secret
GET /api/v1/secrets returns key names only, never the secret values.
curl http://127.0.0.1:4000/api/v1/secrets

​
Templates

Manage prompt templates for agent instructions. Templates support variable interpolation.
MethodPathDescription
GET/api/v1/templatesList all prompt templates
GET/api/v1/templates/:idGet a specific template
POST/api/v1/templatesCreate a new template
PUT/api/v1/templates/:idUpdate an existing template
DELETE/api/v1/templates/:idDelete a template
POST/api/v1/templates/:id/previewPreview rendered output with sample variables
curl http://127.0.0.1:4000/api/v1/templates

​
Workspaces & Git

Inspect and manage the working directory pool and git routing context.
MethodPathDescription
GET/api/v1/workspacesList workspaces with disk usage
DELETE/api/v1/workspaces/:keyRemove a workspace and free disk
GET/api/v1/git/contextGit repo context — branches, remotes, routing rules
curl http://127.0.0.1:4000/api/v1/workspaces

​
Audit

Paginated audit log of all orchestrator actions for compliance and debugging.
MethodPathDescription
GET/api/v1/auditQuery audit log entries (supports pagination)
curl "http://127.0.0.1:4000/api/v1/audit?limit=50&offset=0"

​
Webhooks

Inbound webhook receivers for external integrations.
MethodPathDescription
POST/webhooks/linearLinear webhook receiver — processes issue and comment events
Webhook endpoints have a separate rate limit of 600 requests/minute. Configure the webhook URL in your Linear workspace settings.

​
Docs & Spec

Machine-readable API specification and interactive documentation.
MethodPathDescription
GET/api/v1/openapi.jsonOpenAPI 3.0 specification
GET/api/docsSwagger UI — interactive API explorer
curl http://127.0.0.1:4000/api/v1/openapi.json | jq .info
Last modified on March 31, 2026