Documents

List documents

GET /api/v1/apps/{appId}/collections/{collection}/docs

A page of the documents the caller may read. Query parameters: limit (default 50, at most 1000) and cursor.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, collection.

Response (200, JSON):

Field	Type	Required	Notes
next	string	no
rows	array of object	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/apps/{appId}/collections/{collection}/docs" \
  -H "Authorization: Bearer $TOKEN"

Create a document

POST /api/v1/apps/{appId}/collections/{collection}/docs

Creates a JSON document. The caller owns it.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, collection.

Request body (JSON):

Field	Type	Required	Notes
values	object	yes

Response (200, JSON):

Field	Type	Required	Notes
(body)	object	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X POST "https://node.example.com/api/v1/apps/{appId}/collections/{collection}/docs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"values": {}}'

One document

GET /api/v1/apps/{appId}/collections/{collection}/docs/{id}

One document, with its version.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, collection, id.

Response (200, JSON):

Field	Type	Required	Notes
(body)	object	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/apps/{appId}/collections/{collection}/docs/{id}" \
  -H "Authorization: Bearer $TOKEN"

Replace a document (version-checked)

PUT /api/v1/apps/{appId}/collections/{collection}/docs/{id}

Replaces a document’s data. It needs the version the caller last read, in the body or as If-Match; 409 when it changed since.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, collection, id.

Request body (JSON):

Field	Type	Required	Notes
values	object	yes
version	integer	no

Response (200, JSON):

Field	Type	Required	Notes
(body)	object	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X PUT "https://node.example.com/api/v1/apps/{appId}/collections/{collection}/docs/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"values": {}}'

Merge a document (version-checked)

PATCH /api/v1/apps/{appId}/collections/{collection}/docs/{id}

Merges fields into a document’s data. It needs the version the caller last read, in the body or as If-Match; 409 when it changed since.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, collection, id.

Request body (JSON):

Field	Type	Required	Notes
values	object	yes
version	integer	no

Response (200, JSON):

Field	Type	Required	Notes
(body)	object	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X PATCH "https://node.example.com/api/v1/apps/{appId}/collections/{collection}/docs/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"values": {}}'

Delete a document

DELETE /api/v1/apps/{appId}/collections/{collection}/docs/{id}

Deletes a document the caller may delete.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, collection, id.

Response: no body on success.

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X DELETE "https://node.example.com/api/v1/apps/{appId}/collections/{collection}/docs/{id}" \
  -H "Authorization: Bearer $TOKEN"

Query documents

POST /api/v1/apps/{appId}/collections/{collection}/docs:query

Documents matching a filter on their top-level fields, with the same filter language, sort, limit and cursor as table queries.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, collection.

Request body (JSON):

Field	Type	Required	Notes
cursor	string	no
filter	object	no
filter.and	array of object	no
filter.field	string	no
filter.not	object	no	recursive
filter.op	string	no
filter.or	array of object	no
filter.value	any	no
limit	integer	no
select	array of string	no
sort	array of object	no
sort[].dir	string	yes
sort[].field	string	yes

Response (200, JSON):

Field	Type	Required	Notes
next	string	no
rows	array of object	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X POST "https://node.example.com/api/v1/apps/{appId}/collections/{collection}/docs:query" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'