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. |