Pipeline de API: historial de versiones de una tarjeta
Índice: Pipelines de API — índice
Objetivo: guardar cada estado de una tarjeta, hacer una instantánea cuando quieras y volver a una versión anterior.
Pasos
- Activar el historial (solo el dueño).
PUT /v0/my/cards/470000000000000001/versions
{"enabled": true}
→ {"nonce": "470000000000000001", "versioned": true, "workspace": "470000000000000031", "items": []}
El historial funciona con proyectos, artículos, publicaciones, documentos, hojas, tableros, espacios, rúbricas, campañas, oráculos, agendas, endpoints de API, enlaces, secretos, salas y cupones. {"enabled": false} lo desactiva.
Edita como siempre. Cada escritura del dueño o de un editor guarda primero el estado anterior como la siguiente versión.
Instantánea ahora (requiere write; sin cuerpo).
POST /v0/my/cards/470000000000000001/versions
→ {"version": 3, "nonce": "470000000000000043", "created_at": "2026-10-15T12:00:00Z", "author": "<user>"}
- Listar versiones.
GET /v0/my/cards/470000000000000001/versions
→ {"versioned": true, "workspace": "470000000000000031",
"items": [{"version": 1, "nonce": "470000000000000041", "created_at": "…", "author": "<user>"}, …]}
La versión 1 es la más antigua; los números no cambian nunca. Una versión se lee con el GET normal de la tarjeta sobre su nonce; GET /v0/my/cards/{snapshot}/versions responde version_of y version.
- Volver atrás.
POST /v0/my/cards/470000000000000001/versions/2/make-current
→ {"nonce": "470000000000000001", "restored": 2, "pushed": {"version": 4, "nonce": "…", …}}
El estado que era actual se guarda antes como la siguiente versión (pushed), así que la vuelta atrás también se puede deshacer.
En segundo plano
- Las versiones son copias archivadas de solo lectura. Las guarda el espacio de historial; es privado (Private), así que solo tú ves el historial hasta que compartas ese espacio con un enlace o un permiso.
authores el usuario cuya escritura llevó ese estado al historial.
Reglas
PUT: solo el dueño; si no, 404. 400history can be switched only on an original card(sobre una versión o un espacio de historial),history is not supported for <type>.POST …/versions: requiere write; si no, 404. 400history is off for this card; switch it on first.make-current: requiere write sobre la tarjeta y read sobre esa versión; si no, 404.- Cualquier escritura en una versión: 400
this card is a version snapshot and is read-only; use make-current on the original.
Superficie de la API
| Endpoint | Para qué | FE | IA / oráculo |
|---|---|---|---|
PUT /v0/my/cards/{nonce}/versions |
Activar o desactivar el historial | sí (Guardar historial) | sí, antes de editar tarjetas importantes |
GET /v0/my/cards/{nonce}/versions |
Listar versiones | sí (Historial) | sí |
POST /v0/my/cards/{nonce}/versions |
Instantánea ahora | sí (Guardar versión) | sí, como punto de control |
POST /v0/my/cards/{nonce}/versions/{version}/make-current |
Volver atrás | sí (Hacer actual) | sí |