Basalt docs
GitHub

Databases and fields

The workspace field registry, databases and their bound fields, saved views, and row memberships.

29 operations. Every path is relative to the instance origin; every response body is JSON unless stated. See API for authentication, errors and pagination.

GET /api/v1/workspaces/{workspaceId}/fields

List a workspace's registry fields.

listFields · token scope: content:read

Path parameters

  • workspaceId · string (uuid) — required

Query parameters

  • cursor · string — length 1–∞
  • limit · integer — 1–100

Response 200 — application/json

  • items · object[] — required
    • id · string (uuid) — required
    • workspaceId · string (uuid) — required
    • key · string — required, length 1–100
    • name · string — required
    • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
    • config · object — required
    • createdAt · string (date-time) — required
  • nextCursor · string | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/fields

Create a workspace field (typed registry column).

createField · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required

Request body — application/json, required

  • key · string — length 1–100
  • name · string — required, length 1–200
  • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
  • config · object

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • key · string — required, length 1–100
  • name · string — required
  • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
  • config · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

GET /api/v1/workspaces/{workspaceId}/fields/{fieldId}

Get a single field.

getField · token scope: content:read

Path parameters

  • workspaceId · string (uuid) — required
  • fieldId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • key · string — required, length 1–100
  • name · string — required
  • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
  • config · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

PATCH /api/v1/workspaces/{workspaceId}/fields/{fieldId}

Update a field name and/or config (type changes go through retype).

updateField · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • fieldId · string (uuid) — required

Request body — application/json, required

  • name · string — length 1–200
  • config · object

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • key · string — required, length 1–100
  • name · string — required
  • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
  • config · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

DELETE /api/v1/workspaces/{workspaceId}/fields/{fieldId}

Delete a field from the registry (unbinds it everywhere and strips its page values). Returns the deleted field.

deleteField · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • fieldId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • key · string — required, length 1–100
  • name · string — required
  • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
  • config · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/fields/{fieldId}/retype

Change a field type, converting stored page values (bounded/chunked). Illegal targets (to/from relation or formula) are rejected (400).

retypeField · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • fieldId · string (uuid) — required

Request body — application/json, required

  • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
  • config · object

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • key · string — required, length 1–100
  • name · string — required
  • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
  • config · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/fields/{fieldId}/merge

Merge this field into a target field: move page values, rebind databases, then delete this (source) field. Returns the target field.

mergeField · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • fieldId · string (uuid) — required

Request body — application/json, required

  • targetFieldId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • key · string — required, length 1–100
  • name · string — required
  • type · "text" | "number" | "select" | "multi_select" | "date" | "person" | "checkbox" | "url" | "relation" | "formula" — required
  • config · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

GET /api/v1/workspaces/{workspaceId}/fields/{fieldId}/usage

Report how widely a field is used (databases bound, pages carrying it).

getFieldUsage · token scope: content:read

Path parameters

  • workspaceId · string (uuid) — required
  • fieldId · string (uuid) — required

Response 200 — application/json

  • fieldId · string (uuid) — required
  • databaseCount · integer — required, 0–9007199254740991
  • pageCount · integer — required, 0–9007199254740991

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

GET /api/v1/workspaces/{workspaceId}/databases

List databases in a workspace (optionally filtered to a collection).

listDatabases · token scope: content:read

Path parameters

  • workspaceId · string (uuid) — required

Query parameters

  • cursor · string — length 1–∞
  • limit · integer — 1–100
  • collectionId · string (uuid)

Response 200 — application/json

  • items · object[] — required
    • id · string (uuid) — required
    • workspaceId · string (uuid) — required
    • collectionId · string (uuid) — required
    • parentPageId · string (uuid) | null — required
    • position · string — required
    • name · string — required
    • icon · string | null — required
    • createdBy · string (uuid) | null — required
    • updatedBy · string (uuid) | null — required
    • createdAt · string (date-time) — required
    • updatedAt · string (date-time) — required
    • deletedAt · string (date-time) | null — required
  • nextCursor · string | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/databases

Create a database in a collection, optionally under a parent page.

createDatabase · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required

Request body — application/json, required

  • collectionId · string (uuid) — required
  • parentPageId · string (uuid)
  • name · string — required, length 1–200
  • icon · string — length 0–2048

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • name · string — required
  • icon · string | null — required
  • createdBy · string (uuid) | null — required
  • updatedBy · string (uuid) | null — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

GET /api/v1/workspaces/{workspaceId}/databases/{databaseId}

Get a single database.

getDatabase · token scope: content:read

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • name · string — required
  • icon · string | null — required
  • createdBy · string (uuid) | null — required
  • updatedBy · string (uuid) | null — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

PATCH /api/v1/workspaces/{workspaceId}/databases/{databaseId}

Update a database name and/or icon.

updateDatabase · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Request body — application/json, required

  • name · string — length 1–200
  • icon · string | null

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • name · string — required
  • icon · string | null — required
  • createdBy · string (uuid) | null — required
  • updatedBy · string (uuid) | null — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/databases/{databaseId}/trash

Soft-delete a database (move to trash). Deep: the pages HOMED in it are trashed with it. Row memberships are kept, not dropped, so restoring is lossless; they are removed only by a permanent delete.

trashDatabase · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • name · string — required
  • icon · string | null — required
  • createdBy · string (uuid) | null — required
  • updatedBy · string (uuid) | null — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/databases/{databaseId}/restore

Restore a database from the trash, together with exactly the pages that were trashed in the same batch (pages already in the trash beforehand stay there). Row memberships survived the trash, so the restored database shows its rows again. Restoring under a still-trashed parent re-parents the database to the collection root, mirroring restorePage.

restoreDatabase · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • name · string — required
  • icon · string | null — required
  • createdBy · string (uuid) | null — required
  • updatedBy · string (uuid) | null — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

DELETE /api/v1/workspaces/{workspaceId}/databases/{databaseId}/permanent

Permanently delete a TRASHED database and everything below it — irreversible. Refuses with 409 when the database is not in the trash. Same cascade as deletePagePermanently, plus the database-specific rows: every membership (db_row) of the database, its column bindings (database_field), and every view targeting it. Returns what was deleted.

deleteDatabasePermanently · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Response 200 — application/json

  • roots · integer — required, 0–9007199254740991
  • pages · integer — required, 0–9007199254740991
  • databases · integer — required, 0–9007199254740991
  • views · integer — required, 0–9007199254740991
  • blocks · integer — required, 0–9007199254740991

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

GET /api/v1/workspaces/{workspaceId}/databases/{databaseId}/fields

List a database's field bindings, in column order.

listDatabaseFields · token scope: content:read

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Query parameters

  • cursor · string — length 1–∞
  • limit · integer — 1–100

Response 200 — application/json

  • items · object[] — required
    • workspaceId · string (uuid) — required
    • databaseId · string (uuid) — required
    • fieldId · string (uuid) — required
    • position · string — required
    • required · boolean — required
    • defaultValue · object | null — required
  • nextCursor · string | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/databases/{databaseId}/fields

Bind a registry field into a database as a column.

bindField · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Request body — application/json, required

  • fieldId · string (uuid) — required
  • required · boolean
  • defaultValue · object | null
  • beforeId · string (uuid)
  • afterId · string (uuid)

Response 200 — application/json

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • fieldId · string (uuid) — required
  • position · string — required
  • required · boolean — required
  • defaultValue · object | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

PATCH /api/v1/workspaces/{workspaceId}/databases/{databaseId}/fields/{fieldId}

Update a binding: required, default value, and/or column position.

updateBinding · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • fieldId · string (uuid) — required

Request body — application/json, required

  • required · boolean
  • defaultValue · object | null
  • beforeId · string (uuid)
  • afterId · string (uuid)

Response 200 — application/json

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • fieldId · string (uuid) — required
  • position · string — required
  • required · boolean — required
  • defaultValue · object | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

DELETE /api/v1/workspaces/{workspaceId}/databases/{databaseId}/fields/{fieldId}

Remove a field binding from a database (values on pages are kept).

unbindField · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • fieldId · string (uuid) — required

Response 200 — application/json

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • fieldId · string (uuid) — required
  • position · string — required
  • required · boolean — required
  • defaultValue · object | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

GET /api/v1/workspaces/{workspaceId}/views

List views in a workspace (optionally filtered to one database).

listViews · token scope: content:read

Path parameters

  • workspaceId · string (uuid) — required

Query parameters

  • cursor · string — length 1–∞
  • limit · integer — 1–100
  • targetDatabaseId · string (uuid)

Response 200 — application/json

  • items · object[] — required
    • id · string (uuid) — required
    • workspaceId · string (uuid) — required
    • collectionId · string (uuid) — required
    • parentPageId · string (uuid) | null — required
    • position · string — required
    • targetDatabaseId · string (uuid) — required
    • layout · "table" | "list" — required
    • filters · object[] — required
      • fieldId · string (uuid) — required
      • op · "eq" | "ne" | "contains" | "is_empty" | "is_not_empty" — required
      • value · any
    • sorts · object[] — required
      • fieldId · string (uuid) — required
      • direction · "asc" | "desc" — required
    • createdAt · string (date-time) — required
    • updatedAt · string (date-time) — required
    • deletedAt · string (date-time) | null — required
  • nextCursor · string | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/views

Create a saved view (table or list) over a database.

createView · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required

Request body — application/json, required

  • collectionId · string (uuid) — required
  • parentPageId · string (uuid)
  • targetDatabaseId · string (uuid) — required
  • layout · "table" | "list" — required
  • filters · object[]
    • fieldId · string (uuid) — required
    • op · "eq" | "ne" | "contains" | "is_empty" | "is_not_empty" — required
    • value · any
  • sorts · object[]
    • fieldId · string (uuid) — required
    • direction · "asc" | "desc" — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • targetDatabaseId · string (uuid) — required
  • layout · "table" | "list" — required
  • filters · object[] — required
    • fieldId · string (uuid) — required
    • op · "eq" | "ne" | "contains" | "is_empty" | "is_not_empty" — required
    • value · any
  • sorts · object[] — required
    • fieldId · string (uuid) — required
    • direction · "asc" | "desc" — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

GET /api/v1/workspaces/{workspaceId}/views/{viewId}

Get a single view.

getView · token scope: content:read

Path parameters

  • workspaceId · string (uuid) — required
  • viewId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • targetDatabaseId · string (uuid) — required
  • layout · "table" | "list" — required
  • filters · object[] — required
    • fieldId · string (uuid) — required
    • op · "eq" | "ne" | "contains" | "is_empty" | "is_not_empty" — required
    • value · any
  • sorts · object[] — required
    • fieldId · string (uuid) — required
    • direction · "asc" | "desc" — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

PATCH /api/v1/workspaces/{workspaceId}/views/{viewId}

Update a view layout, filters, and/or sorts.

updateView · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • viewId · string (uuid) — required

Request body — application/json, required

  • layout · "table" | "list"
  • filters · object[]
    • fieldId · string (uuid) — required
    • op · "eq" | "ne" | "contains" | "is_empty" | "is_not_empty" — required
    • value · any
  • sorts · object[]
    • fieldId · string (uuid) — required
    • direction · "asc" | "desc" — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • targetDatabaseId · string (uuid) — required
  • layout · "table" | "list" — required
  • filters · object[] — required
    • fieldId · string (uuid) — required
    • op · "eq" | "ne" | "contains" | "is_empty" | "is_not_empty" — required
    • value · any
  • sorts · object[] — required
    • fieldId · string (uuid) — required
    • direction · "asc" | "desc" — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/views/{viewId}/trash

Soft-delete a view (move to trash).

trashView · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • viewId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • parentPageId · string (uuid) | null — required
  • position · string — required
  • targetDatabaseId · string (uuid) — required
  • layout · "table" | "list" — required
  • filters · object[] — required
    • fieldId · string (uuid) — required
    • op · "eq" | "ne" | "contains" | "is_empty" | "is_not_empty" — required
    • value · any
  • sorts · object[] — required
    • fieldId · string (uuid) — required
    • direction · "asc" | "desc" — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/databases/{databaseId}/rows/query

The main read path: run a view (filters/sorts) over a database and page through the rows with a composite keyset cursor. Cells are projected at read time from page props + relation_link + formula evaluation.

queryDatabaseRows · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Request body — application/json, required

  • filters · object[]
    • fieldId · string (uuid) — required
    • op · "eq" | "ne" | "contains" | "is_empty" | "is_not_empty" — required
    • value · any
  • sorts · object[]
    • fieldId · string (uuid) — required
    • direction · "asc" | "desc" — required
  • cursor · string — length 1–∞
  • limit · integer — 1–100

Response 200 — application/json

  • items · object[] — required
    • pageId · string (uuid) — required
    • workspaceId · string (uuid) — required
    • databaseId · string (uuid) — required
    • position · string — required
    • title · string — required
    • icon · string | null — required
    • cells · object — required
    • createdAt · string (date-time) — required
  • nextCursor · string | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/databases/{databaseId}/rows

Create a new page as a row of this database, seeding its props from the supplied cells and the bindings' default values (D2 materialize-at-create).

createRow · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Request body — application/json, required

  • title · string — length 0–1000
  • icon · string — length 0–2048
  • cells · object
  • beforeId · string (uuid)
  • afterId · string (uuid)

Response 200 — application/json

  • pageId · string (uuid) — required
  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • position · string — required
  • title · string — required
  • icon · string | null — required
  • cells · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/databases/{databaseId}/rows/add

Add an existing page to this database as a row (membership).

addExistingPage · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required

Request body — application/json, required

  • pageId · string (uuid) — required
  • cells · object
  • beforeId · string (uuid)
  • afterId · string (uuid)

Response 200 — application/json

  • pageId · string (uuid) — required
  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • position · string — required
  • title · string — required
  • icon · string | null — required
  • cells · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

POST /api/v1/workspaces/{workspaceId}/databases/{databaseId}/rows/{pageId}/move

Reorder a row within its database membership.

moveRow · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • pageId · string (uuid) — required

Request body — application/json, required

  • beforeId · string (uuid)
  • afterId · string (uuid)

Response 200 — application/json

  • pageId · string (uuid) — required
  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • position · string — required
  • title · string — required
  • icon · string | null — required
  • cells · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required

DELETE /api/v1/workspaces/{workspaceId}/databases/{databaseId}/rows/{pageId}

Remove a page from this database (drops the membership; the page is kept). 409 with a needs-new-home code when this is the page's home database — reparent it via movePage first.

removeRow · token scope: content:write

Path parameters

  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • pageId · string (uuid) — required

Response 200 — application/json

  • pageId · string (uuid) — required
  • workspaceId · string (uuid) — required
  • databaseId · string (uuid) — required
  • position · string — required
  • title · string — required
  • icon · string | null — required
  • cells · object — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required