Tables

List table rows (keyset page)

GET /api/v1/apps/{appId}/tables/{table}/rows

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

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, table.

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}/tables/{table}/rows" \
  -H "Authorization: Bearer $TOKEN"

Create a table row

POST /api/v1/apps/{appId}/tables/{table}/rows

Creates a row from values: column name to value, checked against the manifest’s columns. The caller owns the row.

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, table.

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}/tables/{table}/rows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"values": {}}'

One table row

GET /api/v1/apps/{appId}/tables/{table}/rows/{id}

One row, 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, table, 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}/tables/{table}/rows/{id}" \
  -H "Authorization: Bearer $TOKEN"

Patch a row (version-checked)

PATCH /api/v1/apps/{appId}/tables/{table}/rows/{id}

Changes some of a row’s values. It needs the version the caller last read, in the body or as If-Match; a row changed since, or not there, answers 409.

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, table, 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}/tables/{table}/rows/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"values": {}}'

Delete a row

DELETE /api/v1/apps/{appId}/tables/{table}/rows/{id}

Deletes a row 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, table, 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}/tables/{table}/rows/{id}" \
  -H "Authorization: Bearer $TOKEN"

Atomic batch of row writes

POST /api/v1/apps/{appId}/tables/{table}/rows:batch

Up to 100 row writes (create, update with its version, delete) applied together: all of them, or none.

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, table.

Request body (JSON):

Field	Type	Required	Notes
ops	array of object	yes
ops[].id	string	no
ops[].op	string	yes
ops[].values	object	no
ops[].version	integer	no

Response (200, JSON):

Field	Type	Required	Notes
results	array of object	yes
results[].id	string	yes
results[].index	integer	yes
results[].row	object	no

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

curl -X POST "https://node.example.com/api/v1/apps/{appId}/tables/{table}/rows:batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ops": []}'

Query table rows

POST /api/v1/apps/{appId}/tables/{table}/rows:query

Rows matching a filter (eq, ne, lt, lte, gt, gte, in, nin, combined with and, or and not), with a sort, the fields to select, a limit (default 50, at most 1000) and a cursor. Values are always sent as values: no SQL from a client reaches the database.

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, table.

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}/tables/{table}/rows:query" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'