Pipeline de API: escribir artículos y publicaciones

Índice: Pipelines de API — índice

Objetivo: escribir un artículo (formato largo) o una publicación (corta; lo que las campañas de anuncios envían a los grupos de Telegram) en uno o varios idiomas, con imágenes; elegir quién la ve; editarla, archivarla o eliminarla.

Artículos y publicaciones usan las mismas llamadas. Las rutas de abajo dicen articles; usa posts para una publicación.

Pasos

1. Sube imágenes (opcional).

POST /v0/my/media/upload          multipart/form-data: up to 10 image files, 10 MB each
→ {"files": [{"hash": "9f2c…e41a", "format": "webp", "width": 1280, "height": 720, "size": 81234, …}]}

Las imágenes se guardan en webp. Inserta cada una en el texto como ![caption](media:<hash>.webp).

2. Crear.

POST /v0/my/articles
Idempotency-Key: art-7d1e…
{"title": "Spring menu",
 "content": "Fresh pasta every day.\n\n![Our kitchen](media:9f2c…e41a.webp)",
 "language": "en",
 "project": "470000000000000001",
 "rubrics": ["<rubric nonce>"], "location": "<place nonce>",
 "translate_mode": "auto", "translate_langs": ["ru", "es"]}
→ {"nonce": "470000000000000042", "card_type": "article", "visibility": "Private",
   "canonical_lang": "en", "i18n": [{"lang": "en", "source": "authored", "title": "Spring menu", "content": "…"}], …}

• Solo title es obligatorio. language (por defecto en) pasa a ser el idioma canónico.
• Las tarjetas nuevas son Private. project: uno de tus proyectos; la tarjeta le pertenece (necesario para Unlisted y Public).
• workspaces: espacios de trabajo tuyos donde colocar la tarjeta. handle: opcional, se guarda como a.<handle> para artículos y p.<handle> para publicaciones.
• rubrics, location: Pipeline de API: etiquetar tarjetas con rúbricas
• translate_mode: "auto" traduce automáticamente a translate_langs (entre en, ru, es; por defecto: todos menos el de origen).

3. Elige quién la ve.

PATCH /v0/my/articles/470000000000000042
{"visibility": "Public", "publicity": "Everyone",
 "permissions": {"read": true, "write": false, "execute": false}}

• visibility: Private, Unlisted (accesible por enlace y al compartir, nunca listada) o Public.
• Unlisted y Public necesitan el anclaje al proyecto y permissions explícitos; Public además necesita publicity: Everyone (también visitantes anónimos y buscadores) o Ecosystem (solo usuarios con sesión iniciada). Public no puede conceder escritura.
• Una tarjeta nunca es más visible que su proyecto. Reglas: Grafo de Cabi.Chat — Políticas de tarjetas

4. Editar. PATCH /v0/my/articles/{nonce} con cualquiera de title, content, handle, project, rubrics, location; los artículos también aceptan teaser (la línea corta que se muestra en las fichas).

• language elige el idioma que editas (por defecto, el canónico); un idioma nuevo se añade. canonical_lang cambia el canónico (debe tener texto). i18n_source: {"ru": "machine"} marca un idioma como traducido automáticamente o authored.
• translate_mode / translate_langs funcionan como al crear.
• Las lecturas devuelven las imágenes como enlaces firmados; reenvía el texto tal cual o con referencias media:: ambas guardan lo mismo.

5. Archivar o restaurar. POST /v0/my/archive {"nonce": "470000000000000042", "archived": true} → sale de tus listas; GET /v0/my/articles?archived=true muestra las archivadas; "archived": false la recupera.

6. Eliminar. DELETE /v0/my/articles/{nonce} → {"success": true}. Un artículo, solo su propietario; una publicación, cualquiera con escritura sobre ella.

Leer.

• Las tuyas: GET /v0/my/articles?limit=20&offset=0 (scope: owned (por defecto), granted, all; archived=true). Una: GET /v0/my/articles/{nonce|@handle} → todos los idiomas, tarjetas mentioned, rubrics, writable.
• Públicas: GET /v0/graph/articles, GET /v0/graph/articles/{nonce|@handle}. Sin token, solo las tarjetas Public para Everyone.

Detrás

• Las traducciones se hacen después de guardar: vuelve a leer la tarjeta hasta que el idioma aparezca en i18n con source: "machine".
• Los enlaces a tarjetas en el texto ([](https://cabi.chat/article/<nonce>)) se convierten en menciones: vuelven en mentioned de la tarjeta.
• Una publicación llega a Telegram solo mediante una campaña de anuncios que la lleve (pipeline de anuncios).

Reglas (400)

• title is required; handle may contain only a-z, 0-9, _ . -; handle is too long (max 64).
• project not found; project is not readable; card visibility Public exceeds project visibility Unlisted; unlisted and public cards must anchor to a project.
• Public/Unlisted visibility requires explicit permissions; Public visibility requires explicit publicity; Public cards cannot grant write; Private cards carry no permissions.
• Subida: no image files in upload; at most 10 files per upload; se rechazan los archivos que no son imágenes y los de más de 10 MB.
• Una tarjeta en la que no puedes escribir: 404.

Superficie de la API