Skip to content

Contacts

Handing a grant to a counterparty the workspace keeps in its address book. The grant is always minted in the caller's own workspace, so the caller keeps the side they can pause and revoke. Where the contact's address belongs to an account on this server the grant is also put in that person's own tray; otherwise the slug comes back for the caller to pass on. Nothing is pushed to another server.

POST /api/contacts/{id}/send

Share vault entries with a contact

Auth: Session

Mints a share of the named entries in the contact's workspace, owned by the caller, and answers with its slug.

Every entry and section must be one the caller may read in that workspace; an id alone is not permission, so one from anywhere else is reported as not found. Where the contact's address belongs to an account here the share is put in their tray — a bookmark they can remove, resolved through the same public view as the slug itself, with every gate and view cap still applying.

channel says how much of that the caller is told. It is handed_over, with delivered and emailed both false, unless something already connects the two: the contact was proven by the peer check, they share a workspace, or a grant has come the other way. Otherwise a precise answer would resolve any address that was typed in — delivered means it has an account here, and emailed, only ever attempted where it has none, means it does not. The slug is in every answer, so the grant can always be passed on by hand.

Deliveries into a tray are bounded per pair of accounts per day while nothing connects them (RATELIMIT_CONTACT_PAIR, 3), and a recipient may refuse a sender outright through contactBlocks. Neither refusal is reported: "you have had your three" and "you are blocked" are both answers about the address, and a sender who learns of a block opens another account. The delivered bookmark carries sender, which is what a block is aimed at.

A session is required: an API key authenticates as a program, and this is the one endpoint that writes into somebody else's account.

Two audit rows are written: the share's own creation, and the handover naming the contact, whether it arrived, and why it did not.

Parameters

Name In Required Notes
id path yes

Request body

application/json

Field Type Notes
records array of string Vault entry ids to share.
sections array of string Vault section ids to share as units — entries added to one later are shared too. At least one record or section is required.
label string What the recipient sees this share called.
expiresAt string
maxViews integer Views allowed before the share revokes itself.

Responses

Status Meaning
200 The share, and whether it reached an account here.
400 Refused, with a named reason.
401 Refused, with a named reason.
403 Refused, with a named reason.
404 Refused, with a named reason.
429 Refused, with a named reason.

Response fields

Field Type Notes
ok boolean
id string
slug string
kind string (share)
channel string (account | email | manual | handed_over) Where it went, as far as the caller is told. handed_over is the answer for a contact nothing connects them to, and for a refused delivery: the grant exists, the slug is here, and nothing is said about the address. delivered and emailed are then both false, which does not mean nothing arrived.
delivered boolean It is in the recipient's tray on this server. Only ever true alongside channel: account.
emailed boolean The link was queued to be emailed to the contact's address — queued, not accepted by a mail server. Only ever true when delivered is false, where the address has no account here, and where the operator's mail.recipients policy admits it. The email carries what the grant is called and a link, never what was shared.

POST /api/contacts/{id}/deliver

Deliver an existing share or request to a contact

Auth: Session

Hands an existing grant to a contact without creating a new share or request. Its id, slug, protections and response inbox are preserved.

A user session is required; API keys are refused. The contact must be visible to the caller, and the grant must be owned by the caller in the contact's workspace. The caller must also have permission to create the corresponding kind of grant in that workspace. Missing, inaccessible, other-owner and other-workspace grants return 404. Paused, revoked, expired or completed grants, and grants whose view or response cap has been reached, return 400.

Delivery uses the same tray, email, blocking, per-pair limits and privacy-preserving response rules as /api/contacts/{id}/send and /api/contacts/{id}/ask. handed_over does not confirm whether the address has an account or whether delivery was refused. A repeated delivery does not queue a second successful email invitation for the same grant and recipient address.

Shares with encrypted link-key wraps always return channel: manual, with delivered and emailed false. Their fragment keys stay on the caller's devices; the caller must share the complete address manually.

Parameters

Name In Required Notes
id path yes Contact receiving the existing grant.

Request body

application/json

Field Type Notes
kind string (share | request)
id string Existing link or request id, owned by the caller.
locale string Optional language hint for the email invitation.

Responses

Status Meaning
200 The original grant and the permitted delivery outcome.
400 Refused, with a named reason.
401 Refused, with a named reason.
403 Refused, with a named reason.
404 Refused, with a named reason.
429 Refused, with a named reason.

Response fields

Field Type Notes
ok boolean
id string
slug string
kind string (share | request)
channel string (account | email | manual | handed_over)
delivered boolean In the recipient's tray; only true with channel: account.
emailed boolean Queued for email; only true with channel: email.

POST /api/contacts/{id}/ask

Ask a contact for data

Auth: Session

Mints a request in the contact's workspace, owned by the caller, and answers with its slug.

identity is required and must be one the workspace holds: the name on an ask is what the responder is asked to trust. Without a template the responder may send whatever they choose. maxResponses defaults to 1, because an ask is addressed to one person — left uncapped it is a form anyone holding the slug can keep filling in.

Where the contact's address belongs to an account here the ask is put in their tray, as something to answer rather than something to read. channel says how much of that the caller is told, with the same reserve as /api/contacts/{id}/send: handed_over unless something already connects the two, and the same per-pair cap and blocks behind it.

Two audit rows are written: the request's own creation, and the handover naming the contact, whether it arrived, and why it did not.

Parameters

Name In Required Notes
id path yes

Request body

application/json

Field Type Notes
label string What the recipient sees they are being asked for.
identity string Identity signing the ask; must belong to the workspace.
template string Form the answer must match; omit to accept anything.
expiresAt string
maxResponses integer

Responses

Status Meaning
200 The request, and whether it reached an account here.
400 Refused, with a named reason.
401 Refused, with a named reason.
403 Refused, with a named reason.
404 Refused, with a named reason.
429 Refused, with a named reason.

Response fields

Field Type Notes
ok boolean
id string
slug string
kind string (request)
channel string (account | email | manual | handed_over) As for a share: handed_over where the caller is told nothing about the address, which is every contact nothing connects them to.
delivered boolean It is in the recipient's tray. Only ever true alongside channel: account.
emailed boolean The request was queued to be emailed. As for a share, plus one condition: answering needs an account, so an ask is only emailed while signups are open. The link goes to the sign-up page, which opens the request in the app afterwards.