Workforce Agents API

Drive a single agent over HTTP. Every request is authenticated with that agent's API key, sent as a bearer token:

Authorization: Bearer oct_agt_...

All endpoints are scoped to one agent through the {agentId} path segment - find the agent ID in the agent's page URL in the dashboard. A key only works for the agent it was created for.

Get an agent

Read whether the agent can take a run now, what it is working on, and the state of its computer.

GET /api/v1/workforce/agents/{agentId}

Response

{
  "agentId": "cm5abc123def456ghi",
  "name": "Avery Stone",
  "status": "busy",
  "unavailableReason": null,
  "currentThreadId": "cm5xyz123abc456def",
  "queuedThreads": 0,
  "computer": { "kind": "dedicated", "os": "linux", "state": "running" },
  "definition": { "slug": "research-analyst", "version": 12 },
  "capabilities": { "memory": true, "credentials": false }
}

The computer state is running, starting, paused (stopped; it resumes on the next run), down, or none (no computer yet, or the caller's own machine for a CLI agent). The status is computed on every read, so it reflects a dispatch immediately. New values may be added to any of these fields; treat an unrecognized one as unknown.

Example

curl https://octavus.ai/api/v1/workforce/agents/AGENT_ID \
  -H "Authorization: Bearer oct_agt_..."

Start a thread

Dispatch a message to the agent. This starts a new thread and returns immediately.

POST /api/v1/workforce/agents/{agentId}/threads

Request Body

{
  "message": "Summarize the latest sales report"
}

RunConfig

Configure how the agent runs for this thread without changing its dashboard settings - the same shape the Agent CLI accepts. Set on thread creation only; a thread's run config is fixed once it starts. The server validates and bounds it before the run starts, so an unrunnable model or an undeclared capability is rejected up front.

Any model from the model catalog is allowed, as long as a key resolves for its provider (your project/org key or the platform default), and so is any openrouter/... model when your project or org has its own OpenRouter key; any other model is rejected (see Unsupported Models). Capability toggles are bounded to the capabilities the agent's protocol declares.

Response

Returns 201 (200 when an idempotency key returns an earlier request's thread).

{
  "threadId": "cm5xyz123abc456def",
  "status": "pending"
}

Poll the Get a thread endpoint until the status is terminal.

Retry safely with an idempotency key

Send an Idempotency-Key header with a value unique to the task, such as a job id or a UUID (1-255 printable ASCII characters, no spaces):

Idempotency-Key: job-2026-03-04-reconcile-march

If you send the same key with the same request again - for example because the first response was lost - you get back 200 with the thread the first request created and an Idempotent-Replayed: true response header, and no second thread is started. The same key with a different request body is rejected with 409 IDEMPOTENCY_KEY_REUSED. A retry that arrives while the first request is still being processed can get 409 IDEMPOTENCY_KEY_IN_PROGRESS with a Retry-After header; retry after that delay to get the thread. A key stays bound to its thread for the thread's lifetime.

Only run on an idle agent

An agent runs one task at a time, so a new thread normally waits behind a run already in flight (queued). With "ifIdle": true in the body, a dispatch to an agent that already has a run in flight or queued is refused with 409 AGENT_BUSY instead, and nothing is created:

{
  "error": "The agent already has a run in flight or queued",
  "code": "AGENT_BUSY",
  "currentThreadId": "cm5xyz123abc456def"
}

currentThreadId names the thread holding the agent; it can be null when another dispatch is just starting. To check without dispatching, use Get an agent. ifIdle looks at this agent's threads only: a Mac shared with other agents may be running one of theirs, in which case the new thread waits its turn on that computer.

Example

curl -X POST https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads \
  -H "Authorization: Bearer oct_agt_..." \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize the latest sales report" }'

With a per-run config (model, thinking, capability toggles, recording):

curl -X POST https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads \
  -H "Authorization: Bearer oct_agt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize the latest sales report",
    "config": {
      "model": "anthropic/claude-sonnet-5",
      "thinking": "high",
      "capabilities": { "memory": false },
      "record": true
    }
  }'

Get a thread

Read a thread's status and messages. Poll this until the run finishes.

GET /api/v1/workforce/agents/{agentId}/threads/{threadId}

Response

{
  "threadId": "cm5xyz123abc456def",
  "status": "completed",
  "failureReason": null,
  "failureType": null,
  "messages": [],
  "runConfig": { "model": "anthropic/claude-sonnet-5", "thinking": "high" },
  "usage": {
    "currency": "USD",
    "costUsd": 0.0421,
    "totalFeeUsd": 0.0455,
    "byok": false,
    "inputTokens": 18234,
    "outputTokens": 1207,
    "totalTokens": 19441
  },
  "recording": null,
  "startedAt": "2026-03-04T10:12:03.418Z",
  "completedAt": "2026-03-04T10:19:47.902Z",
  "provenance": {
    "platform": {
      "deployments": [
        {
          "deploymentId": "dpl_9Xa2mQ7kLp3RtV8Wn",
          "commitSha": "4f1c2e9a7b3d5f60817c9e2a4b6d8f0a1c3e5b79",
          "firstSeenAt": "2026-03-04T10:12:03.912Z"
        }
      ]
    },
    "definition": { "slug": "research-analyst", "version": 12 },
    "computer": {
      "kind": "dedicated",
      "os": "linux",
      "runtimeVersion": "75",
      "imageVersion": "46",
      "region": "us-east-1"
    }
  }
}

Keep polling while the status is pending, queued, or running. Stop when it is completed, failed, cancelled, or blocked. A blocked thread means a usage or spending limit was reached (see failureReason); the thread is created even when the run is blocked before it starts, so a blocked attempt is still a pollable thread rather than an error. If the run was recorded and you need the video, keep polling until the recording is final too (see Recording).

Recording

A recorded run's recording has its own lifecycle, and it settles shortly after the run ends: a thread can read completed while its recording is still processing. To get the video, keep polling the thread until recording.status is ready, failed, or unavailable. It normally takes a few seconds.

recording is null only when the run was not recorded.

Provenance

provenance describes the run itself, not whatever is current when you read it, so a result can be attributed to exactly what produced it:

computer.kind is dedicated, e2b, mac, or cli. runtimeVersion is the computer's runtime release (the desktop app version on a Mac, the Agent CLI version for a CLI run), and imageVersion is the image a dedicated computer launched from or the sandbox template of an E2B computer.

Failure types

failureType classifies why a failed or blocked run stopped, so you can tell the agent failing at its task from a problem reaching it without parsing failureReason.

Only computer_unreachable guarantees the run never started. Every other type can follow work the agent already did, so check messages before retrying a task with side effects. New types may be added; treat an unrecognized value like unknown.

Example

curl https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads/THREAD_ID \
  -H "Authorization: Bearer oct_agt_..."

Follow up in a thread

Send another message into an existing thread. If the agent is still working the message runs after the current turn finishes; otherwise it starts immediately.

POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/messages

Request Body

{
  "message": "Now turn that into a slide deck"
}

Response

Returns 202.

{
  "threadId": "cm5xyz123abc456def",
  "status": "running"
}

Poll Get a thread for the new run's result.

Example

curl -X POST https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads/THREAD_ID/messages \
  -H "Authorization: Bearer oct_agt_..." \
  -H "Content-Type: application/json" \
  -d '{ "message": "Now turn that into a slide deck" }'

Cancel a thread's run

Stop a thread's in-flight run - the programmatic equivalent of the dashboard Stop button. The executor is signaled to abort, so a run that has overrun stops instead of continuing to bill. Idempotent: a thread that has already finished (or never started) is left as-is.

POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/cancel

Response

Returns 200.

{
  "threadId": "cm5xyz123abc456def",
  "status": "cancelled"
}

status is cancelled once the run was in flight, or the thread's unchanged status when it had already finished. The executor abort completes shortly after; poll Get a thread for the settled state.

Example

curl -X POST https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads/THREAD_ID/cancel \
  -H "Authorization: Bearer oct_agt_..."

Errors

Errors return { "error": string, "code": string } with an HTTP status: