API-пайплайн: статьи и посты

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

Цель: написать статью (длинный формат) или пост (короткий; то, что кампании объявлений отправляют в группы Telegram) на одном или нескольких языках, с изображениями; выбрать, кто его видит; редактировать, архивировать или удалить.

Статьи и посты используют одни и те же вызовы. В путях ниже указано articles; для поста используйте posts.

Шаги

1. Загрузите изображения (по желанию).

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

Изображения хранятся в webp. Вставьте каждое в текст как ![caption](media:<hash>.webp).

2. Создание.

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

• Обязателен только title. language (по умолчанию en) становится каноническим языком.
• Новые карточки — Private. project: один из ваших проектов; карточка принадлежит ему (нужно для Unlisted и Public).
• workspaces: ваши рабочие пространства, куда положить карточку. handle: по желанию, хранится как a.<handle> для статей и p.<handle> для постов.
• rubrics, location: API-пайплайн: рубрики для карточек
• translate_mode: "auto" переводит машинно на translate_langs (из en, ru, es; по умолчанию — на все, кроме исходного).

3. Выберите, кто видит.

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

• visibility: Private, Unlisted (доступна по ссылке и через шаринг, никогда не попадает в списки) или Public.
• Unlisted и Public требуют привязки к проекту и явных permissions; Public требует также publicity: Everyone (в том числе анонимные посетители и поисковые системы) или Ecosystem (только вошедшие пользователи). Public не может давать право записи.
• Карточка никогда не видна шире, чем её проект. Правила: Граф Cabi.Chat — политики карточек

4. Правка. PATCH /v0/my/articles/{nonce} с любыми из title, content, handle, project, rubrics, location; статьи принимают также teaser (короткая строка на плитках).

• language выбирает язык, который вы редактируете (по умолчанию канонический); новый язык добавляется. canonical_lang меняет канонический язык (у него должен быть текст). i18n_source: {"ru": "machine"} помечает язык как машинный или authored.
• translate_mode / translate_langs работают так же, как при создании.
• При чтении изображения приходят подписанными ссылками; отправляйте текст обратно как есть или со ссылками media: — сохраняется одно и то же.

5. Архив или восстановление. POST /v0/my/archive {"nonce": "470000000000000042", "archived": true} → карточка уходит из ваших списков; GET /v0/my/articles?archived=true показывает архивные; "archived": false возвращает её.

6. Удаление. DELETE /v0/my/articles/{nonce} → {"success": true}. Статью — только владелец; пост — любой, у кого есть право записи на него.

Чтение.

• Ваши: GET /v0/my/articles?limit=20&offset=0 (scope: owned (по умолчанию), granted, all; archived=true). Одна: GET /v0/my/articles/{nonce|@handle} → все языки, карточки mentioned, rubrics, writable.
• Публичные: GET /v0/graph/articles, GET /v0/graph/articles/{nonce|@handle}. Без токена — только карточки Public для Everyone.

Что происходит за кадром

• Переводы выполняются после сохранения: перечитывайте карточку, пока язык не появится в i18n с source: "machine".
• Ссылки на карточки в тексте ([](https://cabi.chat/article/<nonce>)) становятся упоминаниями: они возвращаются в mentioned карточки.
• Пост попадает в Telegram только через кампанию объявлений, которая его несёт (пайплайн объявлений).

Правила (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.
• Загрузка: no image files in upload; at most 10 files per upload; не-изображения и файлы больше 10 МБ отклоняются.
• Карточка, в которую вы не можете писать: 404.

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