Developers
API overview
Embed the agent in your own app over the HTTP API: keys and their scope, end_user_ref, the turn lifecycle, webhooks, billing and a first request in a minute.
Last updated:
On this page
What the API gives you
The API lets your server create isolated spaces, configure them (manifest, secrets, tools, MCP servers), send requests with files, and get back replies and files the agent produced. Billing goes to your account, broken down by your own customers.
Keys and access
- Base URL:
https://dash.octodus.com/v1 - Every request: the header
Authorization: Bearer octo_live_… - Create keys in the dashboard: Integrations, API keys. The key is shown once.
- The API is for server-side calls: never embed a key in a browser or mobile app.
| Key scope | What it controls |
|---|---|
| Only spaces this key creates (recommended) | Spaces created through POST /v1/spaces with this key |
| One space | The one space you named |
| All my spaces | Every space the account owns |
end_user_ref is your own customer ID. It does not create an account with us, but spend and per-customer limits are tracked by it.
Your first request
Create a space, send a turn with an Idempotency-Key, and poll it until it reaches a terminal state. Python and TypeScript versions are in the reference.
bash
BASE=https://dash.octodus.com/v1
KEY=octo_live_xxxxxxxxxxxxxxxx
SLUG=$(curl -s -X POST $BASE/spaces -H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' -d '{"title":"My first space"}' | jq -r .space_id)
TURN=$(curl -s -X POST $BASE/turns -H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" \
-d '{"space":"'"$SLUG"'","end_user_ref":"customer-42","text":"Hello"}' | jq -r .turn_id)
curl -s $BASE/turns/$TURN -H "Authorization: Bearer $KEY" | jq '{state, result}'Lifecycle and webhooks
- A turn is asynchronous:
queued→running→done|failed|cancelled. - Instead of polling, register a webhook: the platform posts a signed event on every transition. Webhooks
- A turn's result is text for a person. The agent delivers structured data through your own tools (MCP or REST). Tools and MCP
Billing and limits
- Each turn is billed to the key owner's account; the cost is in
billed_cost_usd. 402 INSUFFICIENT_CREDITS: the balance is exhausted and needs a top-up.429 QUOTA_EXCEEDED: the key's daily cap, a customer cap or a windowed cap; honour Retry-After.- There is no request rate limit: spend is bounded by the balance and the caps.