API pipeline: Write articles and posts

Index: API pipelines — index

Goal: write an article (long form) or a post (short; what announcement campaigns send to Telegram groups) in one or more languages, with images; choose who sees it; edit, archive or delete it.

Articles and posts take the same calls. Paths below say articles; use posts for a post.

Steps

1. Upload images (optional).

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, …}]}

Images are stored as webp. Put each into the text as ![caption](media:<hash>.webp).

2. Create.

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": "…"}], …}

• Only title is required. language (default en) becomes the canonical language.
• New cards are Private. project: one of your projects; the card belongs to it (needed for Unlisted and Public).
• workspaces: workspaces of yours to place the card into. handle: optional, stored as a.<handle> for articles, p.<handle> for posts.
• rubrics, location: API pipeline: Tag cards with rubrics
• translate_mode: "auto" machine-translates into translate_langs (from en, ru, es; default: all but the source).

3. Choose who sees it.

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

• visibility: Private, Unlisted (reachable by link and shares, never listed) or Public.
• Unlisted and Public need the project anchor and explicit permissions; Public also needs publicity: Everyone (also anonymous visitors and search engines) or Ecosystem (signed-in users only). Public cannot grant write.
• A card is never more visible than its project. Rules: Cabi.Chat Graph — Card Policies

4. Edit. PATCH /v0/my/articles/{nonce} with any of title, content, handle, project, rubrics, location; articles also take teaser (the short line shown on tiles).

• language picks the language you edit (default: canonical); a new language is added. canonical_lang switches the canonical one (it must have text). i18n_source: {"ru": "machine"} marks a language machine-made or authored.
• translate_mode / translate_langs work as on create.
• Reads return images as signed links; send the text back as is or with media: refs: both store the same.

5. Archive or restore. POST /v0/my/archive {"nonce": "470000000000000042", "archived": true} → it leaves your lists; GET /v0/my/articles?archived=true shows archived ones; "archived": false brings it back.

6. Delete. DELETE /v0/my/articles/{nonce} → {"success": true}. An article only by its owner; a post by anyone with write on it.

Read.

• Yours: GET /v0/my/articles?limit=20&offset=0 (scope: owned (default), granted, all; archived=true). One: GET /v0/my/articles/{nonce|@handle} → every language, mentioned cards, rubrics, writable.
• Public: GET /v0/graph/articles, GET /v0/graph/articles/{nonce|@handle}. Without a token only Public cards for Everyone.

Behind

• Translations run after the save: read the card again until the language shows up in i18n with source: "machine".
• Card links in the text ([](https://cabi.chat/article/<nonce>)) become mentions: they come back in mentioned on the card.
• A post reaches Telegram only through an announcement campaign that carries it (announcements pipeline).

Rules (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.
• Upload: no image files in upload; at most 10 files per upload; non-images and files over 10 MB are refused.
• A card you cannot write: 404.

API surface