The Workforce Agents API drives one Octavus Agent over HTTPS. This page lists every endpoint with its request and response fields. For a walkthrough, start with Run your agents from code.
Basics
- Base URL:
https://octavus.ai. - Authentication: the agent's API key as a bearer token on every request,
Authorization: Bearer oct_agt_.... Keys are created in the agent's Settings -> API. A key works only for the agent it was created for. - Agent ID: the
{agentId}in every path. Find it in the agent's address in the dashboard,https://octavus.ai/agents/<agentId>/.... - Bodies: JSON, sent with
Content-Type: application/json. - Request IDs: every response carries a
Request-Idheader, and every error body arequestId. Quote it when you contact support. - New values: statuses, part types, and fields are added over time. Treat a value you do not recognize as unknown rather than failing on it.
| Endpoint | Purpose |
|---|---|
GET /api/v1/workforce/agents/{agentId} | Read the agent's availability and its computer |
POST /api/v1/workforce/agents/{agentId}/files | Host files to attach to a task |
POST /api/v1/workforce/agents/{agentId}/threads | Start a thread: give the agent a task |
GET /api/v1/workforce/agents/{agentId}/threads/{threadId} | Read a thread's status, messages, and result |
POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/messages | Follow up in a thread |
POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/cancel | Stop a thread's run |
Get an agent
Read whether the agent can take a run now, what it is working on, and the state of its computer. The status is computed on every read, so it reflects a dispatch immediately.
GET /api/v1/workforce/agents/{agentId}curl "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID" \
-H "Authorization: Bearer $OCTAVUS_AGENT_KEY"{
"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 }
}| Field | Type | Description |
|---|---|---|
status | string | idle (ready for a run), busy (a run is in flight or queued), or unavailable (a new run cannot start; see unavailableReason) |
unavailableReason | string | null | paused (an owner paused the agent), computer_down (its computer cannot be reached), or cli_only (the agent runs only from the Agent CLI on a machine you control) |
currentThreadId | string | null | The thread holding the agent: the running one, else the oldest dispatched or queued one |
queuedThreads | number | Threads waiting behind the current one |
computer | object | kind (dedicated, e2b, mac, or cli), os (linux, windows, macos, or null), and state: running, starting, paused (stopped; it resumes on the next run), down, or none (no computer yet, or your own machine for a CLI agent) |
definition | object | null | The pre-built agent this agent was hired from (slug) and the version of its definition (version); null for an agent not hired from a pre-built one |
capabilities | object | The capabilities the agent can toggle, each with whether it is enabled. These are the keys a run's config.capabilities accepts |
Host files
Create files for the agent and get URLs to upload them to. A task's files must be files hosted for this agent, files one of its threads produced, or https: URLs you host yourself.
POST /api/v1/workforce/agents/{agentId}/files{
"files": [{ "filename": "spec.pdf", "mediaType": "application/pdf", "size": 204800 }]
}| Field | Type | Required | Description |
|---|---|---|---|
files | array | Yes | 1 to 20 files |
files[].filename | string | Yes | The file's name |
files[].mediaType | string | Yes | Its media type, application/pdf |
files[].size | number | Yes | Its size in bytes |
Returns 201:
{
"files": [
{
"id": "1762900000000-k3x9q2p",
"uploadUrl": "https://s3.amazonaws.com/bucket/key?...",
"downloadUrl": "https://s3.amazonaws.com/bucket/key?..."
}
]
}Then PUT each file's bytes to its uploadUrl with the declared Content-Type. The upload URL is valid for 15 minutes; the download URL for 7 days.
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @spec.pdfAttaching files
The files field of a thread start or a follow-up is a list of file references:
{
"id": "1762900000000-k3x9q2p",
"mediaType": "application/pdf",
"url": "https://s3.amazonaws.com/bucket/key?...",
"filename": "spec.pdf",
"size": 204800
}| Field | Required | Description |
|---|---|---|
id | Yes | The id the files endpoint returned; for a URL you host yourself, any identifier of your choosing |
mediaType | Yes | The file's media type |
url | Yes | The downloadUrl the files endpoint returned, or your own https: URL |
filename | No | The file's name |
size | No | Its size in bytes |
width, height | No | An image's dimensions in pixels, when you know them |
A hosted file is checked where it is used: its bytes must have been uploaded, and it must be this agent's. A URL you host yourself is accepted as given, without fetching; the agent reads it only when it needs the content, and it is never copied, so its availability is yours. A reference that fails these rules fails the request with 400 INVALID_FILE_REFERENCE.
Limits: 100 MB per file, 200 MB per request, 20 files per request.
Supported types:
| Category | Media types |
|---|---|
| Images | image/jpeg, image/png, image/gif, image/webp, image/svg+xml |
| Video | video/mp4, video/webm, video/quicktime, video/mpeg |
| Audio | audio/mpeg, audio/wav, audio/webm, audio/mp4, audio/x-m4a |
| Documents | application/pdf, text/plain, text/markdown, text/csv, text/html, application/json, application/yaml, text/yaml, application/x-yaml, application/xml, application/zip, application/octet-stream |
| Code | text/x-python, text/javascript, text/typescript |
| Office documents | .docx, .xlsx, .pptx (application/vnd.openxmlformats-officedocument.*), .doc (application/msword), .xls (application/vnd.ms-excel), .ppt (application/vnd.ms-powerpoint) |
Start a thread
Send the agent a message. This starts a new thread and returns immediately.
POST /api/v1/workforce/agents/{agentId}/threads{
"message": "Summarize the latest sales report"
}| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes, unless files is given | The task. A turn carries a message, at least one file, or both |
files | array | No | File references; see Attaching files |
config | object | No | Per-run configuration; see Run configuration. Omitted fields keep the agent's settings |
ifIdle | boolean | No | Refuse instead of queuing when the agent already has a run in flight or queued; see Only run on an idle agent |
Returns 201 (200 when an idempotency key returns an earlier request's thread):
{ "threadId": "cm5xyz123abc456def", "status": "pending" }Poll Get a thread until the status is final. When a plan allowance or spending limit stops the run before it starts, the thread is still created, with the status blocked and a failureReason, so every request is a thread you can read.
Run configuration
config sets how the agent runs this thread without changing its settings in the dashboard. It is fixed when the thread starts: a follow-up runs with the same configuration. The server checks it before the run starts, so a model that cannot run or a capability the agent does not have is refused up front with 400 INVALID_RUN_CONFIG.
| Field | Type | Description |
|---|---|---|
model | string | The model for the run, as provider/model-id, for example anthropic/claude-sonnet-5. Any model in the catalog at octavus.ai/pricing/models whose provider your organization can use |
backupModel | string | The model used when the primary one fails, in the same form |
thinking | string | Reasoning effort: off, low, medium, high, xhigh, max, or auto (the model decides) |
capabilities | object | Capability toggles, { "memory": false }. The keys are those Get an agent lists under capabilities; an unlisted one keeps the agent's setting |
record | boolean | Record the run (the agent's work and its computer) to a video; see Recording |
recordVisibility | string | Where the recording is stored: private (default; played through a signed URL) or public (a permanent, unguessable URL). Ignored without record |
curl -X POST "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads" \
-H "Authorization: Bearer $OCTAVUS_AGENT_KEY" \
-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
}
}'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 to 255 printable ASCII characters, no spaces):
Idempotency-Key: job-2026-03-04-reconcile-marchSending the same key with the same request again, for example because the first response was lost, returns 200 with the thread the first request created and an Idempotent-Replayed: true header; no second thread is started. The same key with a different body is refused with 409 IDEMPOTENCY_KEY_REUSED. A retry that arrives while the first request is still being processed gets 409 IDEMPOTENCY_KEY_IN_PROGRESS with a Retry-After header; retry after that delay. 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. With "ifIdle": true, a request to an agent that already has a run in flight or queued is refused with 409 AGENT_BUSY, and nothing is created:
{
"error": "The agent already has a run in flight or queued",
"code": "AGENT_BUSY",
"type": "conflict_error",
"retryable": false,
"requestId": "req_8f2c41d07a9b4e6c",
"currentThreadId": "cm5xyz123abc456def"
}currentThreadId names the thread holding the agent; it can be null when another request is just starting. To check without sending work, 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.
Get a thread
Read a thread's status, messages, and result. Poll this until the run finishes.
GET /api/v1/workforce/agents/{agentId}/threads/{threadId}curl "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID" \
-H "Authorization: Bearer $OCTAVUS_AGENT_KEY"{
"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"
}
}
}| Field | Type | Description |
|---|---|---|
threadId | string | The thread's identifier |
status | string | See Thread statuses |
failureReason | string | null | Why the run stopped, when status is failed or blocked |
failureType | string | null | The class of failureReason; see Failure types. Null when there is no failure |
messages | array | The conversation, in order; see Messages |
runConfig | object | null | The configuration the thread ran under (model, backupModel, thinking, capabilities); null when it ran with the agent's settings |
usage | object | null | The run's cost and tokens: costUsd (the model provider's cost), totalFeeUsd (provider and bandwidth fees), byok (whether your own provider key paid for it), and inputTokens, outputTokens, totalTokens |
recording | object | null | The run's recording when one was requested; see Recording. Null when the run was not recorded |
startedAt | string | null | When the thread's first run started on the agent's computer (ISO 8601). Null while queued or pending, or when it never started |
completedAt | string | null | When the thread's latest run reached its final status (ISO 8601). Null while a run is in flight; a follow-up clears it. With startedAt, this is the run's own duration, so you do not need to time your polls |
provenance | object | null | What the thread ran on, recorded while it ran; see Provenance. Null until a step of the thread has run, for example on a blocked thread |
Thread statuses
| Status | Meaning |
|---|---|
idle | Created, nothing sent yet. You rarely see it: a thread the API starts is pending or queued at once |
pending | Sent, waiting to start |
queued | Waiting for the agent to finish its current run |
running | The agent is working |
completed | Finished (final) |
failed | Ended with an error; see failureReason and failureType (final) |
cancelled | Stopped, by the API or by the Stop button in the dashboard (final) |
blocked | Stopped by a plan allowance or spending limit, before or during the run; see failureReason (final) |
Keep polling while the status is pending, queued, or running. Stop when it is completed, failed, cancelled, or blocked. A blocked thread runs again when you send it a new message after upgrading or raising the limit. If the run was recorded and you need the video, keep polling until the recording is final too.
Messages
messages is the conversation as the dashboard shows it, in order. Each message has a role (user or assistant), a status (done once complete), a createdAt, and parts. One turn of the agent is one assistant message, however many steps it took; its parts hold every step in order. The agent's reply to your last message is the last assistant message.
| Part type | What it holds |
|---|---|
text | Text the agent wrote: text and status |
reasoning | The agent's reasoning, when the model exposes it: text and status |
tool-call | A step the agent took: toolName, title, status, and, for steps shown in full, args and result |
worker | Work the agent delegated to a sub-agent: title, status, and nested parts |
file | A file the agent produced or was given: id, mediaType, url, filename, size |
source | A source the agent cited: url, title |
operation | An operation card: name, title, status |
object | Structured output: typeName, object |
step-start | The boundary between two steps of one turn |
The list grows over time. Keep a part of an unknown type and skip it when reading. A file part's url is a signed download link; read a thread again for a fresh one.
Recording
A recorded run's recording has its own lifecycle and 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.
| Status | Meaning |
|---|---|
requested | Recording was requested but the run has not started yet, for example because it is queued |
recording | The run is being recorded |
processing | The run has ended; the video is being finalized |
ready | Final. url plays the video |
failed | Final. The video could not be produced; error says why |
unavailable | Final. The recording never started, for example because your plan does not include recording; error says why |
recording also carries visibility (private or public). A private recording's url is a signed link; read the thread again for a fresh one.
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.
| Field | Type | Description |
|---|---|---|
platform.deployments | array | The platform builds that executed the thread's steps, oldest first: deploymentId, commitSha, and firstSeenAt. Usually one; more than one means a new build was deployed mid-thread |
definition | object | null | The pre-built agent the agent was hired from (slug) and the version of its definition (version) as of the thread's latest step; null for an agent not hired from a pre-built one |
computer | object | null | The computer as of the thread's latest step: kind (dedicated, e2b, mac, or cli), os, runtimeVersion, imageVersion, and region. Null when no step reached a 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.
| Type | Meaning |
|---|---|
computer_unreachable | The agent's computer could not be reached, so the run never started |
network | A connectivity failure on the way to the run: it could not be handed off, or its connection dropped |
transport | The run's connection to Octavus kept dropping and could not be recovered |
platform | A failure on the Octavus side |
provider | The model provider returned an error, was overloaded, or rate limited the run |
timeout | A request timed out, usually to the model provider |
billing | A plan allowance was reached; comes with blocked |
limit | A spending limit was reached; comes with blocked |
session_too_large | The thread can no longer be stored; continue in a new thread |
unknown | The failure could not be classified |
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 one you do not recognize like unknown.
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. A thread's configuration is set when it starts, so a follow-up takes no config.
POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/messages{
"message": "Now turn that into a slide deck"
}| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes, unless files is given | The follow-up. A turn carries a message, at least one file, or both |
files | array | No | File references; see Attaching files |
record | boolean | No | Record this turn to a video. Honored when the turn starts immediately; a turn that waits behind a run in flight is not recorded |
recordVisibility | string | No | private (default) or public; see Run configuration. Ignored without record |
Returns 202 with the thread's current status:
{ "threadId": "cm5xyz123abc456def", "status": "running" }Poll Get a thread for the new turn's result. Up to 15 messages can wait in a thread; one more is refused with 409 QUEUE_FULL. When a plan allowance or spending limit stops the follow-up before it starts, the thread itself is settled blocked with a failureReason.
curl -X POST "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID/messages" \
-H "Authorization: Bearer $OCTAVUS_AGENT_KEY" \
-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 Stop button of the dashboard, from code. The agent is told to stop, so a run that has overrun stops instead of continuing to bill. Cancelling a thread that has already finished, or never started, changes nothing.
POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/cancelReturns 200:
{ "threadId": "cm5xyz123abc456def", "status": "cancelled" }status is cancelled when the run was in flight, or the thread's unchanged status when it had already finished. The stop completes shortly after; poll Get a thread for the settled state.
curl -X POST "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID/cancel" \
-H "Authorization: Bearer $OCTAVUS_AGENT_KEY"Errors
Every error is one flat JSON body with an HTTP status:
{
"error": "Thread not found: cm5xyz123abc456def",
"code": "NOT_FOUND",
"type": "not_found_error",
"retryable": false,
"requestId": "req_8f2c41d07a9b4e6c"
}| Field | Description |
|---|---|
error | A readable message |
code | The stable, machine-readable code |
type | The classification, such as validation_error, not_found_error, or conflict_error |
retryable | Whether the same request can succeed if retried |
requestId | The request's ID; quote it when contacting support |
issues | On a 400 validation failure: what was wrong with the body |
retryAfter | On a 429 or 503: seconds to wait, also sent as the Retry-After header |
An error may add fields that describe it (a 409 AGENT_BUSY names the thread holding the agent). Ignore fields you do not recognize.
| Status | Code | Meaning |
|---|---|---|
400 | VALIDATION_ERROR | The body is invalid, or the turn has neither a message nor a file; issues lists the problems |
400 | INVALID_RUN_CONFIG | config names a model that cannot run or a capability the agent does not have; the message says which |
400 | INVALID_FILE_REFERENCE | A file in files is not one the agent can take; see Attaching files |
400 | VALIDATION_ERROR | The Idempotency-Key header is malformed |
401 | UNAUTHORIZED | The API key is missing or invalid |
403 | FORBIDDEN | The key is not authorized for this agent |
403 | ORG_BLOCKED | The organization is suspended, pending verification, or archived; the message says which |
404 | NOT_FOUND | The agent or thread does not exist for this key |
409 | AGENT_PAUSED | An owner paused the agent; resume it in the dashboard |
409 | AGENT_BUSY | An ifIdle request to an agent with a run in flight or queued; currentThreadId names the thread |
409 | IDEMPOTENCY_KEY_REUSED | The Idempotency-Key was used with a different request |
409 | IDEMPOTENCY_KEY_IN_PROGRESS | The key's first request is still being processed; retry after Retry-After |
409 | QUEUE_FULL | The thread already has 15 messages waiting |
429 | Too many requests (hosting files is rate limited per organization); wait Retry-After seconds | |
500 | An error on the Octavus side; retry, and quote the requestId if it persists | |
503 | Temporarily unavailable; wait Retry-After seconds |
A plan allowance or spending limit is not an error on these endpoints: the thread is created, or settled, with the status blocked and a failureReason, so it is always a thread you can read.