View management

A saved view is the persisted configuration of a records table: which columns show, how rows sort, which filters apply, the layout type, and any grouping. It is one row per (workspace, root) pair, addressed under the owning workspace.

Where POST /v1/records/query is transient (it returns rows for a one-off filter/sort and writes nothing), a view is persisted — it is the base configuration a grid opens with, and the thing the UI's column / sort / layout / group controls write to.

What a view holds

Endpoints

All view operations are scoped under the workspace that owns them.

See the Records views & statistics group in the sidebar for the full request/response schema of each.

Trigger any view type

Every view possibility is reachable from the create / update body — set layout_type (one of the seven) plus group_by where the layout needs it. For example, a kanban board grouped by status:

POST /v1/workspaces/{workspace_id}/views
{
  "data": {
    "type": "workspace-view",
    "attributes": {
      "name": "Pipeline by status",
      "root": "companies",
      "layout_type": "kanban",
      "group_by": ["status"],
      "columns": [{ "field": "name" }, { "field": "status" }],
      "sort": [{ "field": "created_at", "direction": "desc" }]
    }
  }
}

Swap layout_type for calendar with a date group_by (e.g. ["due_date"]), or list / graph / table with no group_by, to trigger the other layouts. The same attributes are accepted by PATCH to reconfigure an existing view.

Default grouping (auto_group)

A kanban or calendar view needs a group_by to render grouped; without one it shows a "select a field" state. You don't have to supply it — when group_by is omitted on a kanban/calendar create (or a layout switch to one), the server resolves a logical default and persists it onto the view.

auto_group (boolean, default true) controls this. It is a request-only control flag and is not stored on the view. Pass auto_group: false to leave group_by unset (the view then renders the "select a field" state). It has no effect when you pass an explicit group_by (including explicit null), or for layouts that don't group (table / list / graph). On PATCH, auto-resolution applies only when switching a non-default view to kanban/calendar that doesn't already group — it never overwrites an existing group_by, and it never applies to a default view (which rejects group_by changes; see below).

Resolution is deterministic first, model-assisted only when needed:

Auto-default only chooses from the enum (kanban) or date (calendar) candidates — it never auto-groups by free text. A root with no eligible field leaves group_by as null (the "select a field" state). The full set of eligible fields stays available for explicit selection: pass any eligible field as group_by to override the default.

The default view is a shared baseline

Exactly one view per (workspace, root) carries is_default: true. The default is a shared baseline across every user of the workspace, so its personal-state fields are protected: a PATCH to a default view that changes filters, sort, or group_by is rejected with 409 DEFAULT_VIEW_READONLY (these are exactly the fields the chat updateDataView tool would otherwise leak into the shared baseline).

Its layout fields stay mutable on the default — PATCH may still change layout_type, layout_config, display_fields, columns, name, and the is_default toggle itself.

To make the fork the active view, promote it with PATCH … { "data": { "attributes": { "is_default": true } } }, which atomically demotes the previous default (the single-default invariant is enforced server-side). There is no /views/{id}/set-default action endpoint — is_default flows through the resource's PATCH like any other field (per the API Shape Standard: state transitions belong on the resource's existing PATCH, not a custom verb).

How a view relates to a query

A view supplies the base columns, sort, and filters a grid opens with. POST /v1/records/query then runs against that root — you can pass a whereClause / orderBy to overlay a transient filter or sort on top of the view's base without persisting anything. To make a filter or sort stick, write it to the view via PATCH.