An editor your AI can use

Most “AI-powered” editors put the model inside the product: a chat box in the sidebar, a rewrite button on the toolbar. Docs takes the opposite approach. Your agent lives wherever it already lives — Claude Code, Cursor, a cron job, your own framework — and Docs gives it a document it can operate on like any other tool in its environment.

That choice forced a question we think most products skip: what does an editing API that agents are genuinely good at actually look like?

Agents already know how to edit files

Every serious coding agent has converged on the same primitive for editing local files: string replacement. Read the file, find an exact old_string, replace it with new_string, fail loudly if the match is missing or ambiguous. It’s the contract behind the Edit tool in Claude Code and its equivalents everywhere else — and models have been trained on millions of episodes of using it well.

So Docs speaks it natively:

POST /api/docs/<id>/edit
{
  "old_string": "launch is scheduled for Q3",
  "new_string": "launch is scheduled for Q2"
}

The error contract mirrors local edit-tool semantics exactly. If old_string isn’t in the document, you get a 409 with “old_string not found” — re-read and fix your match. If it appears more than once, you get a 409 for ambiguity — add surrounding context, or pass "replace_all": true. An agent that can edit a file on your laptop can edit a Docs document with zero new behavior to learn. That is the whole point.

Reading follows the same instinct. GET /api/docs/<id>/raw returns plain markdown, and ?numbered=1 returns it with cat -n-style line numbers — the read-before-edit pattern agents already practice locally.

The hard part: live documents

Here’s where a shared document is harsher than a local file: someone may be typing in it right now.

A naive implementation would take the agent’s edit, compute the new full text, and replace the document. In a CRDT-backed multiplayer editor, that’s catastrophic — a delete-everything-insert-everything operation destroys every collaborator’s cursor and selection, and merges horribly with concurrent keystrokes.

Docs never does this. Every server-side change — a one-line str_replace or a full-document PUT — is diffed against the current state and applied as a minimal set of CRDT operations to the live Yjs document. Concurrent human edits merge the way CRDTs are designed to merge. Cursors survive. The human experience of an agent edit is a small, surgical change appearing in place, exactly as if a careful collaborator had made it.

No keys, attributed anyway

There are no API keys. Knowing a document’s id is the permission to edit it — the same capability URL a human uses in the browser. What we ask of agents instead is attribution: two headers, x-actor-id and x-actor-name, so every annotation, suggestion, and edit shows up in the document credited to the actor who made it. Collaboration needs identity for blame, not for gatekeeping — at least in this beta.

Discoverable from a cold start

The test we hold ourselves to: an agent with no prior context should be able to figure all of this out. So:

• llm.txt gives the elevator summary and the lifecycle in ~25 lines.
• llms-full.txt is the complete manual — every endpoint with curl examples.
• The agent prompt on our home page is a copy-paste block teaching the full workflow: create → share the URL → read numbered → targeted edits → review → checkpoint.

Beyond editing, the same API carries the review layer — annotations with verdicts, threaded comments, acceptable suggestions, checkpoints, clean export. Your agent doesn’t just patch text; it participates: flags a conflict between two sections, proposes a fix as a suggestion, asks a question in a thread, and checkpoints before anything drastic.

An editor your AI can use turns out to mean an editor that meets agents where they already are — and then sweats the CRDT details so humans never feel the machinery. Open a document and hand your agent the link.