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
identityrelation 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. |