docs: broker HTTP / WS API reference#865
Merged
Merged
Conversation
The broker's listen API (port 3888 by default) is what the dashboard,
the CLI, the SDKs, and any custom integration call to spawn agents,
inject PTY input, subscribe to events, and shut the broker down. None
of that surface was documented anywhere outside the source.
Adds `reference-broker-api` covering:
- base URL / port / `--api-bind` flag
- auth model: `X-API-Key` or `Bearer`, `RELAY_BROKER_API_KEY` env,
unauthenticated fallback when unset, `/health` exempt
- all 22 routes grouped as Health/Config, Agent lifecycle, PTY
interaction, Event stream — with body shapes for the ones a
caller would actually compose by hand (`/api/spawn`, `/api/send`,
`/api/input/{name}`)
- `/ws` protocol: ping cadence, `?sinceSeq=` resume, `replay_gap`
frame, full inventory of durable + ephemeral event `kind`s
- worked end-to-end curl + websocat example to spawn, observe,
drive, message, and release an agent
- error envelope and common codes
Mirrors to `docs/reference-broker-api.md` per `.claude/rules/docs-sync.md`.
Adds the slug to the CLI nav group in `web/lib/docs-nav.ts`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis PR adds comprehensive API reference documentation for the agent-relay-broker, consisting of a new MDX page detailing the HTTP and WebSocket listen API surface with authentication, endpoint specifications, event streaming, and error handling. It integrates the documentation into the CLI navigation menu and updates the documentation governance policy to establish MDX as the single source of truth. ChangesBroker API Documentation and Governance
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/reference-broker-api.md`:
- Around line 29-32: Update the two fenced code blocks so they include a
language identifier to satisfy MD040: change the credentials/header block
containing "X-API-Key: <token> Authorization: Bearer <token>" to use a ```http
fence, and change the websocket example "ws://localhost:3888/ws?sinceSeq=12345"
to use a ```text (or ```http) fence; also apply the same change to the other
identical fenced block later in the file so all similar fences include a
language tag.
In `@web/content/docs/reference-broker-api.mdx`:
- Around line 30-33: The MDX code fences lack explicit fence languages; update
the blocks containing "X-API-Key: <token>\nAuthorization: Bearer <token>" to use
a language like http (```http) and the block with
"ws://localhost:3888/ws?sinceSeq=12345" to use a neutral text language (```text)
so the doc linter and markdown source stay in sync; locate these exact blocks in
reference-broker-api.mdx and replace the opening triple backticks with the
appropriate fenced language tokens.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 3ab98c70-7630-4725-9cc4-75516389533b
📒 Files selected for processing (3)
docs/reference-broker-api.mdweb/content/docs/reference-broker-api.mdxweb/lib/docs-nav.ts
Comment on lines
+29
to
+32
| ``` | ||
| X-API-Key: <token> | ||
| Authorization: Bearer <token> | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add fence languages to satisfy markdown linting (MD040).
Both fenced blocks are missing a language identifier, which matches the lint warnings and can fail docs quality gates.
Suggested patch
-```
+```http
X-API-Key: <token>
Authorization: Bearer <token>@@
- +text
ws://localhost:3888/ws?sinceSeq=12345
Also applies to: 153-155
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 29-29: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference-broker-api.md` around lines 29 - 32, Update the two fenced
code blocks so they include a language identifier to satisfy MD040: change the
credentials/header block containing "X-API-Key: <token> Authorization: Bearer
<token>" to use a ```http fence, and change the websocket example
"ws://localhost:3888/ws?sinceSeq=12345" to use a ```text (or ```http) fence;
also apply the same change to the other identical fenced block later in the file
so all similar fences include a language tag.
Comment on lines
+30
to
+33
| ``` | ||
| X-API-Key: <token> | ||
| Authorization: Bearer <token> | ||
| ``` |
Contributor
There was a problem hiding this comment.
Mirror file has the same missing fence-language issue.
These code fences also need explicit languages to keep the MDX page lint-clean and in sync with the markdown source.
Suggested patch
-```
+```http
X-API-Key: <token>
Authorization: Bearer <token>@@
- +text
ws://localhost:3888/ws?sinceSeq=12345
Also applies to: 154-156
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@web/content/docs/reference-broker-api.mdx` around lines 30 - 33, The MDX code
fences lack explicit fence languages; update the blocks containing "X-API-Key:
<token>\nAuthorization: Bearer <token>" to use a language like http (```http)
and the block with "ws://localhost:3888/ws?sinceSeq=12345" to use a neutral text
language (```text) so the doc linter and markdown source stay in sync; locate
these exact blocks in reference-broker-api.mdx and replace the opening triple
backticks with the appropriate fenced language tokens.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 633aa2a52b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+233
to
+236
| Failed responses return a consistent envelope: | ||
|
|
||
| ```json | ||
| { |
There was a problem hiding this comment.
This section says all failures use the nested error.code/message/statusCode envelope, but many protected endpoints actually return {"success": false, "error": "..."} instead (for example /api/send and /api/spawn paths in src/listen_api.rs). Consumers implementing error parsing from this doc will mis-handle common non-2xx responses unless the docs describe both formats (or scope this envelope to the endpoints that really use it).
Useful? React with 👍 / 👎.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
6 issues found across 3 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/reference-broker-api.md">
<violation number="1" location="docs/reference-broker-api.md:93">
P2: `cli` is documented as required, but the server defaults it to `"claude"` when omitted; only `name` is required.</violation>
<violation number="2" location="docs/reference-broker-api.md:111">
P2: The JSON curl examples omit `Content-Type: application/json`, so copied requests can fail with 415 before reaching these handlers.</violation>
<violation number="3" location="docs/reference-broker-api.md:232">
P2: The docs currently overstate error-shape consistency; multiple endpoints still return `{ success: false, error: "..." }` instead of the nested `error` envelope.</violation>
</file>
<file name="web/content/docs/reference-broker-api.mdx">
<violation number="1" location="web/content/docs/reference-broker-api.mdx:117">
P2: `/api/input/{name}` is documented as returning 404 for missing agents, but the handler currently returns 400 (`agent_not_found`).</violation>
<violation number="2" location="web/content/docs/reference-broker-api.mdx:207">
P2: POST examples with JSON bodies are missing `Content-Type: application/json`, which can cause Axum to reject the requests.</violation>
<violation number="3" location="web/content/docs/reference-broker-api.mdx:233">
P2: The docs claim a single consistent error envelope, but the API currently returns multiple error formats across endpoints.</violation>
</file>
Tip: instead of fixing issues one by one fix them all with cubic
Re-trigger cubic
| -d '{"data":"hello\n"}' | ||
| ``` | ||
|
|
||
| Returns 404 if the agent isn't found. |
There was a problem hiding this comment.
P2: /api/input/{name} is documented as returning 404 for missing agents, but the handler currently returns 400 (agent_not_found).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/reference-broker-api.mdx, line 117:
<comment>`/api/input/{name}` is documented as returning 404 for missing agents, but the handler currently returns 400 (`agent_not_found`).</comment>
<file context>
@@ -0,0 +1,247 @@
+ -d '{"data":"hello\n"}'
+```
+
+Returns 404 if the agent isn't found.
+
+#### `POST /api/send`
</file context>
Suggested change
| Returns 404 if the agent isn't found. | |
| Returns 400 with code `agent_not_found` if the agent isn't found. |
|
|
||
| ## Error envelope | ||
|
|
||
| Failed responses return a consistent envelope: |
There was a problem hiding this comment.
P2: The docs claim a single consistent error envelope, but the API currently returns multiple error formats across endpoints.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/reference-broker-api.mdx, line 233:
<comment>The docs claim a single consistent error envelope, but the API currently returns multiple error formats across endpoints.</comment>
<file context>
@@ -0,0 +1,247 @@
+
+## Error envelope
+
+Failed responses return a consistent envelope:
+
+```json
</file context>
| agent-relay up --port 3888 & | ||
|
|
||
| # 2. Spawn Alice running claude | ||
| curl -sX POST localhost:3888/api/spawn \ |
There was a problem hiding this comment.
P2: POST examples with JSON bodies are missing Content-Type: application/json, which can cause Axum to reject the requests.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/reference-broker-api.mdx, line 207:
<comment>POST examples with JSON bodies are missing `Content-Type: application/json`, which can cause Axum to reject the requests.</comment>
<file context>
@@ -0,0 +1,247 @@
+agent-relay up --port 3888 &
+
+# 2. Spawn Alice running claude
+curl -sX POST localhost:3888/api/spawn \
+ -H "X-API-Key: $KEY" \
+ -d '{"name":"Alice","cli":"claude"}'
</file context>
`docs/*.md` is a partial mirror that's gone stale long ago (5 pages there vs 40+ in `web/content/docs/`) and is no longer maintained. The Next.js site under `web/` reads `web/content/docs/*.mdx` directly — that's the source of truth. This PR followed the old `.claude/rules/docs-sync.md` rule and created a `docs/reference-broker-api.md` mirror. Dropping it here along with rewriting the rule so future doc PRs aren't sent down the same wrong path. The canonical reference at `web/content/docs/reference-broker-api.mdx` is untouched. Cleaning up the existing legacy pages in `docs/` is a separate task. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
willwashburn
added a commit
that referenced
this pull request
May 17, 2026
The previous version of `web/content/docs/reference-broker-api.mdx` on this branch only contained the new Snapshots section — it assumed the full broker API reference (which exists on PR #865's branch as 247 lines covering auth, routes, /ws, error envelope) was already on main. It isn't. If this PR merges first, the published docs page would have only a header + the snapshot section, missing the rest of the API surface. Folds PR #865's full reference content in and slots the snapshot section under "Routes" between "PTY interaction" and "Event stream" (promoted from `##` to `###` to match the section's nesting). Adds a snapshot step to the end-to-end worked example so the new endpoint is exercised there too. Also brings the `.claude/rules/docs-sync.md` rewrite from PR #865 onto this branch — the old "mirror to /docs/*.md" rule was what sent the first version of this doc down the wrong path. Either merge order now works: if PR #865 lands first there's a trivial conflict on the duplicated base content; if this PR lands first the doc is already complete. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
reference-broker-apicovering the broker's listen API surface (port 3888 by default): auth model, all 22 routes grouped by purpose, full request/response shapes for the ones a caller would compose by hand, and the/wsprotocol (?sinceSeq=resume,replay_gapframe, full inventory of durable + ephemeral eventkinds).curl + websocatexample so you can spawn → observe → drive → message → release an agent without going through the dashboard.docs/reference-broker-api.mdper.claude/rules/docs-sync.md.web/lib/docs-nav.ts.Why
None of the broker's HTTP/WS surface was documented anywhere outside the source. That made it invisible to anyone trying to build a custom integration, debug a flow, or even understand what the dashboard talks to. It also blocks the work in #864 (
view/drivesubcommands) — the clients are thin wrappers around this API, and a doc reviewer needs to be able to see the surface they wrap.Notes
/api/spawn,/api/release,/api/metrics, …) delegate to the broker over an internal channel; their full success payload isn't easily extracted from the handler code, so the doc gives the body shapes and statuses but stays vague on success-response fields. Fine for now; can tighten as we use them.kinds came from greppingjson!({\"kind\": ...})acrosssrc/. The durable vs ephemeral split is enforced inbroadcast_if_relevant(src/listen_api.rs:1291).Test plan
web/lib/docs-nav.tschange renders the new page in the docs sidebar under "CLI"docs/reference-broker-api.mdandweb/content/docs/reference-broker-api.mdxstay in sync (no content drift between them)Related: #864 (view/drive subcommands — depends on this surface being discoverable).