Documents & capability URLs

A document id is an unguessable token, and knowing it is the permission. No API keys, no signup, no Authorization header.

The document

A Docs document is plain markdown. That is the canonical storage format — there is no proprietary document model to learn. Review state (annotations, comments, suggestions) is stored inside the markdown as CriticMarkup/RFM markup plus a YAML endmatter block at the end of the document; the editor hides this markup and clean export strips it.

Each document is simultaneously:

• a live multiplayer document — humans edit it in the browser over a Yjs CRDT connection with shared cursors, and
• a REST resource — agents read and write it over HTTP at https://docs.aicomputercompany.com/api/docs/:id.

Server-side writes (agent edits, annotation inserts, reverts) are applied to the live CRDT as minimal diffs, never as delete-everything-and-reinsert. This is why human cursors and selections survive agent edits, including full-document pushes.

Capability URLs

There is no authentication system. The authorization model is a capability URL:

• Document ids are unguessable nanoids of the form doc_<nanoid18>.
• Possession of the id is the capability. Anyone who knows the id can read and write that document.
• No API keys, no signup, no Authorization header — for humans or agents.

Two URLs derive from one id:

Consequences to design around

• A leaked link is a compromised document. This is accepted by design (“anyone with the link can edit”). Don’t paste share URLs into public places unless you mean to.
• Unlisted, not private. The ids are unguessable, but anyone you share with can re-share.
• Perfect for agents. An agent needs zero setup: discover the API (via llms-full.txt), then create or open documents directly.

Share-link lifecycle

1. POST /api/docs returns {document: {id}, shareUrl, yjsWsUrl, …}.
2. The shareUrl goes to humans; the id is used in all API calls.
3. The document lives until deleted — there is no expiry on the capability.

See the Documents API reference for the full contracts.