The Workforce Agents API lets you give one of your Octavus Agents a task without a browser: send it a message, wait for it to finish, and read what it did. It is built for automation - CI pipelines, scheduled jobs, and backend code that hands work to an agent and collects the result. Every run is a normal Thread on the agent in the dashboard, live while it runs and afterward, so you can follow it there too.
You need:
- An agent in your organization that you have access to.
- A verified organization. If the agent's API settings say your organization is not verified, contact support@octavus.ai.
- A place to run server-side code or scripts. An API key is a secret and never belongs in a browser or a mobile app.
How a run works
- Start a thread by sending the agent a message. The API answers right away with a
threadId. - Poll the thread every few seconds until its status is final.
- Read the thread's messages to get the agent's reply and anything it produced.
An agent runs one task at a time on its computer. A thread started while the agent is busy waits in line (queued) and starts when the agent is free. Full runs often take several minutes.
| Status | Meaning |
|---|---|
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; failureReason says why (final) |
cancelled | Stopped (final) |
blocked | Could not run because a plan allowance or spending limit was reached; failureReason says which (final) |
Keep polling while the status is pending, queued, or running. Stop at completed, failed, cancelled, or blocked.
Create an API key
Each agent has its own keys. A key drives only the agent it was created for and can never call another one.
- In the dashboard, open the agent and go to Settings -> API.
- Select Create API key and name it after the job or system that will use it.
- Copy the key. It starts with
oct_agt_and is shown only once. - Store it where your code reads secrets: an environment variable, or your CI's secret store.
To revoke a key, delete it on the same page. Anything using it fails on its next request.
Treat the key like a password. Anyone who has it can give this agent work and read its threads. Never commit it to a repository or ship it in client-side code.
You also need the agent's ID: open the agent in the dashboard and copy the segment after /agents/ in the address bar, https://octavus.ai/agents/<agentId>/....
Run your first task
Every request goes to https://octavus.ai and carries the key as a bearer token:
Authorization: Bearer oct_agt_...The examples use two environment variables, AGENT_ID and OCTAVUS_AGENT_KEY.
1. Start a thread
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" }'{ "threadId": "cm5xyz123abc456def", "status": "pending" }2. Poll until it finishes
curl "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID" \
-H "Authorization: Bearer $OCTAVUS_AGENT_KEY"Read status from the response and repeat every few seconds until it is final.
3. Read the reply
The same response carries messages: the conversation, in order. Each message has a role (user or assistant) and a list of parts. The agent's reply is the last message with role: "assistant". Its words are in that message's text parts, and anything it produced for you (a document, a spreadsheet) is a file part with a download url. Other part types, such as tool-call, show the steps the agent took.
An abbreviated response:
{
"threadId": "cm5xyz123abc456def",
"status": "completed",
"failureReason": null,
"messages": [
{
"role": "user",
"parts": [{ "type": "text", "text": "Summarize the latest sales report", "status": "done" }]
},
{
"role": "assistant",
"parts": [
{ "type": "tool-call", "title": "Reading the report", "status": "done" },
{ "type": "text", "text": "Q3 revenue was up 12% ...", "status": "done" },
{ "type": "file", "mediaType": "application/pdf", "filename": "summary.pdf", "url": "https://..." }
]
}
],
"usage": { "costUsd": 0.0421, "totalTokens": 19441 },
"startedAt": "2026-03-04T10:12:03.418Z",
"completedAt": "2026-03-04T10:19:47.902Z"
}A complete example
Start a thread, wait for it, and print the reply. Python, standard library only:
import json
import os
import time
import urllib.request
BASE = f"https://octavus.ai/api/v1/workforce/agents/{os.environ['AGENT_ID']}"
HEADERS = {
"Authorization": f"Bearer {os.environ['OCTAVUS_AGENT_KEY']}",
"Content-Type": "application/json",
}
FINAL = {"completed", "failed", "cancelled", "blocked"}
def call(method, path, body=None):
data = json.dumps(body).encode() if body is not None else None
request = urllib.request.Request(BASE + path, data=data, method=method, headers=HEADERS)
with urllib.request.urlopen(request) as response:
return json.load(response)
thread = call("POST", "/threads", {"message": "Summarize the latest sales report"})
while thread["status"] not in FINAL:
time.sleep(5)
thread = call("GET", f"/threads/{thread['threadId']}")
if thread["status"] != "completed":
raise SystemExit(f"{thread['status']}: {thread['failureReason']}")
reply = [m for m in thread["messages"] if m["role"] == "assistant"][-1]
print("".join(part["text"] for part in reply["parts"] if part["type"] == "text"))Continue the conversation
Send another message into the same thread to build on what the agent did. If the agent is still working, the message runs after the current turn finishes; otherwise it starts right away.
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" }'The response is 202 with the thread's current status. Poll the thread as before for the new result; completedAt is cleared while the new turn runs and set again when it finishes.
Stop a run
Cancel a run that has taken too long or is no longer needed. This is the Stop button of the dashboard: the agent is told to stop, and the run stops billing.
curl -X POST "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID/cancel" \
-H "Authorization: Bearer $OCTAVUS_AGENT_KEY"The thread reads cancelled. Cancelling a thread that has already finished changes nothing.
Send files with a task
A task can carry files: a spec to review, a spreadsheet to clean up. Host them first with the files endpoint, upload the bytes to the URL it returns, then attach the reference to your message. You can also attach a file by an https: URL you host yourself. The steps are in Attaching files.
Good practices
- Retry safely. Send an
Idempotency-Keyheader with a value unique to the task, such as a job ID. If the response is lost and you send the same request again, you get the thread the first request created instead of a second run. - Do not pile up work. To run only when the agent is free, send
"ifIdle": true; a busy agent answers409 AGENT_BUSYand nothing is created. To look before you send, read the agent withGET /api/v1/workforce/agents/$AGENT_ID: itsstatusisidle,busy, orunavailable. - Poll gently. Every 3 to 5 seconds is plenty; runs take minutes, not milliseconds. Set your own time budget and cancel the run when it is exceeded.
- Check the work before retrying. On a
failedthread, readfailureType: onlycomputer_unreachableguarantees the agent did nothing. For anything else, look atmessagesbefore repeating a task with side effects, such as sending an email. - Keep the request ID. Every response carries a
Request-Idheader, and every error body arequestId. Quote it when you contact support@octavus.ai.
Verify
Open the agent in the dashboard. The thread you started is in its Threads, with your message, the agent's work, and the reply you read from the API.
Troubleshooting
| What you see | What it means |
|---|---|
401 | The key is missing, malformed, or was deleted. Send it as Authorization: Bearer oct_agt_.... |
403 FORBIDDEN | The key belongs to a different agent than the one in the URL. |
403 ORG_BLOCKED | Your organization is suspended, pending verification, or archived; the message says which. |
404 | The thread does not exist for this agent, or the agent ID is wrong. |
409 AGENT_PAUSED | An owner paused the agent. Resume it in the dashboard. |
Status blocked | A plan allowance or spending limit was reached; failureReason says which. Upgrade or raise the limit, then send a new message to the same thread. |
Agent unavailable | paused: resume the agent. computer_down: its computer cannot be reached; check it in the dashboard. cli_only: the agent is set to run from the Agent CLI on a machine you control, so it takes work only from there. |
| Cannot create a key | Your organization is not verified yet. Contact support@octavus.ai. |