API pipeline: Keep a card's version history

Index: API pipelines — index

Goal: keep every saved state of a card, take a snapshot on demand and roll back to an older version.

Steps

1. Switch history on (the owner only).

PUT /v0/my/cards/470000000000000001/versions
{"enabled": true}
→ {"nonce": "470000000000000001", "versioned": true, "workspace": "470000000000000031", "items": []}

History works for projects, articles, posts, docs, sheets, boards, workspaces, rubrics, campaigns, oracles, agendas, API endpoints, links, secrets, rooms and coupons. {"enabled": false} switches it off.

2. Edit as usual. Every write by the owner or a writer first stores the previous state as the next version.

3. Snapshot now (needs write; no body).

POST /v0/my/cards/470000000000000001/versions
→ {"version": 3, "nonce": "470000000000000043", "created_at": "2026-10-15T12:00:00Z", "author": "<user>"}

4. List versions.

GET /v0/my/cards/470000000000000001/versions
→ {"versioned": true, "workspace": "470000000000000031",
   "items": [{"version": 1, "nonce": "470000000000000041", "created_at": "…", "author": "<user>"}, …]}

Version 1 is the oldest; numbers never change. Read a version with the ordinary card GET on its nonce; GET /v0/my/cards/{snapshot}/versions answers version_of and version.

5. Roll back.

POST /v0/my/cards/470000000000000001/versions/2/make-current
→ {"nonce": "470000000000000001", "restored": 2, "pushed": {"version": 4, "nonce": "…", …}}

The state that was current is stored first as the next version (pushed), so a rollback can be undone the same way.

Behind

• Versions are archived, read-only copies of the card. The history workspace holds them; it is Private, so only you see the history until you share that workspace by a link or grant.
• author is the user whose write pushed that state into history.

Rules

• PUT: owner only, else 404. 400 history can be switched only on an original card (on a version or a history workspace), history is not supported for <type>.
• POST …/versions: needs write, else 404. 400 history is off for this card; switch it on first.
• make-current: needs write on the card and read of that version, else 404.
• Any write to a version: 400 this card is a version snapshot and is read-only; use make-current on the original.

API surface