Revisions & checkpoints

Named save points, full history, and safe revert — all applied to the live document as minimal diffs.

Docs keeps a linear history of revisions per document. Some are created automatically (e.g. by writes that checkpoint), others are explicit checkpoints — named save points you create on purpose.

Revisions

A revision is a snapshot of the document’s markdown plus metadata: id (rev_…), message, creating actor, and timestamp. You can:

• list them: GET /api/docs/:id/revisions → {"revisions": [...], "actors": {...}}
• fetch one: GET /api/docs/:id/revisions/:revId
• fetch one’s raw markdown: GET /api/docs/:id/revisions/:revId/raw

Checkpoints

A checkpoint is just a revision you create deliberately:

curl -X POST https://docs.aicomputercompany.com/api/docs/doc_abc123/checkpoints \
  -H 'Content-Type: application/json' \
  -H 'x-actor-id: agent_demo' \
  -d '{"reason": "manual-save", "message": "Before restructuring section 2"}'

If you omit markdown in the body, the checkpoint captures the latest revision content.

Checkpoint flags on write endpoints

Several write endpoints take checkpoint controls inline, so a logical unit of work produces one history entry:

• PUT /api/docs/:id/markdown — "checkpoint": true (default true) + "message".
• POST /api/docs/:id/annotations — "checkpoint": false by default for single annotations.
• POST /api/docs/:id/annotations/bulk — "checkpoint": true by default: one revision for a whole review pass (e.g. “AI spec review”), no matter how many annotations it creates.

Set checkpoint: true on important edits so humans get named history entries they can navigate and revert to.

Revert

Reverting never rewrites history. POST /api/docs/:id/revert with {"revisionId": "rev_…"}:

1. creates a new revision containing the old content, and
2. diff-applies that content to the live document.

Because the revert is applied as a minimal diff (like every server-side write), collaborators who are mid-edit keep their cursors — the document content shifts under them rather than being replaced.

Relationship to export

GET /api/docs/:id/export.md exports the latest saved revision, while GET /api/docs/:id/export.clean.md cleans the live document content. If you need the very latest text including unsaved live edits, use raw or export.clean.md. See Documents API.