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: "
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:
or
Authorization: Bearer
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:"
,
"text"
:
"Your comment here"
}
Reply to a comment:
{
"op"
:
"comment.reply"
,
"markId"
:
""
,
"by"
:
"ai:"
,
"text"
:
"Reply text"
}
Resolve a comment:
{
"op"
:
"comment.resolve"
,
"markId"
:
""
,
"by"
:
"ai:"
}
Suggest a replacement:
{
"op"
:
"suggestion.add"
,
"kind"
:
"replace"
,
"quote"
:
"original text"
,
"by"
:
"ai:"
,
"content"
:
"replacement text"
}
Suggest a deletion:
{
"op"
:
"suggestion.add"
,
"kind"
:
"delete"
,
"quote"
:
"text to delete"
,
"by"
:
"ai:"
}
Bulk rewrite:
{
"op"
:
"rewrite.apply"
,
"content"
:
"full new markdown"
,
"by"
:
"ai:"
}
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:
(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:","content":"new"}
POST
/marks/suggest-insert
{"quote":"after this","by":"ai:","content":"insert"}
POST
/marks/suggest-delete
{"quote":"delete this","by":"ai:"}
POST
/marks/comment
{"quote":"text","by":"ai:","text":"comment"}
POST
/marks/reply
{"markId":"","by":"ai:","text":"reply"}
POST
/marks/resolve
{"markId":"","by":"ai:"}
POST
/marks/accept
{"markId":""}
POST
/marks/reject
{"markId":""}
POST
/rewrite
{"content":"full markdown","by":"ai:"}
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"
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