Proof - Collaborative Markdown Editor
Proof is a collaborative document editor for humans and agents. It supports two modes:
-
Web API - Create and edit shared documents via HTTP (no install needed)
-
Local Bridge - Drive the macOS Proof app via localhost:9847
Web API (Primary for Sharing)
Create a Shared Document
No authentication required. Returns a shareable URL with access token.
curl -X POST https://www.proofeditor.ai/share/markdown
-H "Content-Type: application/json"
-d '{"title":"My Doc","markdown":"# Hello\n\nContent here."}'
Response format:
{ "slug": "abc123", "tokenUrl": "https://www.proofeditor.ai/d/abc123?token=xxx", "accessToken": "xxx", "ownerSecret": "yyy", "_links": { "state": "https://www.proofeditor.ai/api/agent/abc123/state", "ops": "https://www.proofeditor.ai/api/agent/abc123/ops" } }
Use the tokenUrl as the shareable link. The _links give you the exact API paths.
Read a Shared Document
curl -s "https://www.proofeditor.ai/api/agent/{slug}/state"
-H "x-share-token: <token>"
Edit a Shared Document
All operations go to POST https://www.proofeditor.ai/api/agent/{slug}/ops
Note: Use the /api/agent/{slug}/ops path (from _links in create response), NOT /api/documents/{slug}/ops .
Authentication for protected docs:
-
Header: x-share-token: <token> or Authorization: Bearer <token>
-
Token comes from the URL parameter: ?token=xxx or the accessToken from create response
Comment on text:
{"op": "comment.add", "quote": "text to comment on", "by": "ai:<agent-name>", "text": "Your comment here"}
Reply to a comment:
{"op": "comment.reply", "markId": "<id>", "by": "ai:<agent-name>", "text": "Reply text"}
Resolve a comment:
{"op": "comment.resolve", "markId": "<id>", "by": "ai:<agent-name>"}
Suggest a replacement:
{"op": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:<agent-name>", "content": "replacement text"}
Suggest a deletion:
{"op": "suggestion.add", "kind": "delete", "quote": "text to delete", "by": "ai:<agent-name>"}
Bulk rewrite:
{"op": "rewrite.apply", "content": "full new markdown", "by": "ai:<agent-name>"}
Known Limitations (Web API)
-
suggestion.add with kind: "insert" returns Bad Request on the web ops endpoint. Use kind: "replace" with a broader quote instead, or use rewrite.apply for insertions.
-
Bridge-style endpoints (/d/{slug}/bridge/* ) require client version headers (x-proof-client-version , x-proof-client-build , x-proof-client-protocol ) and return 426 CLIENT_UPGRADE_REQUIRED without them. Use the /api/agent/{slug}/ops endpoint instead.
Local Bridge (macOS App)
Requires Proof.app running. Bridge at http://localhost:9847 .
Required headers:
-
X-Agent-Id: claude (identity for presence)
-
Content-Type: application/json
-
X-Window-Id: <uuid> (when multiple docs open)
Key Endpoints
Method Endpoint Purpose
GET /windows
List open documents
GET /state
Read markdown, cursor, word count
GET /marks
List all suggestions and comments
POST /marks/suggest-replace
{"quote":"old","by":"ai:<agent-name>","content":"new"}
POST /marks/suggest-insert
{"quote":"after this","by":"ai:<agent-name>","content":"insert"}
POST /marks/suggest-delete
{"quote":"delete this","by":"ai:<agent-name>"}
POST /marks/comment
{"quote":"text","by":"ai:<agent-name>","text":"comment"}
POST /marks/reply
{"markId":"<id>","by":"ai:<agent-name>","text":"reply"}
POST /marks/resolve
{"markId":"<id>","by":"ai:<agent-name>"}
POST /marks/accept
{"markId":"<id>"}
POST /marks/reject
{"markId":"<id>"}
POST /rewrite
{"content":"full markdown","by":"ai:<agent-name>"}
POST /presence
{"status":"reading","summary":"..."}
GET /events/pending
Poll for user actions
Presence Statuses
thinking , reading , idle , acting , waiting , completed
Workflow: Review a Shared Document
When given a Proof URL like https://www.proofeditor.ai/d/abc123?token=xxx :
-
Extract the slug (abc123 ) and token from the URL
-
Read the document state via the API
-
Add comments or suggest edits using the ops endpoint
-
The author sees changes in real-time
Read
curl -s "https://www.proofeditor.ai/api/agent/abc123/state"
-H "x-share-token: xxx"
Comment
curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops"
-H "Content-Type: application/json"
-H "x-share-token: xxx"
-d '{"op":"comment.add","quote":"text","by":"ai:compound","text":"comment"}'
Suggest edit
curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops"
-H "Content-Type: application/json"
-H "x-share-token: xxx"
-d '{"op":"suggestion.add","kind":"replace","quote":"old","by":"ai:compound","content":"new"}'
Workflow: Create and Share a New Document
1. Create
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown
-H "Content-Type: application/json"
-d '{"title":"My Doc","markdown":"# Title\n\nContent here."}')
2. Extract URL and token
URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') SLUG=$(echo "$RESPONSE" | jq -r '.slug') TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')
3. Share the URL
echo "$URL"
4. Make edits using the ops endpoint
curl -X POST "https://www.proofeditor.ai/api/agent/$SLUG/ops"
-H "Content-Type: application/json"
-H "x-share-token: $TOKEN"
-d '{"op":"comment.add","quote":"Content here","by":"ai:compound","text":"Added a note"}'
Safety
-
Use /state content as source of truth before editing
-
Prefer suggest-replace over full rewrite for small changes
-
Don't span table cells in a single replace
-
Always include by field for attribution tracking