Route Map
Every path below is under http://127.0.0.1:19821 and comes from the daemon’s
own OpenAPI document. Only /api/v1/token in the first group is reachable
without a bearer token.
Where the document carries no description for a route, none is invented here.
Fetch /api/v1/openapi.json, or open /api/v1/docs, for request and response
schemas.
System
Section titled “System”Is the daemon up, is it signed in, and when did it last talk to the server.
GET /api/v1/sync answers what the last sync did without doing another one;
POST runs one.
| Path | Methods |
|---|---|
/api/v1/status | GET |
/api/v1/sync | GET, POST |
/api/v1/token | POST |
/health and /api/v1/health also exist, outside the documented set.
Identity
Section titled “Identity”The two routes an integration usually wants.
POST /api/v1/verify checks three words against the connections this device
holds a secret for. It is purely local. Read the conclusive field before you
show anything: it is false whenever some connection could not be checked,
including the common case where nothing is cached. A caller must not say “not
verified” unless conclusive is true.
A match carries window — current, or previous for an earlier code the
operator still accepts (one by default), with windowsBack saying how far back
— and validUntil, the instant that code stops or stopped being current. Show a
previous match with that time in local time, and suggest a seal for a message
read later. On a connection where every member has their own code, memberName
says whose code it was. The reader’s own code never matches. This route and the
previous codes below need only a read-scoped token.
POST /api/v1/stamp signs content on the device and answers three words, the
time it was signed, an assurance level and the URL a recipient opens to check
the signature.
| Path | Methods |
|---|---|
/api/v1/stamp | POST |
/api/v1/verify | POST |
Following people, and the record of verifications.
POST /api/v1/verify/public is the other half of /api/v1/verify: it asks the
server whether three words belong to anybody, rather than checking locally.
The /api/v1/trust-cards routes list and change the people this account
follows. The path keeps an older name. The {id} on these routes is the id of
the person followed, not the id of the follow row.
| Path | Methods |
|---|---|
/api/v1/trust-cards | GET, POST |
/api/v1/trust-cards/{id} | PATCH, DELETE |
/api/v1/trust-cards/{id}/history | GET |
/api/v1/trust/metrics | GET |
/api/v1/verification-log | GET |
/api/v1/verify/public | POST |
Connections
Section titled “Connections”Create, read, rename and delete connections; read the current code for one; mark one a favourite; add and remove members.
GET /api/v1/connections/:id/members/:mid/previous-codes lists one member’s
previous codes, newest first, each with words, validFrom and validUntil;
:mid is the membership row id. previousWindows is how many the operator
accepts. available is false when this device holds no secret to derive them —
show that as “cannot show”, not as an empty list. It is local and records
nothing. A row that is not a member of that connection answers 404.
| Path | Methods |
|---|---|
/api/v1/connections | GET, POST |
/api/v1/connections/:id | GET, PATCH, DELETE |
/api/v1/connections/:id/code | GET |
/api/v1/connections/:id/favorite | POST |
/api/v1/connections/:id/members | POST |
/api/v1/connections/:id/members/:mid | DELETE |
/api/v1/connections/:id/members/:mid/previous-codes | GET |
Invitations
Section titled “Invitations”GET /api/v1/invitations lists both directions. The rest act on one invitation:
approve, decline, or withdraw one you sent.
| Path | Methods |
|---|---|
/api/v1/invitations | GET |
/api/v1/invitations/pending | GET |
/api/v1/invitations/:id/approve | POST |
/api/v1/invitations/:id/decline | POST |
/api/v1/invitations/:id/withdraw | POST |
Guest Codes
Section titled “Guest Codes”Create and revoke codes for people who do not use the app, fetch one as a QR image, or have it sent.
| Path | Methods |
|---|---|
/api/v1/guest-codes | GET, POST |
/api/v1/guest-codes/:id | DELETE |
/api/v1/guest-codes/:id/qr | GET |
/api/v1/guest-codes/:id/send | POST |
External Members
Section titled “External Members”The guest verification pages.
| Path | Methods |
|---|---|
/api/v1/external-members | GET, POST |
/api/v1/external-members/:id | DELETE |
Tags organise connections. The assign path takes both ids: the tag, then the connection.
| Path | Methods |
|---|---|
/api/v1/tags | GET, POST |
/api/v1/tags/:id | PATCH, DELETE |
/api/v1/tags/:id/assign/:cid | POST, DELETE |
Presets
Section titled “Presets”Connection presets, and which one is the default.
| Path | Methods |
|---|---|
/api/v1/presets | GET, POST |
/api/v1/presets/{id} | PATCH, DELETE |
/api/v1/presets/{id}/default | POST |
/api/v1/presets/default | DELETE |
Open Links
Section titled “Open Links”Open links and the approval requests they produce. A link can be paused, resumed
or given a new slug; a request can be approved or declined. suggest proposes a
slug.
| Path | Methods |
|---|---|
/api/v1/open-links | GET, POST |
/api/v1/open-links/suggest | GET |
/api/v1/open-links/{id} | DELETE |
/api/v1/open-links/{id}/pause | PATCH |
/api/v1/open-links/{id}/resume | PATCH |
/api/v1/open-links/{id}/slug | PATCH |
/api/v1/open-links/requests | GET |
/api/v1/open-links/requests/{id}/approve | POST |
/api/v1/open-links/requests/{id}/decline | POST |
Profile and Context
Section titled “Profile and Context”GET /api/v1/context answers account identity and organisation context in one
call — the active organisation is present only when there is one.
POST /api/v1/context/active-org switches the active organisation, or clears it
for personal context. It is session-scoped: it writes this session’s choice, not
the persistent user default, so a desktop choice does not retarget other
devices.
/api/v1/profiles/{id} is a minimal public profile of somebody else, and
/keys their active public keys.
| Path | Methods |
|---|---|
/api/v1/context | GET |
/api/v1/context/active-org | POST |
/api/v1/profile | GET, PATCH |
/api/v1/profiles/{id} | GET |
/api/v1/profiles/{id}/keys | GET |
/api/v1/preferences | GET, PATCH |
/api/v1/notifications | GET, DELETE |
/api/v1/notifications/read | POST |
Account
Section titled “Account”Devices, sessions, email addresses, data exports and account deletion.
An export is asked for and built by the server: POST /api/v1/exports answers
an id, not a file, and /api/v1/exports/{id}/download answers a signed,
expiring link to a finished one.
DELETE /api/v1/account deletes the account and everything in it, and cannot be
undone. It requires a body carrying confirmEmail, the account’s own address,
which the daemon compares on the machine before it calls anything. A call with
no body, or with the wrong address, is refused.
| Path | Methods |
|---|---|
/api/v1/devices | GET |
/api/v1/devices/{id} | DELETE |
/api/v1/sessions | GET |
/api/v1/sessions/{id} | DELETE |
/api/v1/emails | GET, POST |
/api/v1/exports | GET, POST, DELETE |
/api/v1/exports/{id}/download | GET |
/api/v1/account | DELETE |
Organisation Management
Section titled “Organisation Management”Members, groups, alerts and analytics.
The member, group and alert routes need a full token, on every method. The
activity and analytics reads are ordinary GETs and a read token is enough.
| Path | Methods |
|---|---|
/api/v1/org/members | GET |
/api/v1/org/members/{id} | GET |
/api/v1/org/members/{id}/activate | POST |
/api/v1/org/members/{id}/suspend | POST |
/api/v1/org/members/bulk-invite | POST |
/api/v1/org/groups | GET, POST |
/api/v1/org/groups/{id} | PATCH, DELETE |
/api/v1/org/groups/{id}/members | POST, DELETE |
/api/v1/org/alerts | GET, POST |
/api/v1/org/alerts/{id} | PATCH, DELETE |
/api/v1/org/activity | GET |
/api/v1/org/activity/summary | GET |
/api/v1/org/analytics/dashboard | GET |
/api/v1/org/analytics/trends | GET |
API Tokens
Section titled “API Tokens”Listing, minting and revoking tokens. Also full only.
| Path | Methods |
|---|---|
/api/v1/api-tokens | GET, POST |
/api/v1/api-tokens/{id} | DELETE |
Assistant and Feedback
Section titled “Assistant and Feedback”One turn of the assistant conversation, a rating for an answer, and feedback to the team. The chat answer is passed through from the server, so the daemon does not fix its shape.
| Path | Methods |
|---|---|
/api/v1/chat | POST |
/api/v1/chat/rate | POST |
/api/v1/feedback | POST |