HTTP and WebSocket API
Use the raw API from any language. TypeScript users get the same calls through the SDK. Every request and response schema is in the API reference.
The base URL is https://gateway.broods.app, or your own gateway when self-hosting.
Credentials
Every request sends Authorization: Bearer <credential>.
| Endpoint | Accepts |
|---|---|
POST /v1/runs, GET /v1/runs/{runId} | Runtime key, account key, or a stage session ticket |
GET /v1/runs/{runId} | Also a run token, from inside a sandbox |
| Agent WebSocket | Runtime key or a stage session ticket |
/v1/* config routes | Account key, or a role session within its policy |
| Logs and traces socket | Stage session ticket only. The runtime key is refused |
The runtime key only reaches agents with publicAccess: true in its own stage, over HTTP and on the agent WebSocket alike. A run token (brt_, read from BROODS_RUN_TOKEN inside a sandbox) only reads its own agent's runs. Starting a run with it is not enabled yet, so POST /v1/runs and every other route answer 403 run_token_scope, and config routes answer 401. Prefixes, lifetimes and the other limits of each credential are in Security. Every credential starts with b (bsk_, bask_, ...).
With the runtime key, also send the signed-in user's token, which your server signs with the stage's signing secret:
X-Broods-User-Token: buat_...
Every conversationKey and eventId of that request then lives under that user, and the response names them as bsu:<userId>:<key>. Send either form back. An agent that requires a user token, which every new agent does, answers the runtime key without one with 403 user_token_required. A forged or expired token is a 401. See Users behind the runtime key.
The signing secret comes from POST /v1/account/projects/{project}/stages/{stage}/user-token-secret, authenticated with the account key, a project key or a broods login token holding keys:write on the stage. It rotates the secret and returns it once as { "secret": "bsig_...", "hint": "bsig_…abcd" }; tokens the previous secret signed stop working. broods dev and broods deploy call it for you when the stage has no secret yet.
Calling the API from a sandbox
Every bash command that blocks runs with the identity of the run that issued it. A background job outlives the run and its token, so it gets none:
| Variable | Value |
|---|---|
BROODS_RUN_TOKEN | Bearer that reads this agent's runs. Expires shortly after the run's time budget |
BROODS_AGENT_ID | The agent the run acts as |
BROODS_ACCOUNT_ID | Its account |
BROODS_BASE_URL | The API base, when the deployment publishes one |
curl -sS "$BROODS_BASE_URL/v1/runs/run_..." \
-H "Authorization: Bearer $BROODS_RUN_TOKEN"
The env carries no run id. Use one your script was handed, such as the runId returned to whoever started a background run of this agent. Account envVars cannot override these names. The token does not start runs yet.
Run an agent
POST /v1/runs streams the turn back as server-sent events.
curl -N -X POST "https://gateway.broods.app/v1/runs" \
-H "Authorization: Bearer $BROODS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "agent_...",
"eventId": "req-001",
"conversationKey": "my-conversation",
"events": [
{ "role": "user", "content": [{ "type": "text", "text": "Hello, who are you?" }] }
]
}'
| Field | Required | Description |
|---|---|---|
agentId | yes | Agent to run |
eventId | yes | Your correlation id |
conversationKey | yes | Conversation to continue or create |
events | yes, unless answers or continue | AI SDK messages. Roles user, tool, and system with persist: false |
background | no | true answers 202 with a run id instead of streaming |
mode | no | Busy-conversation behavior, one of steer, the default, followup, collect, reject |
idempotencyKey | no | Retry identity. Defaults to eventId, bound for 7 days |
system | no | One-turn system message or list, not stored |
model | no | Per-run call settings such as temperature, maxOutputTokens, reasoning, providerOptions. provider, modelId, output and apiKey are rejected |
answers | no | Answers to open ask_questions prompts. Cannot be combined with events |
continue | no | Re-enter a run that stopped on the step cap or a provider fault |
The stream carries AI SDK stream parts such as step-start, text-delta, tool-call, tool-result, finish and error. One run can carry several model passes, each ending in its own finish part: after subagent or async tool results, or after the run hands its worker slot on near the slot deadline. The run is over when the stream closes, not at a finish part. A run that writes nothing for 30 seconds, such as during a long tool call, sends an SSE comment line such as : keepalive or : waiting for async work pending=2. SSE parsers ignore them, and they keep the connection open. A streamed run waits for a free worker slot like a background run, so on a busy deployment the stream may send only keepalives before its first part. If the run queue itself is full, the request answers 503 with Retry-After and one SSE error frame. Nothing runs, nothing is recorded or counted against your plan, and retrying with the same eventId starts the run. An account out of budget or past its runs per minute gets its 402 or 429 instead, even while the queue is full. A run that passed the check and owns its conversation is never failed for capacity later. One queued behind another turn of its conversation starts when that turn ends, and can still fail with In-process worker queue is full if the queue is full then. Closing the connection before the run finishes aborts the run and marks it failed. Use background: true when the caller may disconnect.
The dashboard advertises a scoped form of the same endpoint, POST /v1/projects/{project}/stages/{stage}/agents/{endpointId}. It takes the same body and refuses a key from another project or stage with 401.
Background runs and polling
curl -X POST "https://gateway.broods.app/v1/runs" \
-H "Authorization: Bearer $BROODS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agentId": "agent_...", "eventId": "req-002", "conversationKey": "report", "background": true,
"events": [{ "role": "user", "content": [{ "type": "text", "text": "Write the report." }] }] }'
{
"runId": "run_8c1d4a9e2f1b40d7a3c65e90b7412fda",
"eventId": "req-002",
"conversationKey": "report",
"status": "processing",
"requestedMode": "steer",
"statusUrl": "https://gateway.broods.app/v1/runs/run_8c1d4a9e2f1b40d7a3c65e90b7412fda"
}
Poll GET /v1/runs/{runId} until the status settles. Status records stay readable for 7 days. If the run queue is full, the background POST answers 503 service_unavailable with Retry-After instead of 202. Nothing is recorded or counted, and a retry with the same eventId starts the run. A plan refusal (402, 429) comes first. A 202 with status processing is never failed for capacity. One with status queued waits behind another turn of its conversation and can still fail for capacity when that turn ends on a full queue.
status | Meaning |
|---|---|
accepted, queued, applied, processing | Not finished |
awaiting_approval | approvals lists tool calls waiting for approval |
awaiting_input | questions lists open ask_questions prompts |
completed | response and result hold the answer |
failed | error explains. stoppedByUser: true marks a deliberate /stop |
expired | Queued work timed out before it ran |
Each status also reports the owning agentId, plus requestedMode, appliedMode and appliedToEventId.
Answer a question
When a run is awaiting_input, post the answers on the same route with no events. The conversation resumes by itself.
curl -X POST "https://gateway.broods.app/v1/runs" \
-H "Authorization: Bearer $BROODS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agentId": "agent_...", "eventId": "req-003", "conversationKey": "my-conversation", "background": true,
"answers": [{ "statusId": "async_tool_...", "answers": { "deploy_target": ["dev"] } }] }'
statusId comes from the question. answers maps each question id to option labels or free text.
Continue a stopped run
A turn that hits agent.maxTurn or a provider fault ends as failed with its history intact. continue: true appends one "continue" user turn and runs it as a followup. It always answers 202.
curl -X POST "https://gateway.broods.app/v1/runs" \
-H "Authorization: Bearer $BROODS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agentId": "agent_...", "eventId": "req-004", "conversationKey": "my-conversation", "continue": true }'
Busy conversations
A second request on a conversation that is already running follows mode:
| Mode | Behavior |
|---|---|
steer | Joins the live run at its next step. Becomes a follow-up if the run has no step left |
followup | Runs as its own turn after earlier work |
collect | Queued messages merge into one later turn |
reject | Refused with 409 conversation_busy. Nothing is stored |
A queued request answers 202 with a statusUrl instead of a second SSE stream. Steered output appears on the live run's stream. Each conversation queues up to 100 requests or 1 MiB; beyond that you get 429 ingress_capacity with Retry-After. Queued requests expire after 15 minutes. See Conversations.
A user's conversation files
An agent with a workspace on a sandbox gives each user-token conversation its own folder. Your backend can seed it before the first message and read what the agent left there, with the runtime key and the user's token, on the agent's URL plus /files:
curl -X PUT "$AGENT_URL/files?agentId=$AGENT_ID&conversationKey=chat-1" \
-H "Authorization: Bearer $BROODS_API_KEY" -H "X-Broods-User-Token: $USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"files":[{"path":"notes/todo.md","contentBase64":"LSBzaGlwCg=="}]}'
curl "$AGENT_URL/files?agentId=$AGENT_ID&conversationKey=chat-1" \
-H "Authorization: Bearer $BROODS_API_KEY" -H "X-Broods-User-Token: $USER_TOKEN"
PUT replaces the whole folder; GET answers { files: [{ path, contentBase64 }] }. ?workspace=<name> picks a workspace other than the first. Without a user token it answers 403 user_token_required: the root folder is yours, not a visitor's.
Errors
{
"error": {
"message": "...",
"type": "permission_error",
"code": "public_access_disabled",
"param": "agentId"
}
}
Branch on code, never on message. Each response also carries an X-Request-Id header. Quote it when reporting a problem.
| Status | code | Cause |
|---|---|---|
| 401 | unauthorized | Missing or wrong credential, or a key for another scope |
| 403 | public_access_disabled | The agent does not set publicAccess: true |
| 403 | run_overrides_disabled | system or model sent without allowRunOverrides: true |
| 403 | run_token_scope | A run token did anything but read its own agent's runs |
| 403 | status_access_denied | The run's status is not readable from this deployment, such as a subagent run started under another deployment, or another user's run |
| 403 | user_token_required | The agent requires a user token with the runtime key and none was sent |
| 403 | user_token_conversation | The user token lists its conversations and this conversationKey is not one |
| 404 | run_not_found | Unknown run id |
| 409 | conversation_busy | Busy conversation in reject mode |
| 409 | idempotency_conflict | Same idempotency key, different payload |
| 429 | ingress_capacity | Conversation queue is full |
| 503 | service_unavailable | POST /v1/runs when the deployment's run queue is full. Nothing is recorded or counted; retry after Retry-After. A plan refusal wins |
On a streamed run, conversation_busy, idempotency_conflict, ingress_capacity and service_unavailable arrive as the only SSE error frame instead of a JSON body, with the same HTTP status, code and Retry-After. The frame names the error class errorType, since its type is error:
data: {"type":"error","error":"Conversation is already processing another turn. Try again when the current turn finishes.","code":"conversation_busy","errorType":"conflict_error"}
Python example
import json
import requests
response = requests.post(
url="https://gateway.broods.app/v1/runs",
headers={"Authorization": f"Bearer {api_key}"},
json={
"agentId": "agent_...",
"eventId": "req-001",
"conversationKey": "my-conversation",
"events": [{"role": "user", "content": [{"type": "text", "text": "Hello"}]}],
},
stream=True,
)
for line in response.iter_lines():
if line.startswith(b"data: "):
part = json.loads(line[6:])
if part.get("type") == "text-delta":
print(part["text"], end="")
WebSocket
Connect to wss://gateway.broods.app/v1/agents/{endpointId}/ws, or the scoped form /v1/projects/{project}/stages/{stage}/agents/{endpointId}/ws. Send the key as subprotocols, not in the URL:
Sec-WebSocket-Protocol: broods.v1, broods.token.<runtime key>
The server answers broods.v1. A proxy in front of the gateway must not log request headers. A ?token= query parameter is ignored. A user token rides as one more entry, broods.user.<token>, and holds for every frame on the socket: meta then names the conversation as bsu:<userId>:<key>.
The key opens a socket for its own stage only; another stage's path answers 403 before the upgrade. Each frame on the socket is checked like the matching HTTP call: an execute on an agent without publicAccess: true gets an error frame with status: 403, and an attach to its run gets replay_unavailable.
Client frames
| Frame | Purpose |
|---|---|
execute | Starts a run with agentId, sessionId, eventId, events or answers, optional mode, idempotencyKey, system, model |
control | Adds input to the live run with requestId, eventId, events, and mode, default steer |
attach | Reattaches to a run with requestId, agentId, conversationKey, eventId, runId, optional afterCursor |
cancel | Stop reading now. The in-flight step's output is dropped |
{
"type": "control",
"requestId": "r2",
"eventId": "event-2",
"idempotencyKey": "op-2",
"events": []
}
Server frames
| Frame | Meaning |
|---|---|
meta | { sessionId, taskId }. The socket is ready |
output | { eventId, cursor, replay, data }. data is one stream part |
ack | A control input, or an execute that queued, was durably accepted |
status | Later state of that input, with appliedMode and appliedToEventId |
attached | Attach accepted, with replayFromCursor and replayThroughCursor |
replay_unavailable | The cursor cannot be resumed. Read the final result from statusUrl |
done, error | The run ended. An error core refused carries status and code |
Besides AI SDK parts, output.data can be question-request (questions, answer with an execute carrying answers), tool-approval-request (approvals) and waiting (a heartbeat while async work is pending).
{ "type": "ack", "requestId": "r2", "eventId": "event-2", "status": "queued" }
{ "type": "status", "requestId": "r2", "eventId": "event-2", "status": "applied", "appliedMode": "steer", "appliedToEventId": "event-1" }
A socket holds up to 8 control inputs that have not yet reached applied or a terminal status. One more gets a status frame with status: "failed". Send it again once an earlier one settles. An output part larger than 1 MB arrives as its type with truncated: true and no payload, so a done still ends the stream. Read the full result from the run status.
Resume after a disconnect
Output is kept for about 3 minutes, up to 2,000 frames per conversation. Store the cursor of the last output frame you fully processed, then reconnect and send attach with afterCursor. Frames up to replayThroughCursor carry replay: true. Later frames are live. When the cursor is too old or belongs to another event, or the attach names an agentId, conversationKey or eventId that is not the run's own, the server sends replay_unavailable and you read the final result from GET /v1/runs/{runId}. A busy execute that gets queued receives its ack, stays open, and streams once its turn starts.
Channel webhooks
Providers post to one URL per account and channel type. broods dev and broods deploy print it after each sync. The production and per-stage URL forms are in Channels.