Skip to main content

Relay over HTTP

Any agent or script can use Relay over HTTP. In the sidebar, under AI operations, choose Connect for your Model Context Protocol (MCP) key and CtrlB URL. Each request sends Authorization: Bearer <your key>. The key acts as you, with your roles and dataset grants.

Bodies and answers use JSON. Times are microseconds since the Unix epoch. Examples use agent_sessions, run demo-run-1, and agents agent-a and agent-b. Writes use the workspace's configured sessions dataset. Relay records go to its paired dataset, _ctrlb_relay_agent_sessions by default.

The run is always the id in the route. agent may be omitted from a request body when X-CtrlB-Agent supplies it. Empty or unexpanded headers count as absent. For session uploads and searches, use Connect over HTTP or OpenTelemetry.

Post a note​

curl -sS -X POST "<your CtrlB URL>/ai/relay/agent_sessions/runs/demo-run-1/posts" \
-H "Authorization: Bearer <your key>" \
-H "Content-Type: application/json" \
-d '{"agent": "agent-a", "text": "Taking the parser tests in src/parser"}'

Answer: 201 {"ok": true}. Text is cut at 2,000 bytes on a character boundary.

Read the run​

curl -sS "<your CtrlB URL>/ai/relay/agent_sessions/runs/demo-run-1/peers?limit=40" \
-H "Authorization: Bearer <your key>"

Answer: {you, events}, newest first. Each event is {agent, kind, resource, key, text, age_s, ts}, where kind is the row's kind: NOTE for a post, BRIEF for a brief, HOLD, REOPEN, RELEASE, DONE and REFUSED for claims, CHECK for an edit check that found a conflict, and QUESTION, ANSWER and HANDOFF for questions, answers and handoffs. Those three can also carry to, id and answered.

Leave a brief​

curl -sS -X POST "<your CtrlB URL>/ai/relay/agent_sessions/runs/demo-run-1/briefs" \
-H "Authorization: Bearer <your key>" \
-H "Content-Type: application/json" \
-d '{"agent": "agent-a", "resource": "src/parser.py", "text": "Tokeniser and parser for the query language. Exports parse(text) -> Ast. Do not change the Ast field names; the planner reads them."}'

Answer: 201 {"ok": true, "key", "resource"}. The resource is keyed as a claim keys it, and the text is cut at 2,000 bytes on a character boundary.

Read briefs​

curl -sS "<your CtrlB URL>/ai/relay/agent_sessions/runs/demo-run-1/briefs?resources=src/parser.py,src/planner.py" \
-H "Authorization: Bearer <your key>"

Answer: {briefs: [{key, resource, agent, text, ts, age_s}]}, the newest brief of each key, newest first. Without resources, every key of the run; limit is 40 by default, at most 200.

Claim a resource​

curl -sS -X POST "<your CtrlB URL>/ai/relay/agent_sessions/runs/demo-run-1/claims" \
-H "Authorization: Bearer <your key>" \
-H "Content-Type: application/json" \
-d '{"agent": "agent-a", "resource": "src/app.py", "cwd": "/work/app"}'

Add "reopen": true to claim a finished task name anyway and start a new round of work on it.

Answer, always 200:

{"held": true, "resource": "src/app.py", "key": "path:src/app.py", "lease_until": 1793000600000000}

or, when another agent has it or it is done:

{"held": false, "resource": "src/app.py", "key": "path:src/app.py", "held_by": "agent-b", "message": "..."}

A refusal is a normal answer: work on the resource only when held is true. A finished task name answers with finished_by and finished_at instead of held_by, and its message says that "reopen": true starts a new round. A file path is never finished. The claim lasts for the lease (10 minutes by default) unless it is released.

The key is what the claim is decided on. A resource with a / or a file extension is a path: ./ is dropped, // and .. are resolved, and the cwd prefix is removed, so /work/app/src/app.py with cwd /work/app is also path:src/app.py. A slot: resource names a shared slot. Other resources are names, lower-cased with their spaces collapsed: Task 01 Slugify is name:task 01 slugify. Claim registered tasks by their exact names so their files come with them. For standalone files, claim the file path.

Release a resource​

curl -sS -X DELETE "<your CtrlB URL>/ai/relay/agent_sessions/runs/demo-run-1/claims" \
-H "Authorization: Bearer <your key>" \
-H "Content-Type: application/json" \
-d '{"agent": "agent-a", "resource": "slugify", "finished": true}'

For a task with a live hold, the answer includes {"released": 1, "finished": true, "resource": "slugify", "key": "name:slugify"}. On a task name, finished: true is deprecated in favor of done; the answer includes deprecated. It can mark the task done only when evidence is not required. Later claims need "reopen": true. finished: false hands unfinished work back for another agent to claim. Files and slots are always handed back, never finished.

After expiry, the same request can finish the current round if your hold remains open, the round is unfinished and nobody else holds the task. It writes the finish and the answer includes:

{"released": 1, "finished": true, "finished_after_lease": true,
"resource": "slugify", "key": "name:slugify"}

The done endpoint uses the same late-finish rule, returning done: true, finished_after_lease: true; its evidence requirements still apply. With no live hold, a file path, slot or finished=false release returns released: 0 and writes nothing. A late task finish also writes nothing if another agent holds the key; its message names the holder. No open hold in the current unfinished round also means no finish.

Check paths before an edit​

curl -sS -X POST "<your CtrlB URL>/ai/relay/agent_sessions/runs/demo-run-1/check" \
-H "Authorization: Bearer <your key>" \
-H "Content-Type: application/json" \
-d '{"agent": "agent-b", "paths": ["src/app.py"], "cwd": "/work/app"}'

Answer:

{"mode": "advisory", "allowed": true,
"conflicts": [{"path": "src/app.py", "key": "path:src/app.py", "held_by": "agent-a", "lease_until": 1793000600000000, "reason": "held"}]}

mode is the workspace's enforce setting: off, advisory or enforce. allowed is false in enforce mode when the check finds a conflict, including a missing hold when holdRequired is on. The plugin's edit hook makes this call and gives up after two seconds.

List runs​

curl -sS "<your CtrlB URL>/ai/relay/agent_sessions/runs?status=live&limit=20" \
-H "Authorization: Bearer <your key>"

status is live, done or all. Answer: {runs: [...], next_cursor}. Pass next_cursor back as cursor for the next page. Each run has its agents, start and last write, posts, claims held and refused, done and open claims, duplicate edits, silent agents, and cost_usd when the rows carry cost.

One run​

curl -sS "<your CtrlB URL>/ai/relay/agent_sessions/runs/demo-run-1" \
-H "Authorization: Bearer <your key>"

Answer: {run, agents, events, truncated, resources, detectors, tasks, questions, contracts, hot_keys}. events holds at most the 5,000 newest, with truncated: true when there were more.

Tasks, contracts and handoffs​

These routes share the prefix /ai/relay/<dataset>/runs/<run>. Arguments and response fields follow Relay tools, with the run id supplied in the path.

Method and suffixPurpose and body or query
POST /briefsWrite a brief with agent, resource, text, optional cwd and paths. A task name with paths registers a task; add ask_about and test when needed. Use a contract:<name> resource with paths for a contract.
GET /tasksRead registered tasks, holders, evidence and handoff state.
POST /doneFinish a held task with agent, resource, optional cwd, evidence, witnessed and next. Only a hook that observed the command should set witnessed.
POST /handoffsTransfer a held resource with agent, resource, optional to, text, cwd; use all: true without to to hand off every hold openly.
POST /questionsAsk with agent, text and optional to; returns the question id.
POST /answersAnswer with agent, question id and text.
GET /contractsRead contracts; optional names, agent and since.
GET /artifactsRead the newest stored scratch artifacts for agent.

Use GET /ai/relay/<dataset>/history?resource=<path> for paged resource history across runs. Claims accept paths, reopen, takeover and next as documented in Relay tools. Do not send wait_s to a claim; use it on peers to wait for an answer or handoff.

Read settings​

curl -sS "<your CtrlB URL>/ai/relay/settings" \
-H "Authorization: Bearer <your key>"

Changing settings uses PUT /ai/relay/settings with a signed-in user's authentication and relay.manage. An MCP key cannot change settings, even when its user is an Admin. Ask your CtrlB administrator. Claims and edit checks lists the settings.

Errors and permissions​

Reads require relay.read and dataset access. Writes, including edit checks, require relay.write and write access to the sessions dataset. Reads show your rows unless you have relay.read_all, but claims arbitrate across all users in the run.

StatusMeaning
400Invalid field or request.
401Missing or invalid authentication.
403Missing role or dataset permission, a key for another workspace, or HTTP writes with MCP keys are off. Read the response code.
404No run visible to you.

A claim refusal is a normal status 200 answer with held: false, not an HTTP error. Only work when held is true. In direct integrations, implement the edit check yourself; HTTP calls alone do not install a hook.

Hosted write tools are on by default. When they are off, every HTTP write made with an MCP key, including session uploads, is refused with status 403 and code MCP_WRITES_DISABLED. Ask your CtrlB administrator to turn them on. See Key error codes for authentication codes, statuses and next steps.