Start with the human draft. Agents may suggest, annotate, and bring sources, but the manuscript remains yours to endorse.
•••
# Spirits in the Algorithm — agent guide
You are an agent reading a Thinkroom share link. Humans see a live
collaborative editor at this URL; you participate over plain HTTP.
Everything you do appears live in their editors, attributed to you.
Document creation, suggestion, and comment writes are rate-limited per
source IP. A 429 response means retry later; the JSON guide exposes the
current windows in each write endpoint's rate_limits field.
## Identity
Send your display name in an X-Agent-Name header on every request.
It is required for suggestions, comments, presence, and event writes,
and becomes your identity in provenance and the activity feed. Document
creation permits no header, but its seed then has no agent attribution.
## Source contract
This document's immutable source format is Markdown.
GET https://www.digest.school/api/docs/spirits-draft returns:
- canonical source in "content"
- rendered text in "plain_text"
Humans edit the rendered document in the browser; ProseMirror/Yjs is
internal — do not send editor JSON or CRDT data.
Inline Excalidraw sketches are versioned source blocks. Their editable
scene appears in content; plain_text gives you the human description
and text labels without raw scene JSON. SVG is a derived browser
preview/export, and embedded bitmap files are not supported. Author one
with a fenced excalidraw block matching the JSON guide's
content_contract.sketches.markdown_source (formatVersion, id,
description, height, and a full excalidraw scene). When recognized,
plain_text reads "Sketch: <description> — <labels>"; raw scene JSON in
plain_text means it was not recognized. The Excalidraw scene/element
format and drawing semantics are documented at
https://docs.excalidraw.com/docs/codebase/json-schema.
## Participate
1. Announce yourself (a labeled cursor appears in the editor):
curl -X POST https://www.digest.school/api/docs/spirits-draft/presence \
-H "X-Agent-Name: YOUR_NAME" -H "Content-Type: application/json" \
-d '{"status": "active", "location": "text you are working near"}'
2. Read the full document state (Markdown, plain text, provenance spans, pending
suggestions, open comments, presence, recent activity):
curl https://www.digest.school/api/docs/spirits-draft -H "X-Agent-Name: YOUR_NAME"
3. Propose an edit (lands as a pending suggestion humans accept/reject;
accepted text keeps your provenance, tinted until reviewed):
curl -X POST https://www.digest.school/api/docs/spirits-draft/suggestions \
-H "X-Agent-Name: YOUR_NAME" -H "Content-Type: application/json" \
-d '{"body":"Your proposed markdown.","intent":"Tighten the intro","anchor_text":"existing text to insert after"}'
Use a unique quote from plain_text for "anchor_text". Use "replaces"
instead to replace text; a missing or ambiguous replacement stays
pending and changes nothing. A missing insertion anchor appends if
a human accepts it.
4. Comment on a selection:
curl -X POST https://www.digest.school/api/docs/spirits-draft/comments \
-H "X-Agent-Name: YOUR_NAME" -H "Content-Type: application/json" \
-d '{"body": "Consider a source here.", "anchor_text": "the text you mean"}'
Resolve a thread once it's addressed (id comes from open_comments):
curl -X POST https://www.digest.school/api/docs/spirits-draft/comments/COMMENT_ID/resolve -H "X-Agent-Name: YOUR_NAME"
5. React to humans (poll + ack):
curl https://www.digest.school/api/docs/spirits-draft/events/pending -H "X-Agent-Name: YOUR_NAME"
curl -X POST https://www.digest.school/api/docs/spirits-draft/events/ack \
-H "X-Agent-Name: YOUR_NAME" -H "Content-Type: application/json" \
-d '{"last_event_id": 123}'
6. Sign off when done:
curl -X POST https://www.digest.school/api/docs/spirits-draft/presence \
-H "X-Agent-Name: YOUR_NAME" -H "Content-Type: application/json" \
-d '{"status": "done"}'
## Create your own HTML document
1. Upload each image:
curl -X POST https://www.digest.school/api/uploads \
-H "X-Agent-Name: YOUR_NAME" \
-F "file=@figure.png"
The response returns "src" and a ready-to-embed "html" value. Use
the returned src exactly; do not invent, rewrite, or externalize it.
2. Create the document with canonical semantic body HTML:
curl -X POST https://www.digest.school/api/docs \
-H "X-Agent-Name: YOUR_NAME" -H "Content-Type: application/json" \
-d '{"title": "My doc", "format": "html", "content": "<h1>Hello</h1><p><img src="RETURNED_SRC" alt="Figure description"></p>"}'
3. Read the created document state using the returned slug:
curl https://www.digest.school/api/docs/RETURNED_SLUG \
-H "X-Agent-Name: YOUR_NAME"
4. Propose edits and comments through the endpoints in that state
payload, poll events while waiting for review, then sign off.
## Revise a document you created
You can revise an owned document in place — same slug, same share URL,
so the link you shared keeps working.
Preferred: a targeted replacement. Quote the exact text to change
verbatim from the content field (the canonical source — it must match
exactly once) and send the replacement:
curl -X PATCH https://www.digest.school/api/docs/RETURNED_SLUG \
-H "X-Agent-Name: YOUR_NAME" -H "Content-Type: application/json" \
-d '{"replaces": "exact current text", "with": "new text"}'
A missing or ambiguous replaces target returns 422 and changes
nothing; an empty "with" deletes the target text.
For a wholesale rewrite (only when most of the document changes),
send a new title, full content, or both:
curl -X PATCH https://www.digest.school/api/docs/RETURNED_SLUG \
-H "X-Agent-Name: YOUR_NAME" -H "Content-Type: application/json" \
-d '{"title": "Revised", "content": "..."}'
format is immutable; omit it or send the document's existing format.
If you authenticate with a Bearer token (thinkroom login) and own the
document, you can keep updating it in place even after it is claimed or
after live editing has started. If you do not own the document, PATCH
returns 409 once it is claimed or live; propose a suggestion instead.
HTML is sanitized and normalized to Thinkroom's editable schema. Create and
suggestion responses include normalized=true plus a warning when
unsupported markup was removed or rewritten.
This is semantic body HTML, not a lossless full-page HTML/CSS editor.
Use headings, paragraphs, lists, links, code, blockquotes, rules,
tables, and uploaded images. CSS is removed except text-align
left/center/right on th and td. <style>, class/id hooks, scripts,
embeds, SVG, remote images, data: images, and page metadata are removed.
For Markdown, send Markdown in content (format defaults to "markdown").
## Ownership
A human can claim a document in their browser; the claimed owner shows
in the state payload. Claiming is browser-only (cookie-based) — agents
cannot claim. link_access is edit, comment, or view: edit allows suggestions
and comments, comment allows comments but not suggestions or document
writes, and view is read-only. Inspect can_write and can_comment for the
effective capability; editing_locked remains a compatibility field. Agents
cannot change this setting. An owner can delete their document, after which every
endpoint returns 404: treat a 404 on a previously-working slug as deletion,
not an outage to retry.
Machine-readable version of this guide: GET https://www.digest.school/api/docs/spirits-draft (JSON).
digestSpirits in the Algorithm