Skip to main content

Workforce Agents API reference

Every endpoint, request field, response field, and error code of the Workforce Agents API.

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-Id header, and every error body a requestId. 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.
EndpointPurpose
GET /api/v1/workforce/agents/{agentId}Read the agent's availability and its computer
POST /api/v1/workforce/agents/{agentId}/filesHost files to attach to a task
POST /api/v1/workforce/agents/{agentId}/threadsStart 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}/messagesFollow up in a thread
POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/cancelStop 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.

text
GET /api/v1/workforce/agents/{agentId}
bash
curl "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID" \
  -H "Authorization: Bearer $OCTAVUS_AGENT_KEY"
json
{
  "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 }
}
FieldTypeDescription
statusstringidle (ready for a run), busy (a run is in flight or queued), or unavailable (a new run cannot start; see unavailableReason)
unavailableReasonstring | nullpaused (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)
currentThreadIdstring | nullThe thread holding the agent: the running one, else the oldest dispatched or queued one
queuedThreadsnumberThreads waiting behind the current one
computerobjectkind (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)
definitionobject | nullThe 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
capabilitiesobjectThe 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.

text
POST /api/v1/workforce/agents/{agentId}/files
json
{
  "files": [{ "filename": "spec.pdf", "mediaType": "application/pdf", "size": 204800 }]
}
FieldTypeRequiredDescription
filesarrayYes1 to 20 files
files[].filenamestringYesThe file's name
files[].mediaTypestringYesIts media type, application/pdf
files[].sizenumberYesIts size in bytes

Returns 201:

json
{
  "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.

bash
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @spec.pdf

Attaching files

The files field of a thread start or a follow-up is a list of file references:

json
{
  "id": "1762900000000-k3x9q2p",
  "mediaType": "application/pdf",
  "url": "https://s3.amazonaws.com/bucket/key?...",
  "filename": "spec.pdf",
  "size": 204800
}
FieldRequiredDescription
idYesThe id the files endpoint returned; for a URL you host yourself, any identifier of your choosing
mediaTypeYesThe file's media type
urlYesThe downloadUrl the files endpoint returned, or your own https: URL
filenameNoThe file's name
sizeNoIts size in bytes
width, heightNoAn 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:

CategoryMedia types
Imagesimage/jpeg, image/png, image/gif, image/webp, image/svg+xml
Videovideo/mp4, video/webm, video/quicktime, video/mpeg
Audioaudio/mpeg, audio/wav, audio/webm, audio/mp4, audio/x-m4a
Documentsapplication/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
Codetext/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.

text
POST /api/v1/workforce/agents/{agentId}/threads
json
{
  "message": "Summarize the latest sales report"
}
FieldTypeRequiredDescription
messagestringYes, unless files is givenThe task. A turn carries a message, at least one file, or both
filesarrayNoFile references; see Attaching files
configobjectNoPer-run configuration; see Run configuration. Omitted fields keep the agent's settings
ifIdlebooleanNoRefuse 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):

json
{ "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.

FieldTypeDescription
modelstringThe 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
backupModelstringThe model used when the primary one fails, in the same form
thinkingstringReasoning effort: off, low, medium, high, xhigh, max, or auto (the model decides)
capabilitiesobjectCapability toggles, { "memory": false }. The keys are those Get an agent lists under capabilities; an unlisted one keeps the agent's setting
recordbooleanRecord the run (the agent's work and its computer) to a video; see Recording
recordVisibilitystringWhere the recording is stored: private (default; played through a signed URL) or public (a permanent, unguessable URL). Ignored without record
bash
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):

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

Sending 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:

json
{
  "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.

text
GET /api/v1/workforce/agents/{agentId}/threads/{threadId}
bash
curl "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID" \
  -H "Authorization: Bearer $OCTAVUS_AGENT_KEY"
json
{
  "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"
    }
  }
}
FieldTypeDescription
threadIdstringThe thread's identifier
statusstringSee Thread statuses
failureReasonstring | nullWhy the run stopped, when status is failed or blocked
failureTypestring | nullThe class of failureReason; see Failure types. Null when there is no failure
messagesarrayThe conversation, in order; see Messages
runConfigobject | nullThe configuration the thread ran under (model, backupModel, thinking, capabilities); null when it ran with the agent's settings
usageobject | nullThe 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
recordingobject | nullThe run's recording when one was requested; see Recording. Null when the run was not recorded
startedAtstring | nullWhen the thread's first run started on the agent's computer (ISO 8601). Null while queued or pending, or when it never started
completedAtstring | nullWhen 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
provenanceobject | nullWhat 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

StatusMeaning
idleCreated, nothing sent yet. You rarely see it: a thread the API starts is pending or queued at once
pendingSent, waiting to start
queuedWaiting for the agent to finish its current run
runningThe agent is working
completedFinished (final)
failedEnded with an error; see failureReason and failureType (final)
cancelledStopped, by the API or by the Stop button in the dashboard (final)
blockedStopped 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 typeWhat it holds
textText the agent wrote: text and status
reasoningThe agent's reasoning, when the model exposes it: text and status
tool-callA step the agent took: toolName, title, status, and, for steps shown in full, args and result
workerWork the agent delegated to a sub-agent: title, status, and nested parts
fileA file the agent produced or was given: id, mediaType, url, filename, size
sourceA source the agent cited: url, title
operationAn operation card: name, title, status
objectStructured output: typeName, object
step-startThe 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.

StatusMeaning
requestedRecording was requested but the run has not started yet, for example because it is queued
recordingThe run is being recorded
processingThe run has ended; the video is being finalized
readyFinal. url plays the video
failedFinal. The video could not be produced; error says why
unavailableFinal. 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.

FieldTypeDescription
platform.deploymentsarrayThe 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
definitionobject | nullThe 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
computerobject | nullThe 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.

TypeMeaning
computer_unreachableThe agent's computer could not be reached, so the run never started
networkA connectivity failure on the way to the run: it could not be handed off, or its connection dropped
transportThe run's connection to Octavus kept dropping and could not be recovered
platformA failure on the Octavus side
providerThe model provider returned an error, was overloaded, or rate limited the run
timeoutA request timed out, usually to the model provider
billingA plan allowance was reached; comes with blocked
limitA spending limit was reached; comes with blocked
session_too_largeThe thread can no longer be stored; continue in a new thread
unknownThe 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.

text
POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/messages
json
{
  "message": "Now turn that into a slide deck"
}
FieldTypeRequiredDescription
messagestringYes, unless files is givenThe follow-up. A turn carries a message, at least one file, or both
filesarrayNoFile references; see Attaching files
recordbooleanNoRecord this turn to a video. Honored when the turn starts immediately; a turn that waits behind a run in flight is not recorded
recordVisibilitystringNoprivate (default) or public; see Run configuration. Ignored without record

Returns 202 with the thread's current status:

json
{ "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.

bash
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.

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

Returns 200:

json
{ "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.

bash
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:

json
{
  "error": "Thread not found: cm5xyz123abc456def",
  "code": "NOT_FOUND",
  "type": "not_found_error",
  "retryable": false,
  "requestId": "req_8f2c41d07a9b4e6c"
}
FieldDescription
errorA readable message
codeThe stable, machine-readable code
typeThe classification, such as validation_error, not_found_error, or conflict_error
retryableWhether the same request can succeed if retried
requestIdThe request's ID; quote it when contacting support
issuesOn a 400 validation failure: what was wrong with the body
retryAfterOn 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.

StatusCodeMeaning
400VALIDATION_ERRORThe body is invalid, or the turn has neither a message nor a file; issues lists the problems
400INVALID_RUN_CONFIGconfig names a model that cannot run or a capability the agent does not have; the message says which
400INVALID_FILE_REFERENCEA file in files is not one the agent can take; see Attaching files
400VALIDATION_ERRORThe Idempotency-Key header is malformed
401UNAUTHORIZEDThe API key is missing or invalid
403FORBIDDENThe key is not authorized for this agent
403ORG_BLOCKEDThe organization is suspended, pending verification, or archived; the message says which
404NOT_FOUNDThe agent or thread does not exist for this key
409AGENT_PAUSEDAn owner paused the agent; resume it in the dashboard
409AGENT_BUSYAn ifIdle request to an agent with a run in flight or queued; currentThreadId names the thread
409IDEMPOTENCY_KEY_REUSEDThe Idempotency-Key was used with a different request
409IDEMPOTENCY_KEY_IN_PROGRESSThe key's first request is still being processed; retry after Retry-After
409QUEUE_FULLThe thread already has 15 messages waiting
429Too many requests (hosting files is rate limited per organization); wait Retry-After seconds
500An error on the Octavus side; retry, and quote the requestId if it persists
503Temporarily 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.