Skip to content

Records

The vault. Records hold the values that shares resolve at read time.

POST /api/stamp-preview

Preview a file with a stamp on it

Auth: ApiKey, Session

Returns a stamped copy of a file record the caller may read. Pass text to try a stamp before creating a share — the line ends in #preview, so the copy can never pass for one read through a real share. Or pass link to see exactly what that share hands out; the share must grant the record. When link is set, text is ignored.

Request body

application/json

Field Type Notes
record string The file record's id.
text string One line of 1 to 120 characters, trimmed.
link string A share's id.

Responses

Status Meaning
200 The stamped copy, as an attachment named <name>-preview<ext>.
400 watermark_text_invalid.
401 Refused, with a named reason.
404 record_not_found or link_not_found: missing, not visible to the caller, not a file, or not granted by the share.
415 file_not_watermarkable.
429 Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced.

GET /api/collections/{collection}/records

List records

Auth: ApiKey, Session

Standard record listing. Results are already narrowed to what the caller may see, so an empty page means "nothing you can read", not "nothing exists".

Parameters

Name In Required Notes
collection path yes Which collection to act on.
filter query no PocketBase filter expression.
sort query no
page query no
perPage query no

Responses

Status Meaning
200 A page of records.
401 Refused, with a named reason.
403 Refused, with a named reason.

Response fields

Field Type Notes
page integer
perPage integer
totalItems integer
totalPages integer
items array of object

POST /api/collections/{collection}/records

Create a record

Auth: ApiKey, Session

Field requirements vary by collection; see the reference table in the Records guide. Two rules hold everywhere:

  • An identity relation is ownership-checked. Attaching an identity you do not own is refused — identity ids are public, and attaching a foreign one is exactly the impersonation this product exists to stop.
  • Vault records are created here; request-collected rows are minted server-side and never through this endpoint.

File records are sent as multipart/form-data with the bytes in a file part. Stream them: the operator's size cap is advertised at GET /api/server under limits.maxFileSize.

Parameters

Name In Required Notes
collection path yes Which collection to act on.

Request body

application/json

multipart/form-data

Field Type Notes
file string

Responses

Status Meaning
200 The created record.
400 Refused, with a named reason.
403 Refused with a named reason — which scope is missing, which workspace a key is bound to — rather than a bare denial.

GET /api/collections/{collection}/records/{id}

Read one record

Auth: ApiKey, Session

Parameters

Name In Required Notes
collection path yes Which collection to act on.
id path yes

Responses

Status Meaning
200 The record.
404 No such resource, or the caller may not see it.

PATCH /api/collections/{collection}/records/{id}

Update a record

Auth: ApiKey, Session

Updating a record updates every share that points at it, on their next read — that is the rotation gesture, not a side effect.

Some transitions are one-way: an identity may go from active to revoked and never back, because a revocation is a statement already published to verifiers who may have cached it.

Parameters

Name In Required Notes
collection path yes Which collection to act on.
id path yes

Request body

application/json

multipart/form-data

Field Type Notes
file string

Responses

Status Meaning
200 The updated record.
403 Refused, with a named reason.
404 No such resource, or the caller may not see it.

DELETE /api/collections/{collection}/records/{id}

Delete a record

Auth: ApiKey, Session

Deleting a workspace takes its entire contents with it — records, files, templates, members, API keys — and revokes the identities it issued, leaving tombstones so those certificates stop verifying.

Deleting an identity likewise leaves a tombstone, so its fingerprint keeps resolving to a definite answer rather than to silence.

Parameters

Name In Required Notes
collection path yes Which collection to act on.
id path yes

Responses

Status Meaning
204 Deleted.
403 Refused, with a named reason.
404 No such resource, or the caller may not see it.

POST /api/files/token

Mint a file access token

Auth: ApiKey, Session

File fields are protected, so a bare file URL serves nothing. This returns a short-lived token to append to a file request as ?token=. For files reached through a share, use the downloadToken from the resolve instead.

Responses

Status Meaning
200 A file access token.
401 Refused, with a named reason.

Response fields

Field Type Notes
token string