API-пайплайн: история версий карточки

Индекс: API-пайплайны — индекс

Цель: хранить каждое сохранённое состояние карточки, делать снимок по требованию и откатываться к старой версии.

Шаги

1. Включить историю (только владелец).

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

История работает для проектов, статей, постов, документов, таблиц, досок, воркспейсов, рубрик, кампаний, оракулов, агенд, API-эндпоинтов, ссылок, секретов, комнат и купонов. {"enabled": false} выключает её.

2. Редактируйте как обычно. Каждая запись владельца или редактора сначала сохраняет прежнее состояние как следующую версию.

3. Снимок сейчас (нужен write; без тела).

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

4. Список версий.

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

Версия 1 самая старая; номера не меняются. Версию читают обычным GET карточки по её nonce; GET /v0/my/cards/{snapshot}/versions отвечает version_of и version.

5. Откат.

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

Текущее состояние сначала сохраняется как следующая версия (pushed), поэтому откат можно отменить так же.

За кадром

• Версии — архивные копии карточки только для чтения. Их хранит воркспейс истории; он приватный (Private), поэтому историю видите только вы, пока не поделитесь этим воркспейсом по ссылке или грантом.
• author — пользователь, чья запись отправила это состояние в историю.

Правила

• PUT: только владелец, иначе 404. 400 history can be switched only on an original card (на версии или воркспейсе истории), history is not supported for <type>.
• POST …/versions: нужен write, иначе 404. 400 history is off for this card; switch it on first.
• make-current: нужен write на карточку и read на эту версию, иначе 404.
• Любая запись в версию: 400 this card is a version snapshot and is read-only; use make-current on the original.

Поверхность API