Skip to main content

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

EndpointAccepts
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 WebSocketRuntime key or a stage session ticket
/v1/* config routesAccount key, or a role session within its policy
Logs and traces socketStage 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:

VariableValue
BROODS_RUN_TOKENBearer that reads this agent's runs. Expires shortly after the run's time budget
BROODS_AGENT_IDThe agent the run acts as
BROODS_ACCOUNT_IDIts account
BROODS_BASE_URLThe 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?" }] }
]
}'
FieldRequiredDescription
agentIdyesAgent to run
eventIdyesYour correlation id
conversationKeyyesConversation to continue or create
eventsyes, unless answers or continueAI SDK messages. Roles user, tool, and system with persist: false
backgroundnotrue answers 202 with a run id instead of streaming
modenoBusy-conversation behavior, one of steer, the default, followup, collect, reject
idempotencyKeynoRetry identity. Defaults to eventId, bound for 7 days
systemnoOne-turn system message or list, not stored
modelnoPer-run call settings such as temperature, maxOutputTokens, reasoning, providerOptions. provider, modelId, output and apiKey are rejected
answersnoAnswers to open ask_questions prompts. Cannot be combined with events
continuenoRe-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.

statusMeaning
accepted, queued, applied, processingNot finished
awaiting_approvalapprovals lists tool calls waiting for approval
awaiting_inputquestions lists open ask_questions prompts
completedresponse and result hold the answer
failederror explains. stoppedByUser: true marks a deliberate /stop
expiredQueued 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:

ModeBehavior
steerJoins the live run at its next step. Becomes a follow-up if the run has no step left
followupRuns as its own turn after earlier work
collectQueued messages merge into one later turn
rejectRefused 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.

StatuscodeCause
401unauthorizedMissing or wrong credential, or a key for another scope
403public_access_disabledThe agent does not set publicAccess: true
403run_overrides_disabledsystem or model sent without allowRunOverrides: true
403run_token_scopeA run token did anything but read its own agent's runs
403status_access_deniedThe run's status is not readable from this deployment, such as a subagent run started under another deployment, or another user's run
403user_token_requiredThe agent requires a user token with the runtime key and none was sent
403user_token_conversationThe user token lists its conversations and this conversationKey is not one
404run_not_foundUnknown run id
409conversation_busyBusy conversation in reject mode
409idempotency_conflictSame idempotency key, different payload
429ingress_capacityConversation queue is full
503service_unavailablePOST /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​

FramePurpose
executeStarts a run with agentId, sessionId, eventId, events or answers, optional mode, idempotencyKey, system, model
controlAdds input to the live run with requestId, eventId, events, and mode, default steer
attachReattaches to a run with requestId, agentId, conversationKey, eventId, runId, optional afterCursor
cancelStop reading now. The in-flight step's output is dropped
{
"type": "control",
"requestId": "r2",
"eventId": "event-2",
"idempotencyKey": "op-2",
"events": []
}

Server frames​

FrameMeaning
meta{ sessionId, taskId }. The socket is ready
output{ eventId, cursor, replay, data }. data is one stream part
ackA control input, or an execute that queued, was durably accepted
statusLater state of that input, with appliedMode and appliedToEventId
attachedAttach accepted, with replayFromCursor and replayThroughCursor
replay_unavailableThe cursor cannot be resumed. Read the final result from statusUrl
done, errorThe 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.