API-пайплайн: делиться карточками через ссылки доступа

Цель: поделиться своими карточками с выбранными людьми или агендами через ссылку доступа — права, лимиты, срок; затем управлять ссылкой и теми, у кого она есть.

Правила прав и видимости: Граф Cabi.Chat — политики карточек

Шаги

1. Создать.

POST /v0/my/links
Idempotency-Key: 9b2e…
{"title": "Radar for a client", "link_publicity": "Ecosystem",
 "read": true, "write": true, "execute": false,
 "max_openers": 1, "expires_at": "2026-11-01T00:00:00Z",
 "grant_ttl": "7d", "claimable_by": "user",
 "targets": [{"card_type": "campaign", "nonce": "<your campaign>"}]}
→ {"nonce": "<link>", "token": "<token>", "status": "active", "read": true, "write": true, "execute": false,
   "grant_ttl": "7d", "claimable_by": "user", "targets": [{…}], …}

2. Отправить https://cabi.chat/l/<token>. Как принять ссылку: API-пайплайн: принять ссылку доступа

3. Ваши ссылки. GET /v0/my/links (?targets=<card> = ссылки на одну карточку, ?q= = поиск); GET /v0/my/links/<link>.

4. Настроить. PATCH /v0/my/links/<link> с title, targets, max_openers, expires_at, grant_ttl, claimable_by, link_publicity, status (active / revoked). Действует с этого момента.

5. У кого она есть.

GET /v0/my/links/<link>/grants
→ {"grants": [{"grant": "<id>", "subject": "<user>", "subject_type": "user", "project": "<their project>", "project_title": "…",
               "created_at": "…", "expires_at": "…", "status": "active", "targets": ["…"]}]}

6. Продлить, сократить или возобновить доступ одного держателя. PATCH /v0/my/links/<link>/grants/<grant> {"expires_at": "<RFC 3339>"}.

7. Отозвать доступ одного держателя. DELETE /v0/my/links/<link>/grants/<grant>.

8. Отозвать или удалить ссылку. PATCH … {"status": "revoked"} или DELETE /v0/my/links/<link>.

За кадром

• Когда заканчивается грант с w на кампанию, кампания ставится на паузу, если её не держит другой действующий грант с w.

Правила

• link_publicity: Everyone (по умолчанию: читает любой, у кого есть URL, без входа, только чтение) или Ecosystem (вошедшие получают грант). write, execute, max_openers и grant_ttl требуют Ecosystem → иначе 400.
• Права фиксируются при создании: изменить их → 400 link rights are immutable; mint a new link.
• targets: только ваши карточки → иначе 400 target <type>/<nonce> not found or not owned. Ссылка на воркспейс открывает ваши карточки внутри него.
• Приватная (Private) карточка не открывается никому, даже по ссылке: ссылка заработает, когда карточка станет Unlisted или Public.
• max_openers: сколько разных держателей могут принять ссылку; после этого новым она отвечает 404.
• expires_at: после этого момента ссылка ничего не открывает и никто новый не может её принять.
• grant_ttl: <N>d, <N>h или <N>m (от 60 с до 3650 д); каждый доступ длится столько с момента принятия. Один раз на человека: у человека и всех его агенд одно окно, а закончившийся грант нельзя принять снова.
• claimable_by: user (по умолчанию), agenda или both. Когда вы сами открываете свою ссылку, это не принятие.
• Отзыв у одного держателя закрывает ему доступ сразу, и он не сможет принять эту ссылку снова, пока вы его не возобновите (шаг 6). Для возобновления нужна активная, не истёкшая ссылка с targets → иначе 409.
• Отзыв ссылки удаляет её гранты. Грантами управляет владелец ссылки или любой, у кого есть w на ссылку.

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

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