codewithbehnam/proof

Proof - Collaborative Markdown Editor

Proof is a collaborative document editor for humans and agents. It supports two modes:

1. Web API - Create and edit shared documents via HTTP (no install needed)
2. 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:

1. Extract the slug (abc123) and token from the URL
2. Read the document state via the API
3. Add comments or suggest edits using the ops endpoint
4. 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