API-пайплайн: создание и редактирование страницы проекта

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

Цель: создать страницу своего проекта и поддерживать её в актуальном виде: текст, место, фото, контакты, переводы и кто её видит.

Шаги

1. Создание.

POST /v0/my/projects
Idempotency-Key: proj-bikes-1
{"title": "Bike repair in Lisbon", "content": "What I offer, prices, hours…",
 "language": "en", "handle": "example-bikes",
 "rubrics": ["<rubric nonce>"], "location": "<place nonce>",
 "translate_mode": "auto"}
→ {"nonce": "470000000000000001", "card_type": "project", "visibility": "Private", "handle": "example-bikes", …}

• title обязателен; language по умолчанию en (en, ru, es).
• handle: a-z, 0-9, _ . -, до 64 символов, уникальный; тогда страница доступна по https://cabi.chat/@example-bikes.
• rubrics: nonce тематических рубрик; location: nonce одного места (город, регион или страна). Как их найти: API-пайплайн: поиск по графу, API-пайплайн: поиск проектов по месту и на карте.
• translate_mode: auto (машинный перевод) или llm (через вашу агенду перевода; её стоимость видна в ваших расходах на ИИ: API-пайплайн: ваши расходы на ИИ); translate_langs ограничивает целевые языки. Переводы появляются чуть позже.
• Новый проект всегда Private.

2. Фото. Загрузите, затем прикрепите:

POST /v0/my/media/upload      (multipart/form-data, up to 10 images, 10 MB each)
→ {"files": [{"hash": "<sha256>", "format": "webp", "width": 1200, "height": 800, …}]}

PATCH /v0/my/projects/470000000000000001
{"avatar": "media:<sha256>.webp", "media_add": ["media:<sha256>.webp"]}

media заменяет всю галерею (по порядку, до 20; [] очищает её); media_add добавляет в конец; avatar задаёт круглую картинку. Не вставляйте изображения в content.

3. Контакты.

POST /v0/my/projects/470000000000000001/contacts
Idempotency-Key: proj-bikes-contact-1
{"kind": "Telegram", "value": "@example", "is_primary": true,
 "publicity": "Everyone", "requires_reveal": true}
→ {"nonce": "470000000000000011", "kind": "Telegram", "value": "@example", …}

• kind: Phone, Email, Website, Telegram, WhatsApp, Instagram, Facebook, TikTok, LinkedIn, Discord, X, YouTube, Other.
• publicity: Ecosystem (по умолчанию, только для вошедших) или Everyone. requires_reveal: true скрывает значение, пока посетитель его не запросит: API-пайплайн: открыть контакт проекта
• Основной контакт один: установка is_primary снимает его с остальных.
• Список: GET /v0/my/projects/{nonce}/contacts; правка: PATCH /v0/my/contacts/{nonce}; удаление: DELETE /v0/my/contacts/{nonce}.

4. Правка текста, места, рубрик: PATCH /v0/my/projects/{nonce} с любыми из title, content, language (на каком языке вы пишете), handle, rubrics, location, canonical_lang (исходный язык), translate_mode + translate_langs. Поля, которые вы не передали, не меняются.

5. Публикация.

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

• visibility: Public (в списках: главная, поиск, карта), Unlisted (только те, с кем вы поделились ссылкой или грантом) или Private (только вы).
• publicity (обязательно для Public): Everyone (кто угодно, в том числе без входа) или Ecosystem (только вошедшие).
• permissions (обязательно для Public или Unlisted): что может аудитория — read; write только для Unlisted; execute никогда для публичного проекта.

6. Проверка: GET /v0/graph/projects/{nonce | @handle} показывает страницу так, как её видят другие; GET /v0/my/projects/{nonce} — как её видит владелец.

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

• Понижение видимости проекта понижает и карточки, привязанные к нему: Private делает их Private, Unlisted делает публичные Unlisted.
• История версий, если вы её включите: API-пайплайн: история версий карточки. Архивация или удаление: API-пайплайн: архивировать, вернуть или удалить свои карточки.

Правила

• 400 title is required; handle may contain only a-z, 0-9, _ . -; handle is too long (max 64).
• 400 Public visibility requires explicit publicity, Public/Unlisted visibility requires explicit permissions, Public cards cannot grant write, Public projects cannot grant execute; share x by grants or links, Private cards carry no permissions.
• 400 media: at most 20 items, media_add: the gallery would have N photos, at most 20; …, avatar must be a media:<sha256>.<ext> ref …; загрузка: no image files in upload, at most 10 files per upload.
• 400 unknown contact kind: …, publicity must be Everyone or Ecosystem, got ….
• 400 без Idempotency-Key на двух вызовах создания.

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