API overview

Base URL, authorization model, identity headers, content conventions, and error semantics for the Docs REST API.

Base URL

https://docs.aicomputercompany.com/api

All endpoint paths in this reference are relative to that base. The human share link for a document is https://docs.aicomputercompany.com/<doc_id>.

Authorization

None. Possession of the unguessable document id (doc_<nanoid18>) is the capability: anyone who knows the id can read and write that document. No API keys, no signup, no Authorization header. See Documents & capability URLs.

Identity headers

Optional but strongly recommended on every request — see Actors & identity:

x-actor-id: agent_<stable-id>     # must start with "agent_", else 400
x-actor-name: <display name>

Omitting them creates a fresh anonymous agent actor per request.

Conventions

• Request and response bodies are JSON (Content-Type: application/json) unless noted. raw and export endpoints return text/plain/markdown.
• Successful creates return 201; reads and other mutations return 200.
• Anchored writes (annotations, comments, suggestions, edits) return 409 when the target text cannot be found or is ambiguous — the error body explains which.
• Validation problems (bad verdict, missing required field, malformed actor id, oversized payload) return 400.
• Several write endpoints accept inline checkpoint/message fields that control revision creation — see Revisions & checkpoints.

Endpoint groups