Shares¶
Reading a share by slug. The probe reports gates without revealing data; the resolve returns data and consumes a view.
GET /api/public/links/{slug}¶
Probe a share
Unauthenticated
Callable with no credential.
Reports whether a share exists and what stands between the caller and its data. It never returns the data itself, and it does not consume a view — so a client can render a password prompt or a trust panel before spending the one read it may be allowed.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
slug |
path | yes | The capability. Unguessable by construction and never derived from anything user-visible — whoever holds it holds the access. |
Responses
| Status | Meaning |
|---|---|
200 |
The share's gates and the sharer's claim. |
404 |
No such resource, or the caller may not see it. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
slug |
string | |
label |
string | |
status |
string (active | paused | revoked | expired) |
|
requiresPassword |
boolean | |
requireHandshake |
boolean | Whether a proven identity is required. |
watermarked |
boolean | Whether served files are stamped with who they were sent to. |
purpose |
string | application marks a rental application, which is always watermarked; empty for a plain share. |
identity |
string | |
sharer |
Sharer | |
server |
ServerClaim |
POST /api/public/links/{slug}¶
Resolve a share
Unauthenticated
Callable with no credential.
Returns the share's current values and consumes one view. POST rather than GET so the password and handshake material travel in the body rather than in a URL that lands in logs and history.
The view claim is atomic: if a concurrent reader takes the last permitted view, this request is refused rather than served.
Values are resolved at read time, so what comes back is what the record holds now — not what it held when the share was created.
An end-to-end encrypted entry comes back with sealed: true and no
value: sealedValue and sealedVersion are the entry as members
hold it, and viewerWrap is its value key wrapped for this share. The
key to that wrap is derived from the part of the share's address after
#, which never reaches the server. An entry marked unavailable
carries none of the three: the share has not caught up with it. An
encrypted entry the share holds no key for is left out.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
slug |
path | yes | The capability. Unguessable by construction and never derived from anything user-visible — whoever holds it holds the access. |
Request body
application/json
| Field | Type | Notes |
|---|---|---|
password |
string | Required when the probe reported requiresPassword. |
identityId |
string | |
handshakeToken |
string | |
challengeNonce |
string | |
challengeSignature |
string |
Responses
| Status | Meaning |
|---|---|
200 |
The share's contents, and the view count after this read. |
401 |
The password gate refused. link_password_required or link_password_invalid. |
404 |
No such resource, or the caller may not see it. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
slug |
string | |
label |
string | |
purpose |
string | application, or empty for a plain share. |
identity |
string | |
sections |
array of object | How the records are grouped: the sections the link names, then each section of the owner's vault holding a record the link grants, with id, key, name and the ids of its granted records. A section grants nothing itself. |
records |
array of object | File records carry a downloadToken, which already carries this read's view claim — so fetching the bytes is never a second claim and never claim-free. |
viewCount |
integer | |
watermark |
string | The stamp line; present only on a watermarked share. |
archiveToken |
string | Present when the share grants at least one file. Opens /api/public/links/{slug}/archive once, within two minutes, like a downloadToken. |
GET /api/public/links/{slug}/files/{recordId}¶
Download a shared file
Unauthenticated
Callable with no credential.
Serves the bytes behind a file record, authorised by the
downloadToken the resolve returned.
The token carries that resolve's view claim, so a download neither consumes a second view nor bypasses the cap. It is single-use and bound to this slug and record — it will not open a different file, and it will not open this one twice.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
slug |
path | yes | The capability. Unguessable by construction and never derived from anything user-visible — whoever holds it holds the access. |
recordId |
path | yes | The file record's id, as returned by the resolve. |
dl |
query | yes | The downloadToken from the resolve response. |
Responses
| Status | Meaning |
|---|---|
200 |
The file, with its own content type. |
415 |
file_not_watermarkable: the share stamps its files, and this type cannot carry a stamp. |
401 |
The token was missing, spent, or not for this file. |
404 |
No such resource, or the caller may not see it. |
GET /api/public/links/{slug}/archive¶
Download every shared file as a zip
Unauthenticated
Callable with no credential.
A zip of every file the share grants, directly or through its
sections, authorised by the archiveToken the resolve returned. Like a
downloadToken, it carries that resolve's view claim, is single-use
and bound to this slug.
On a watermarked share every entry is a stamped copy, and a file that
cannot be stamped is left out — never included unmarked. Entries are
named after the file, deduplicated as name (2).pdf.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
slug |
path | yes | The capability. Unguessable by construction and never derived from anything user-visible — whoever holds it holds the access. |
dl |
query | yes | The archiveToken from the resolve response. |
Responses
| Status | Meaning |
|---|---|
200 |
The archive, as an attachment named after the share. |
401 |
file_download_invalid: the token was missing, spent, or not for this share. |
404 |
archive_empty when no file could go in, or the share no longer exists. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
GET /s/{slug}¶
Human-readable share page
Unauthenticated
Callable with no credential.
A server-rendered page for the same slug, so a recipient needs no app and no client code. Content negotiation also serves machine formats — CSV, vCard and iCal — with ETag and conditional requests, which is what makes a share consumable by a spreadsheet or a calendar directly.
The format is chosen, first match wins, by:
- a suffix on the slug:
.json,.csv,.txt,.vcfor.ics(/s/abc123.csv); raw, which selects plain text;- the
Acceptheader:text/csv,text/calendar,text/vcard,text/plain, andtext/htmlfor the page; - JSON otherwise.
The page is served only without a suffix, key and raw. Every
machine format consumes a view, except a 304. A share that requires
a proven identity is never served here (handshake_required); a
password-protected one takes password.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
slug |
path | yes | The capability. Unguessable by construction and never derived from anything user-visible — whoever holds it holds the access. |
key |
query | no | Serve this one value instead of the whole share. |
raw |
query | no | Any value selects plain text, unless the slug has a suffix. |
password |
query | no | The share's password, when it has one. |
Responses
| Status | Meaning |
|---|---|
200 |
The share, in the chosen format. |
304 |
Not modified since the If-None-Match ETag. Consumes no view. |
403 |
Paused (link_paused), or gated: handshake_required, link_password_required or link_password_invalid, with protected: true and requireHandshake or requiresPassword. |
404 |
link_not_found, or link_key_not_found for a key the share does not hold. |
410 |
Revoked, expired or out of views. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
slug |
string | |
key |
string | |
value |
string | |
label |
string | |
purpose |
string | |
records |
array of object | |
sections |
array of object | |
updated_at |
string | |
verified |
boolean | Whether the share names an identity. |
viewCount |
integer | |
watermark |
string |
GET /dav/s/{slug}/¶
CardDAV addressbook for a share
Unauthenticated
Callable with no credential.
A read-only, single-card addressbook so a contacts app can subscribe to a share and stay in sync. Gated shares — password or handshake — are never exposed over DAV, because the protocol has nowhere to put the gate.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
slug |
path | yes | The capability. Unguessable by construction and never derived from anything user-visible — whoever holds it holds the access. |
Responses
| Status | Meaning |
|---|---|
200 |
A DAV collection; the card is at contact.vcf. |