Tecto docs
tectoapp.io

Databases and fields

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

34 operations. Every path is relative to the instance origin; every response body is JSON unless stated. The endpoint descriptions below come straight from the server’s own route table. 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
    • builtinKey · "tags" | "summary" | "page_type" | "status" | "related" | null — 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
    • reason · string — length 1–64

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
  • scope · object
    • type · "workspace" | "collection" | "database" — required
    • id · string (uuid)

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
  • builtinKey · "tags" | "summary" | "page_type" | "status" | "related" | null — 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
    • reason · string — length 1–64

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
  • builtinKey · "tags" | "summary" | "page_type" | "status" | "related" | null — 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
    • reason · string — length 1–64

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
  • builtinKey · "tags" | "summary" | "page_type" | "status" | "related" | null — 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
    • reason · string — length 1–64

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
  • builtinKey · "tags" | "summary" | "page_type" | "status" | "related" | null — 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
    • reason · string — length 1–64

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
  • builtinKey · "tags" | "summary" | "page_type" | "status" | "related" | null — required
  • createdAt · string (date-time) — required
  • convertedValues · integer — required, 0–9007199254740991
  • droppedValues · 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
    • reason · string — length 1–64

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
  • builtinKey · "tags" | "summary" | "page_type" | "status" | "related" | null — 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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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

Add one option to an open vocabulary (tags); rejected on a closed select.

addFieldOption · token scope: content:write

Path parameters

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

Request body — application/json, required

  • label · string — required, length 1–200
  • color · string

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
  • builtinKey · "tags" | "summary" | "page_type" | "status" | "related" | null — 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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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 — and, mirroring it again, refuses with 400 when the asking product never shows a database there (ADR-0030): restore the container it was in first, and the database comes home to it.

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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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
    • scopeType · "workspace" | "collection" | "database" — required
    • scopeId · 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
    • reason · string — length 1–64

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
  • scopeType · "workspace" | "collection" | "database" — required
  • scopeId · 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
    • reason · string — length 1–64

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
  • scopeType · "workspace" | "collection" | "database" — required
  • scopeId · 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
    • reason · string — length 1–64

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
  • scopeType · "workspace" | "collection" | "database" — required
  • scopeId · 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
    • reason · string — length 1–64

GET /api/v1/workspaces/{workspaceId}/field-bindings

List the fields offered on every page of the workspace.

listWorkspaceBindings · 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
    • workspaceId · string (uuid) — required
    • scopeType · "workspace" | "collection" | "database" — required
    • scopeId · 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
    • reason · string — length 1–64

POST /api/v1/workspaces/{workspaceId}/field-bindings

Offer a registry field on every page of the workspace.

bindWorkspaceField · token scope: content:write

Path parameters

  • workspaceId · 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
  • scopeType · "workspace" | "collection" | "database" — required
  • scopeId · 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
    • reason · string — length 1–64

PATCH /api/v1/workspaces/{workspaceId}/field-bindings/{fieldId}

Reorder a workspace binding among the workspace's fields.

updateWorkspaceBinding · token scope: content:write

Path parameters

  • workspaceId · 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
  • scopeType · "workspace" | "collection" | "database" — required
  • scopeId · 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
    • reason · string — length 1–64

DELETE /api/v1/workspaces/{workspaceId}/field-bindings/{fieldId}

Stop offering a field workspace-wide (values already on pages are kept).

unbindWorkspaceField · token scope: content:write

Path parameters

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

Response 200 — application/json

  • workspaceId · string (uuid) — required
  • scopeType · "workspace" | "collection" | "database" — required
  • scopeId · 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
    • reason · string — length 1–64

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
    • match · "all" | "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
    • reason · string — length 1–64

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
  • match · "all" | "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
  • match · "all" | "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
    • reason · string — length 1–64

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
  • match · "all" | "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
    • reason · string — length 1–64

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
  • match · "all" | "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
  • match · "all" | "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
    • reason · string — length 1–64

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
  • match · "all" | "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
    • reason · string — length 1–64

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
  • match · "all" | "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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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
    • reason · string — length 1–64

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, or name a newHomeBoardId on removeBoardCard when the database backs a board.

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
    • reason · string — length 1–64