Running via the API

Calls go to your Compass URL under the /v1 prefix:

https://your-compass-url/v1

Authenticate every request with an API key as a bearer token. The key is scoped to a project, so no other headers are needed:

Authorization: Bearer <your-api-key>

Dispatch with POST /v1/runs/. Provide either a deployment_id (the live version) or a workflow_id (a specific workflow or agent), plus the input_data payload. The response is a run with an id and a status.

curl -X POST https://your-compass-url/v1/runs/ \
  -H "Authorization: Bearer $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_id": "<deployment-id>",
    "input_data": { "topic": "Q3 report" }
  }'

run = await client.runs.create(
    deployment_id="<deployment-id>",
    input={"topic": "Q3 report"},
)

compass run --deployment <deployment-id> --input topic="Q3 report"

Once dispatched, read the run by id to check its status and output. Poll until it reaches a terminal state.

curl https://your-compass-url/v1/runs/<run-id> \
  -H "Authorization: Bearer $COMPASS_API_KEY"

run = await client.runs.get("<run-id>")

compass runs get <run-id>

For real-time output, subscribe to the run's event stream at GET /v1/streams/{run_id} — a Server-Sent Events connection that emits each event (tool calls, output, completion) as it happens.

curl -N https://your-compass-url/v1/streams/<run-id> \
  -H "Authorization: Bearer $COMPASS_API_KEY"

async for event in client.streams.events("<run-id>"):
    print(event)

# add --follow when you start the run
compass run --deployment <deployment-id> --input topic="Q3 report" --follow

Beyond the run itself, you can read its trace:

• GET /v1/runs/ — list runs in your project (optionally ?workflow_id=...).
• GET /v1/runs/{id}/executions — per-node execution details.
• GET /v1/runs/{id}/tree — the hierarchical trace, including sub-runs.
• GET /v1/runs/summary — aggregate usage over a time window.

The same base URL and auth cover the rest of the platform: