Schema

A workspace's shape is not fixed at deploy time — somebody can add a table or rename a column while your application is running. These routes are how a client discovers that shape instead of hard-coding it.

Auth: API key (sk_live_ or pk_live_), or an end-user JWT.

Get the schema

GET /{workspaceId}/schema

{
  "tables": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Customers",
      "columns": [
        { "id": "…", "name": "Name",   "type": "ShortText", "isKey": true,  "isNative": false, "isRequired": true,  "pointsTo": null, "entityId": null },
        { "id": "…", "name": "Owner",  "type": "Table",     "isKey": false, "isNative": false, "isRequired": false, "pointsTo": "…",  "entityId": null },
        { "id": "…", "name": "Status", "type": "Status",    "isKey": false, "isNative": false, "isRequired": false, "pointsTo": null, "entityId": "…" }
      ]
    }
  ]
}

The response is filtered twice. It contains only the tables in the credential's scope, and only those whose scope has schema introspection switched on. A table you can query is not necessarily a table you can introspect — that is a separate setting, and a credential shipped to a browser is a good reason to leave it off.

Get the status groups

A Status column's entityId names its group. These routes turn that GUID into the options themselves — including the ones nobody has used yet, which is the difference between a board that keeps its empty column and one that loses it the moment the last card moves away.

GET /{workspaceId}/schema/status-groups

{
  "statusGroups": [
    {
      "id": "…",
      "name": "Deal stage",
      "statuses": [
        { "id": "…", "name": "New",  "color": "3b82f6", "position": 0 },
        { "id": "…", "name": "Won",  "color": "16a34a", "position": 1 },
        { "id": "…", "name": "Lost", "color": "dc2626", "position": 2 }
      ]
    }
  ]
}

GET /{workspaceId}/schema/status-groups/{statusGroupId}

Returns one group, in the same shape, addressed by the entityId the schema response already gave you.

A Status value read back from /query is the option's GUID, not its name. Compare against id, and use name only for display.

Errors

The flat shape — { "error": "…" } — with the meaning in the status.