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

For the owner-only bookmarks collection, optional sealedKey and keyEpoch retain an address key wrapped under the owner's account key. They are either empty/zero, or a version-1 AEAD envelope of 32 bytes at a positive epoch. Request bookmarks cannot carry these fields. The associated-data format and local replay checks are documented in /api/encrypted-links/. Raw address keys are never stored here.

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.

A share bookmark can include sealedKey and keyEpoch: an address key wrapped under its owner's account key, never the raw #k= key. Both must be empty/zero or a correctly sized version-1 envelope at a positive epoch. Request bookmarks cannot carry them. The cryptographic context is described in the Encrypted links and saved keys guide.

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.

Bookmark sealedKey and keyEpoch change together; clearing them uses an empty key and epoch zero. The owner-only rules still apply.

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

POST /api/collections/users/auth-refresh

Renew a session

Auth: Session

PocketBase's own refresh: a new session token for the one sent, and the account as it is now. Sign-in itself happens with a passkey (/api/passkeys/login/*); password sign-in is switched off.

Responses

Status Meaning
200 A fresh token and the account record.
401 Refused, with a named reason.

Response fields

Field Type Notes
token string
record object
meta object

POST /api/collections/users/request-verification

Request a verification mail (switched off)

Unauthenticated

Callable with no credential.

PocketBase's own route. Addresses are confirmed with a code at sign-up (/api/passkeys/register/email), so this always answers 204, as it would for an unknown address, and sends nothing.

Request body

application/json

Field Type Notes
email string

Responses

Status Meaning
204 Accepted; no mail is sent.

GET /api/files/{collection}/{id}/{filename}

Download a record's file

Unauthenticated

Callable with no credential.

A file field's bytes. File fields are protected, so the request carries a token from POST /api/files/token as ?token=, and the caller must be allowed to read the record.

Parameters

Name In Required Notes
collection path yes Which collection to act on.
id path yes
filename path yes The stored file name, as the record’s file field holds it.
token query yes A file token from POST /api/files/token.
download query no Any value asks for Content-Disposition: attachment.

Responses

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