Pipeline de API: compartir tarjetas con enlaces de acceso

Objetivo: compartir tarjetas tuyas con personas o agendas elegidas mediante un enlace de acceso —derechos, límites, duración— y luego gestionar el enlace y quién lo tiene.

Reglas de derechos y visibilidad: Grafo de Cabi.Chat — Políticas de tarjetas

Pasos

1. Crear.

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. Envía https://cabi.chat/l/<token>. Cómo se reclama: Pipeline de API: reclamar un enlace de acceso

3. Tus enlaces. GET /v0/my/links (?targets=<card> = enlaces de una tarjeta, ?q= = búsqueda); GET /v0/my/links/<link>.

4. Ajustar. PATCH /v0/my/links/<link> con title, targets, max_openers, expires_at, grant_ttl, claimable_by, link_publicity, status (active / revoked). Se aplica desde ese momento.

5. Quién lo tiene.

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. Extender, acortar o renovar a un titular. PATCH /v0/my/links/<link>/grants/<grant> {"expires_at": "<RFC 3339>"}.

7. Revocar a un titular. DELETE /v0/my/links/<link>/grants/<grant>.

8. Revocar o eliminar el enlace. PATCH … {"status": "revoked"} o DELETE /v0/my/links/<link>.

En segundo plano

• Cuando termina una concesión con w sobre una campaña, la campaña se pausa salvo que otra concesión w vigente la sostenga.

Reglas

• link_publicity: Everyone (por defecto: cualquiera con la URL lee, sin iniciar sesión, solo lectura) o Ecosystem (quien reclama con sesión iniciada recibe una concesión). write, execute, max_openers y grant_ttl requieren Ecosystem → si no, 400.
• Los derechos se fijan al crear: cambiarlos → 400 link rights are immutable; mint a new link.
• targets: tarjetas tuyas → si no, 400 target <type>/<nonce> not found or not owned. Un enlace a un espacio llega a las tarjetas tuyas que contiene.
• Una tarjeta privada (Private) no comparte nada, ni siquiera con un enlace: empieza a funcionar cuando la tarjeta es Unlisted o Public.
• max_openers: cuántos titulares distintos pueden reclamarlo; después el enlace responde 404 a los nuevos.
• expires_at: a partir de ahí el enlace no abre nada y nadie nuevo puede reclamarlo.
• grant_ttl: <N>d, <N>h o <N>m (de 60 s a 3650 d); cada reclamación dura eso desde su momento. Una vez por persona: una persona y todas sus agendas comparten una misma ventana, y una concesión terminada no se puede volver a reclamar.
• claimable_by: user (por defecto), agenda o both. Abrir tu propio enlace no es reclamarlo.
• Revocar a un titular le quita el acceso en el acto y no puede reclamar este enlace otra vez hasta que lo renueves (paso 6). Renovar requiere un enlace activo, sin caducar y con targets → si no, 409.
• Revocar el enlace elimina sus concesiones. Las gestiona el dueño del enlace o cualquiera con w sobre él.

Superficie de la API

Índice: Pipelines de API — índice