# Review Room Agent API ## ChatGPT, Codex, And Claude MCP Setup Production MCP URL: `https://proof-sdk-psi.vercel.app/mcp` Discovery JSON: `https://proof-sdk-psi.vercel.app/.well-known/agent.json` Claude/Cowork plugin download: `https://proof-sdk-psi.vercel.app/review-room/claude-plugin.zip` ### ChatGPT In ChatGPT, enable developer mode if your workspace allows it, then create a connector with the MCP URL above. The connector URL should be the public `/mcp` endpoint. ChatGPT scans the server's advertised tools during connector creation. Use a shared Review Room document URL, or pass the document slug and token in tool arguments. Write actions may ask for confirmation in ChatGPT. ### Codex Codex supports streamable HTTP MCP servers in `config.toml`: ```toml [mcp_servers.review_room] url = "https://proof-sdk-psi.vercel.app/mcp" ``` Start a new Codex thread after updating config, then provide a Review Room document URL or slug plus token. ### Claude/Cowork In Claude, either install the plugin above or add a custom connector using streamable HTTP transport and paste the MCP URL. Document access is per tool call: pass the shared Review Room document slug and token in tool arguments, or send the token as `Authorization: Bearer `. Treat share tokens as secrets. Do not paste tokens into comments, suggestions, generated documents, or public logs. The browser page at `/agent-docs` includes a **Copy MCP URL** button. Agents can request this same URL with `Accept: text/markdown` to receive plain Markdown. The Review Room MCP currently exposes: - `review_room_get_state` - `review_room_add_comment` - `review_room_reply_comment` - `review_room_resolve_comment` - `review_room_add_suggestion` - `review_room_accept_suggestion` - `review_room_reject_suggestion` ## Agent Routes Hosted Review Room supports both the `/api/agent/*` invite routes and the reusable `/documents/*` routes. The reusable document API surface is mounted in parallel at: - `POST /documents` - `GET /documents/:slug/state` - `GET /documents/:slug/snapshot` - `POST /documents/:slug/ops` - `POST /documents/:slug/presence` - `GET /documents/:slug/events/pending` - `POST /documents/:slug/events/ack` - `GET /documents/:slug/bridge/state` - `GET /documents/:slug/bridge/marks` - `POST /documents/:slug/bridge/comments` - `POST /documents/:slug/bridge/suggestions` - `POST /documents/:slug/bridge/rewrite` - `POST /documents/:slug/bridge/presence` ## Which Editing Method Should I Use? Review Room has three editing approaches. **Pick one — don't mix them.** | Goal | Method | Endpoint | |------|--------|----------| | **Propose edits for human review** | Suggestion marks | `POST /ops` with `suggestion.add` or `POST /bridge/suggestions` | | **Add/replace/insert a few lines** (recommended) | Edit V2 (block-level) | `GET /snapshot` → `POST /edit/v2` | | **Simple text replacement** | Structured edit | `POST /edit` | | **Replace entire document directly** | Rewrite | `POST /ops` with `rewrite.apply` | | **Add a comment** | Ops | `POST /ops` with `comment.add` | If the human asked for revisions, proposed edits, review, or anything they should accept/reject, use `suggestion.add`. Do not use `rewrite.apply` or `/bridge/rewrite` for that flow: rewrite applies content directly and the human will see it as an agent-authored document update, not as pending proposed edits. **Start with `suggestion.add`** for proposed edits the human should review. Use Edit V2 for direct-apply tasks only; it uses stable block refs, handles concurrent edits cleanly, and returns clean markdown without internal HTML annotations. `suggestion.add` now matches against annotated documents correctly and preserves stable anchors. Use `edit/v2` only for direct-apply changes the human explicitly requested, not for reviewable proposed edits. `rewrite.apply` is still disruptive. It is a direct apply operation, not track changes. Avoid it if anyone might have the document open: hosted environments block rewrites while live authenticated collaborators are connected, and `force` is ignored there. ## I Just Received A Review Room Link No browser automation is required. Use HTTP directly (for example, `curl` or your tool's `web_fetch`). If you received a shared link like: https://proof-sdk-psi.vercel.app/d/?token= You can discover the API and read the document in one step using **content negotiation** on that same URL. Fetch JSON (recommended): curl -H "Accept: application/json" "https://proof-sdk-psi.vercel.app/d/?token=" Fetch raw markdown: curl -H "Accept: text/markdown" "https://proof-sdk-psi.vercel.app/d/?token=" The JSON response includes: - `markdown` (document content) - `_links` (state, ops, docs) - `agent.auth` hints (how to use the token) ### Quick copy/paste flow (token already in the shared URL) ```bash SHARE_URL='https://proof-sdk-psi.vercel.app/d/?token=' TOKEN='' SLUG='' curl -H "Accept: application/json" "$SHARE_URL" curl -H "Accept: text/markdown" "$SHARE_URL" curl -H "Authorization: Bearer $TOKEN" -H "X-Agent-Id: your-agent" "https://proof-sdk-psi.vercel.app/documents/$SLUG/state" ``` ## Auth: Token From URL If a URL contains `?token=`, treat it as an access token: - Preferred: `Authorization: Bearer ` - Also accepted: `x-share-token: ` ## Legacy GET-only Agent Fallback Disabled by default. These routes perform mutations via GET and accept tokens in query strings, so deployments must opt in with `PROOF_ADVERTISE_GET_ONLY_ACTIONS=1`; otherwise they return `405 GET_ACTIONS_DISABLED`. Use the Review Room MCP endpoint at `/mcp` or POST `/ops` / `/bridge/suggestions` instead. When enabled: some agent sandboxes can read URLs but cannot send POST requests with headers or bodies; only in that environment, use the constrained GET action endpoint for comments and pending suggestions: ```text GET /api/agent//action?token=&type=suggestion.add&kind=replace"e=&content=&by=ai: ``` The first GET returns `CONFIRM_REQUIRED` plus an `execute.href`. Fetch that `execute.href` to apply the mutation. This endpoint only supports `comment.add` and pending `suggestion.add`; it does not support rewrites or accepted/direct-apply suggestions. If your URL length cap is tight, fetch state with the token first and use `agent.getActionAlias` plus draft chunks: ```text GET /api/agent//state?token= GET /api/agent//action/draft?a=&d=s1&f=content&i=0&t= GET /api/agent//action/draft?a=&d=s1&f=content&i=1&t= GET /api/agent//action?a=&type=suggestion.add&kind=replace"e=&contentDraft=s1&by=ai: ``` For comments, upload `f=text` chunks and use `textDraft=s1`. The draft endpoint also accepts `f=quote` with `quoteDraft=s1` when the quote itself is too long. The first `/action` GET still returns `CONFIRM_REQUIRED`; fetch its `execute.href` to apply. ## Edit Via Ops (Comments, Suggestions, Rewrite) Use: POST /documents//ops `by` controls authorship. Presence is explicit-only: send `X-Agent-Id: ` (or `agentId` in the JSON body) when you want the agent to appear in presence. Add a comment: curl -X POST "https://proof-sdk-psi.vercel.app/documents//ops?token=" \ -H "Content-Type: application/json" \ -H "X-Agent-Id: your-agent" \ -d '{"type":"comment.add","by":"ai:your-agent","quote":"text to anchor","text":"comment body"}' Suggest a replace: curl -X POST "https://proof-sdk-psi.vercel.app/documents//ops?token=" \ -H "Content-Type: application/json" \ -H "X-Agent-Id: your-agent" \ -d '{"type":"suggestion.add","by":"ai:your-agent","kind":"replace","quote":"old text","content":"new text"}' Suggest an insert after an anchor: curl -X POST "https://proof-sdk-psi.vercel.app/documents//ops?token=" \ -H "Content-Type: application/json" \ -H "X-Agent-Id: your-agent" \ -d '{"type":"suggestion.add","by":"ai:your-agent","kind":"insert","quote":"Last sentence of the previous section.","content":"\n\n## New section\n\nNew section body."}' `kind:"insert"` always inserts `content` immediately after `quote`. Include leading/trailing blank lines for block inserts so Markdown headings and paragraphs do not concatenate. To add a new section before an existing heading, prefer `kind:"replace"` and replace the existing heading with the new section followed by the same heading. Create and immediately apply a suggestion: curl -X POST "https://proof-sdk-psi.vercel.app/documents//ops?token=" \ -H "Content-Type: application/json" \ -H "X-Agent-Id: your-agent" \ -d '{"type":"suggestion.add","by":"ai:your-agent","kind":"replace","quote":"old text","content":"new text","status":"accepted"}' Rewrite the whole document: curl -X POST "https://proof-sdk-psi.vercel.app/documents//ops?token=" \ -H "Content-Type: application/json" \ -H "X-Agent-Id: your-agent" \ -d '{"type":"rewrite.apply","by":"ai:your-agent","content":"# New markdown..."}' Only use rewrite when the user explicitly wants direct application. For reviewable revisions, send one or more `suggestion.add` operations instead. ## Edit Via Structured Operations (Append, Replace, Insert) For surgical edits without rewriting the entire document, use the `/edit` endpoint: POST /documents//edit All requests require `Content-Type: application/json` and auth via `Authorization: Bearer `. The body must include an `operations` array (max 50 ops) and a `by` field for authorship. If you want presence, also send `X-Agent-Id: ` or `agentId` in the body. ### Append to a section Add content at the end of a named section (matched by heading text): curl -X POST "https://proof-sdk-psi.vercel.app/documents//edit" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "X-Agent-Id: your-agent" \ -d '{ "by": "ai:your-agent", "operations": [ {"op": "append", "section": "Brandon", "content": "\n\n**Feb 16, 2026**\n\nNew brainstorm idea here."} ] }' The `section` value is matched against heading text (e.g., `"Brandon"` matches `### Brandon`). ### Replace text Find and replace a specific string in the document: curl -X POST "https://proof-sdk-psi.vercel.app/documents//edit" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "X-Agent-Id: your-agent" \ -d '{ "by": "ai:your-agent", "operations": [ {"op": "replace", "search": "old text to find", "content": "new replacement text"} ] }' ### Insert after text Insert content after a specific anchor string: curl -X POST "https://proof-sdk-psi.vercel.app/documents//edit" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "X-Agent-Id: your-agent" \ -d '{ "by": "ai:your-agent", "operations": [ {"op": "insert", "after": "anchor text to find", "content": "\n\nContent to insert after the anchor."} ] }' `insert` only supports `after`. Payloads using `before` are rejected with `INVALID_OPERATIONS`. ### Multiple operations You can combine operations in a single request (applied in order): curl -X POST "https://proof-sdk-psi.vercel.app/documents//edit" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "X-Agent-Id: your-agent" \ -d '{ "by": "ai:your-agent", "operations": [ {"op": "append", "section": "Dan", "content": "\n\nNew idea from Dan."}, {"op": "replace", "search": "(placeholder)", "content": "Actual content here."} ] }' ### Response A successful response includes: { "success": true, "slug": "", "updatedAt": "", "collabApplied": true } - `collabApplied: true` means the edit was pushed into the live collab session (connected viewers see it in real time). - `presenceApplied` is only `true` when you also supplied explicit agent identity via `X-Agent-Id`, `agentId`, or `agent.id`. - If the document changed since you last read it, you may get a `409 STALE_BASE` error — re-fetch state and retry. Collab convergence fields: - `collab.status` is render-authoritative (`confirmed` when the ProseMirror/Yjs fragment converged). - `collab.fragmentStatus` tracks fragment convergence (`confirmed|pending`). - `collab.markdownStatus` tracks SQL markdown projection convergence (`confirmed|pending`). - `collabApplied` follows `fragmentStatus` (not markdown projection status). ### Optimistic locking (required for `/edit`) Pass `baseUpdatedAt` (from a prior state response) to detect concurrent edits: {"by": "ai:your-agent", "baseUpdatedAt": "2026-02-16T...", "operations": [...]} If the document's `updatedAt` doesn't match, you'll get a `409` with `retryWithState` pointing to the state endpoint. ## Update Title Metadata Use: PUT /documents//title Example: curl -X PUT "https://proof-sdk-psi.vercel.app/documents//title" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"title":"Updated document title"}' Discovery: - `GET /documents//state` includes `_links.title` and `agent.titleApi`. ## Edit V2 (Block IDs + Revision Locking) Use v2 for top-level block edits with stable block IDs and revision-based optimistic locking. ### Get a snapshot GET /documents//snapshot Example: curl -H "Authorization: Bearer " "https://proof-sdk-psi.vercel.app/documents//snapshot" The response includes `revision` and an ordered `blocks` array with deterministic refs (`b1`, `b2`, ...). ### Apply edits POST /documents//edit/v2 Example: curl -X POST "https://proof-sdk-psi.vercel.app/documents//edit/v2" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "Idempotency-Key: " \ -d '{ "by": "ai:your-agent", "baseRevision": 128, "operations": [ { "op": "replace_block", "ref": "b3", "block": { "markdown": "Updated paragraph." } }, { "op": "insert_after", "ref": "b3", "blocks": [{ "markdown": "## New Section" }] } ] }' On success, the response includes the new `revision`, a `snapshot` payload, and a `collab` status. If your `baseRevision` is stale, you'll receive `STALE_REVISION` plus the latest snapshot for retry. v2 convergence fields: - `collab.status` remains compatibility status (`confirmed|pending`) and is fragment-authoritative. - `collab.fragmentStatus` and `collab.markdownStatus` expose render-vs-projection split directly. - `202` is only expected when fragment convergence is pending. Precondition contract for v2: - `baseRevision` is required. - `baseUpdatedAt` is not accepted on `/edit/v2`. Idempotency guidance: - Send `Idempotency-Key` for mutation requests (`X-Idempotency-Key` is also accepted for compatibility). - `/edit/v2` examples include this header because block-level retries are common in automation. Mutation contract discovery: - Read `contract.mutationStage` from `GET /documents//state` to detect Stage A/B/C rollout. - `contract.idempotencyRequired` and `contract.preconditionMode` summarize current requirements. Common mutation contract error codes: - `IDEMPOTENCY_KEY_REQUIRED`: mutation request omitted idempotency key in required stage. - `IDEMPOTENCY_KEY_REUSED`: same key reused with a different payload hash. - `BASE_REVISION_REQUIRED`: stage requires `baseRevision` and request did not provide it. - `LIVE_CLIENTS_PRESENT`: rewrite blocked because active authenticated collab clients are connected. Use `retryWithState` to refresh state, confirm `connectedClients === 0`, and if `forceIgnored=true` do not retry with `force` in hosted environments. This response is retryable and includes `reason` + `nextSteps`. - `REWRITE_BARRIER_FAILED`: rewrite safety barrier failed before mutation; no rewrite was applied. This response is retryable and includes `reason` + `nextSteps`; retry with bounded exponential backoff and jitter. ## Presence And Event Polling Poll for changes: GET /documents//events/pending?after=&limit=100 Ack processed events (editor/owner): POST /documents//events/ack Body: {"upToId": , "by": "ai:your-agent"} ## Archived Desktop Workflow This repo is web-first. Desktop-native workflows are outside the public SDK scope and should be treated as separate implementation work. ## Projection Guardrails And QA Operational metrics: - `projection_guard_block_total{reason,source}` - `projection_drift_total{reason,source}` - `projection_repair_total{result,reason}` - `projection_chars_bucket{source,le}` Staging soak (live browser viewers + repeated `/edit` + `/edit/v2`): SHARE_BASE_URL=https://proof-web-staging.up.railway.app \ SOAK_DURATION_MS=300000 \ npx tsx scripts/staging-collab-projection-soak.ts ## Create A New Shared Doc If you need to create a share from scratch, use: POST /documents This is the canonical public create route. Hosted Review Room still accepts `POST /share/markdown` as a compatibility alias. Legacy create routes like `/api/documents` are internal/legacy and may be warned or disabled on hosted environments. ## Recommended Workflow: Adding Content To An Existing Doc This is the most reliable way to add a line, row, or section to an existing document: ### Step 1: Get the snapshot curl -H "Authorization: Bearer " "https://proof-sdk-psi.vercel.app/documents//snapshot" This returns clean markdown per block (no internal HTML tags) plus stable `ref` identifiers and a `revision` number. ### Step 2: Find the right block Look through the `blocks` array for the block you want to edit or insert near. Each block has: - `ref`: stable identifier (e.g., `b3`) - `markdown`: the clean markdown content of that block - `type`: block type (e.g., `paragraph`, `heading`, `table`) ### Step 3: Apply your edit curl -X POST "https://proof-sdk-psi.vercel.app/documents//edit/v2" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "Idempotency-Key: " \ -d '{ "by": "ai:your-agent", "baseRevision": 128, "operations": [ { "op": "insert_after", "ref": "b3", "blocks": [{ "markdown": "New content here." }] } ] }' ### Step 4: Handle conflicts If you get `STALE_REVISION`, the response includes the latest snapshot — re-read the blocks and retry. ## Troubleshooting ### `ANCHOR_NOT_FOUND` on `/edit` replace or insert The `/edit` endpoint searches for your `search` or `after` text in the document. If the document was previously edited by agents, it may contain internal `` HTML tags. The search now automatically falls back to matching against clean text (with tags stripped), so this should be rare. If it still fails, the text genuinely doesn't exist in the document — re-read state and verify. ### `LIVE_CLIENTS_PRESENT` on `rewrite.apply` `rewrite.apply` is blocked when authenticated collaborators are connected. Outside hosted environments you can pass `"force": true`, but on hosted environments `force` is ignored. If you still prefer the safer path: 1. Use `/edit` or `/edit/v2` instead (they work with live clients). 2. Wait for clients to disconnect (poll `/state` and check `connectedClients`). ### Suggestion anchors not matching `suggestion.add` now resolves quotes against clean text even when the stored markdown contains internal `` annotations. If you still get `ANCHOR_NOT_FOUND`, re-read state and verify the quote text genuinely exists. ### Document content looks corrupted after suggestion reject cycles Repeated suggest/reject cycles on annotated documents now preserve stable suggestion anchors so the document text should remain unchanged. If you still see unexpected content drift, re-read `Accept: text/markdown` and report the exact request/response pair. ### `COLLAB_SYNC_FAILED` errors Edits via the API can fail when a browser has the document open with an active Yjs collab session. The `/edit` and `/edit/v2` endpoints handle this gracefully, but `rewrite.apply` does not. If you hit this, retry after a short delay or use `/edit`/`/edit/v2` instead.