# codoc
codoc hosts one HTML document per URL. You create and edit its source through a
REST API; your user reads it in a browser and leaves comments anchored to the
text. While they review, long-poll the document's event stream to learn when a
thread changes, then read the affected comments, revise the document, and reply
through the API. This supports a real-time back-and-forth with your user. There
is no client library or MCP server.
Stored HTML is preserved exactly, but the browser presents a sanitized view:
scripts do not run, and unsupported elements and external resources do not
load. Every content write reports what rendering removed or blocked. Author for
the rendered view; the full resource policy appears under Writing documents
well.
base URL $BASE = https://codoc.sh
transport REST over HTTP; JSON in and out
reading page GET /d/
Public document UUIDs grant anonymous access to current content and comments.
Private documents require membership. Revision history and diffs require an
editor or owner regardless of visibility.
## Registration
Register once and keep the returned key; it is shown only in this response:
```sh
curl -sS -X POST "$BASE/api/agents/register" \
-H 'content-type: application/json' \
-d '{"name":"Document agent"}'
```
The response is { id, name, key, emailAttached, warning }. Capture key as
$KEY; it begins sk_agent_.
Send it on every document API call:
Authorization: Bearer $KEY
Durability is opt-in. Until a verified email is attached, a lost key is
unrecoverable and whoever attaches an email first can claim the account. Attach
one immediately. If you have no address of your own, ask your user for a spare
one, or theirs with +agent added. It becomes this account's address, so they
cannot sign up with it later.
## Account
All calls below except key recovery require Authorization: Bearer $KEY.
GET /api/agents/me → { emailAttached, id, kind, name, pendingEmail? }.
pendingEmail names an email attachment awaiting its code.
POST /api/agents/email { email } → { ok, verification: { codeLength,
expiresInSeconds, submitTo } }. A repeat attachment supersedes the pending one.
POST /api/agents/email/verify { code, email? } → the /me body. Omit email to use
the pending attachment.
POST /api/agents/key/rotate → { id, key }. The retired key works for up to an hour unless
the new key is used once; that verifies it and immediately refuses the retired key.
POST /api/agents/key/recover { email } → the same pending receipt; add code →
{ id, key }, revoking every other key. Recovery requires a verified attached email.
Owners batch membership at POST /api/document/{id}/access with addMembers
[{ email, role }] among its keys; new grants trigger a notice. The creator stays owner.
## How to work with a document
1. ORIENT with read_doc. A bare GET returns a bounded overview: version, source
and text sizes, comment counts, activity, and presence. Use it to begin a turn
and learn whether anything moved. Fetch source only when you need it.
2. LOCATE with find. Search source for edit targets and text for comment capture
evidence. Batch related queries in one call.
3. EDIT with edit_doc. Send every exact replacement for the turn together under
one baseVersion. Use write_doc only when most of the document changes.
4. VERIFY from the write receipt. It reports the new version, counts, anchor
outcomes, sanitization, and concurrent changes. Do not re-read merely to
verify a successful write.
5. COLLABORATE by long-polling events. Read only the comment IDs an event names,
then answer the whole turn through one comments call. Honor pollAfter and
stop when it says "stop".
dryRun: true on edit_doc or write_doc runs the complete evaluation without
persisting or consuming an idempotency key. Its receipt has committed: false;
version is the version the write would produce, not the stored version.
All JSON request bodies are strict. Unknown fields are refused by name. A field
ending in ? below is optional.
## API
Request fields below are generated from the schemas used by the route handlers.
Response schemas are not expanded: the summaries include what is needed to plan
the next call, and successful responses are self-describing JSON.
### create_doc — POST /api/document
Create a document. The calling account becomes its owner; visibility defaults
to public and ownerEmail can name a second owner. When the document is for a
human, name their address as ownerEmail; ask for it if you lack it. They sign
in with it to reach the document.
gate account
header Authorization — Agent account key.
body
change? object
summary? string
html? string
ownerEmail? email
title? string, ≤300 chars
via? string, ≤100 chars
visibility? "public" | "private" (default "public")
returns
id, url, title, version, sanitization, warnings
via stores caller-defined creation attribution. The title field is
authoritative; later edits to source do not rename the document.
### read_doc — GET /api/document/{id}
Orient before fetching. The default overview returns version, sizes and
comment counts for a fraction of the document; read source or text only once
it says something moved. view=source takes fromLine/toLine, so find's line
number reads back as a window. view=history and every version read are
owner/editor-only.
gate public current content or private membership
header Authorization? — Agent account key.
query
fromLine? integer — First source line, 1-based and inclusive; view source only.
toLine? integer — Last source line, inclusive; past the end reads to the end.
version? integer — Read a retained revision instead of the current one.
view? "overview" | "source" | "text" | "history" (default "overview")
returns
overview: version, sizes, title, comments, activity, and presence; source:
exact html plus its line interval; text: canonical projected text;
history: retained revisions newest first
History retains at most 100 revisions. version works with source or text.
fromLine and toLine are 1-based, inclusive, source-only, and toLine clamps to
the document end.
### find — POST /api/document/{id}/find
The grep of the loop, batched. Source matches arrive edit-ready: widen target
with before/after until unique, then paste it into edit_doc. Text matches
arrive capture-ready: occurrenceCount and context go straight into comments.
gate public current content or private membership
header Authorization? — Agent account key.
body
maxResultsPerQuery? integer, ≤50 (default 20)
queries array, 1–10 items
caseSensitive? boolean — Source space only; default true.
query string, 1–2,000 chars
regex? boolean — RE2 syntax. No lookaround, no backreference.
space? "source" | "text" (default "source")
returns
version, space, and one result per query with totalMatches, returned,
truncated, excludedUnusable, and matches
A source match contains line, target, matchCount, occurrence, and up to 80
characters of before/after context. Widen target until unique, then use it in
edit_doc. A source match over 2,000 characters is omitted, not truncated.
Plain queries match across whitespace and line breaks; source matches return
the exact stored bytes. Use regex: true with an escaped query for
whitespace-exact matching. A text match contains quote, occurrenceCount,
occurrence, and normalized context.prefix/context.suffix; copy those fields
into createComments or reanchorComments.
### edit_doc — PATCH /api/document/{id}
Exact string replacement, every edit of a turn in one call. A successful
receipt is complete — it names what the edit did to the comments — so do not
re-read the document after it.
gate editor or higher
header Authorization — Agent account key.
header Idempotency-Key? — Retry label; the same key and body never applies twice.
body
baseVersion integer
change? object
summary? string
dryRun? boolean — Evaluate and receipt without persisting anything.
patches array, 1–100 items
replacement string
target string, ≥1 chars — Exact source substring; widen it until it matches once.
replaceAll? boolean — Replace every instance instead of requiring a unique match.
returns
committed, version, appliedCounts, anchors, sanitization, warnings,
changesSince, changesSinceComplete, and optional replay fields
A stale baseVersion is acceptable when every exact target still resolves
safely. A future version, missing or ambiguous target, or overlapping patches
is refused with structured details. appliedCounts[i] corresponds to
patches[i]. changesSince contains at most 20 revisions.
### write_doc — PUT /api/document/{id}
Whole-document overwrite under strict compare-and-swap. Prefer edit_doc unless
most of the document changes; either way unchanged text keeps its comments.
gate editor or higher
header Authorization — Agent account key.
header Idempotency-Key? — Retry label; the same key and body never applies twice.
body
baseVersion integer
change? object
summary? string
dryRun? boolean — Evaluate and receipt without persisting anything.
html string
returns
the same write receipt as edit_doc
The baseVersion must equal the current version. Unchanged text keeps its
comments. A stale whole-document write is refused because it cannot prove it
preserves an intervening edit.
### diff — GET /api/document/{id}/diff
One bounded unified diff instead of two full documents. Derived output: a hunk
is not an edit target in either space.
gate editor or higher
header Authorization — Agent account key.
query
fromVersion integer
space? "source" | "text" (default "source")
toVersion? integer
returns
fromVersion, toVersion, space, diff, truncated
diff is at most 60,000 characters. Ordinary hunks include 3 unchanged lines of
context; very long lines are refined to bounded changed spans. Diff output is
descriptive, never a patchable address.
### read_comments — GET /api/document/{id}/comments
Bounded thread read that never carries document bytes. When an event names
comment ids, read exactly those; lastAuthor or lastAuthorId returns just the
threads that actor spoke in last; view=overview surveys every thread without
bodies.
gate public current content or private membership
header Authorization? — Agent account key.
query
activeSince? date-time — Threads whose last activity is at or after this instant.
commentIds? array of uuid, ≤50 items
includeSource? boolean — Add each attached thread's exact current-source excerpt.
limit? integer, ≤100 (default 20)
replyLimit? integer, ≤200 (default 15) — Replies carried per thread; limit bounds threads.
lastAuthor? string, 1–100 chars — Threads whose newest message is by this name.
lastAuthorId? uuid — Threads whose newest message is by this account id.
resolved? boolean
state? "attached" | "detached"
view? "full" | "overview" (default "full") — overview drops every body and says who spoke first and last.
returns
version, threads, returned, total, truncated, notFound; each thread
includes replies, reactions, resolution, and its attached or detached
anchor
includeSource adds the exact current-source excerpt for an attached thread,
usable as an edit_doc target. lastAuthor matches a non-unique display name;
lastAuthorId matches an account id, including your own from GET
/api/agents/me. authorAccountId appears only to editors and owners. A reaction
is not a message: a thumbs-up does not make its reactor the last speaker.
view=overview drops every body and returns anchor, resolution, reply and
reaction counts, and who spoke first and last — the survey read, when the
question is the state of every thread rather than what any of them says. This
result is not paged: narrow filters when truncated. limit × replyLimit is the
response bound; values beyond either ceiling are refused rather than clamped.
### comments — POST /api/document/{id}/comments/batch
Every comment mutation in one transaction: create, reply, edit, resolve,
re-anchor, react, delete. Each key takes a list, so one call carries a whole
turn of comment duty. Captures need the evidence find returns.
gate commenter or higher
header Authorization — Agent account key.
header Idempotency-Key? — Retry label; the same key and body never applies twice.
body
baseVersion? integer — Required with reanchorComments, and only then.
createComments? array, ≤100 items
context object
prefix string, ≤1,000 chars
suffix string, ≤1,000 chars
occurrence? integer — Which match, 1-based; required once occurrenceCount exceeds one.
occurrenceCount integer — Total matches of the quote in the whole text; find returns it.
body string, 1–20,000 chars
quote string, 1–1,000 chars
createReplies? array, ≤100 items
body string, 1–20,000 chars
commentId uuid
deleteComments? array of uuid, ≤100 items
deleteReplies? array, ≤100 items
commentId uuid
replyId uuid
editBodies? array, ≤100 items
body string, 1–20,000 chars
commentId uuid
replyId? uuid
react? array, ≤100 items
commentId uuid
emoji string, 1–32 chars
reacted boolean
replyId? uuid
reanchorComments? array, ≤100 items
context object
prefix string, ≤1,000 chars
suffix string, ≤1,000 chars
occurrence? integer — Which match, 1-based; required once occurrenceCount exceeds one.
occurrenceCount integer — Total matches of the quote in the whole text; find returns it.
commentId uuid
quote string, 1–1,000 chars
setResolved? array, ≤100 items
commentId uuid
resolved boolean
returns
applied counts, created.comments, created.replies, eventsCreated, and
optional currentVersion and replay fields
At least one operation list must be non-empty. Capture evidence for
createComments and reanchorComments must come from find in text space; never
compute it. createComments has no baseVersion: its evidence is re-resolved
against the locked current document and refused if its quote, count, or
context changed. created.comments[i] corresponds to createComments[i], and
created.replies[i] to createReplies[i]. Combined body text is limited to
200,000 characters. Resolving preserves a thread; deletion removes it.
### events — GET /api/document/{id}/events
The wake signal: cheap while idle, and it holds the connection open for
waitSeconds. Events name comment ids and never carry bodies, so follow a wake
with read_comments.
gate public current content or private membership
header Authorization? — Agent account key.
query
clientId? string, 1–128 chars
excludeSelf? boolean (default false)
since? "now" | string ^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}):(\d{1,19})$
waitSeconds? integer, 0–25 (default 0)
returns
events, nextCursor, pollAfter, activeViewers, agentListening, viewerToken
and buildId (both for browsers; agents may ignore)
Events contain IDs and metadata, not comment bodies. Read named threads with
read_comments. Agent-key polls ignore clientId, use the account id for
presence, and count as agentListening; anonymous polls require clientId and
count as active viewers. Attach in this order: poll with since=now and
waitSeconds=0 FIRST, process any events that response already carries, take
every baseline read (read_doc for content and read_comments for the thread
survey), then poll from the attach response's nextCursor. Anything arriving
during those baseline reads remains ahead of that cursor and is delivered. Use
now only to attach; using it mid-session skips unread events. A page holds at
most 100 events; a full page means read again from nextCursor. Send back the
nextCursor you were last given; cursors are scoped to their document and a
cursor from another document is refused. excludeSelf omits events written by
the authenticated caller without changing the stream head. actorAccountId
appears only to editors and owners. Honor pollAfter: 4 seconds after an event
or while a reader is active, 10 seconds during recent quiet, 30 seconds during
prolonged quiet, and "stop" after 1,800 seconds without activity. On "stop",
stop polling and return control to the user. If your harness blocks while a
command runs, poll from a background task: a foreground long-poll leaves your
user's other channels unanswered for as long as it waits.
### delete_doc — DELETE /api/document/{id}
Permanently delete a document and everything attached to it. Only an owner can
do this, and the id then reads exactly like one that never existed.
gate owner
header Authorization — Agent account key.
returns
deleted: true
Owner-only and irreversible. The document, history, comments, memberships,
invites, events, and retry receipts are deleted together; later calls return
not_found.
## Worked examples
These are the three worked examples whose data flow is easiest to get wrong on
a first attempt. Every HTTP call is executed against the real route handlers in
the test suite.
### 1. Create a document
```sh
curl -sS -X POST "$BASE/api/document" \
-H 'content-type: application/json' \
-H "authorization: Bearer $KEY" \
-d @- <<'JSON'
{
"html": "<!doctype html>\n<html lang=\"en\">\n<head><meta charset=\"utf-8\"><title>Launch note\n\nLaunch note
\nThe ship date is 2026-09-01.
\nRisks
\nThe ship date is the only hard commitment.
\n\n