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.
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. |
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.
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 rendered share, in the negotiated format. |
404 |
No such resource, or the caller may not see it. |
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. |