API pipeline: Share cards through access links

Goal: share cards you own with chosen people or agendas through an access link: rights, limits, duration; then manage the link and who holds it.

Rules of rights and visibility: Cabi.Chat Graph — Card Policies

Steps

1. Mint.

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. Send https://cabi.chat/l/<token>. Claiming: API pipeline: Claim an access link

3. Your links. GET /v0/my/links (?targets=<card> = links on one card, ?q= = search); GET /v0/my/links/<link>.

4. Tune. PATCH /v0/my/links/<link> with title, targets, max_openers, expires_at, grant_ttl, claimable_by, link_publicity, status (active / revoked). Applies from then on.

5. Who holds it.

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. Extend, shorten or renew one holder. PATCH /v0/my/links/<link>/grants/<grant> {"expires_at": "<RFC 3339>"}.

7. Revoke one holder. DELETE /v0/my/links/<link>/grants/<grant>.

8. Revoke or delete the link. PATCH … {"status": "revoked"} or DELETE /v0/my/links/<link>.

Behind

• When a grant with w on a campaign ends, the campaign is paused unless another live w grant still holds it.

Rules

• link_publicity: Everyone (default: anyone with the URL reads, no sign-in, read-only) or Ecosystem (signed-in claimers get a grant). write, execute, max_openers and grant_ttl need Ecosystem → else 400.
• Rights are fixed at mint: changing them → 400 link rights are immutable; mint a new link.
• targets: cards you own → else 400 target <type>/<nonce> not found or not owned. A link on a workspace reaches the cards inside it that you own.
• A Private card shares nothing, even through a link: it starts working when the card is Unlisted or Public.
• max_openers: how many different holders may claim; after that the link answers 404 to new ones.
• expires_at: after it the link opens nothing and nobody new can claim.
• grant_ttl: <N>d, <N>h or <N>m (60 s to 3650 d); each claim lasts that long from its claim time. Once per person: a person and all their agendas share one window, and an ended grant cannot be claimed again.
• claimable_by: user (default), agenda or both. Your own opening of your link is not a claim.
• Revoking one holder ends their access now and they cannot claim this link again until you renew them (step 6). Renewing needs an active, unexpired link with targets → else 409.
• Revoking the link removes its grants. Grants are managed by the link's owner or anyone with w on the link.

API surface

Index: API pipelines — index