Skip to main content
PATCH
Update a column group

Authorizations

X-API-Key
string
header
required

Path Parameters

table_id
string<uuid>
required
group_id
string<uuid>
required

Body

application/json

Request body for updating a group (tri-state PATCH; members are full-state).

collapsed

Whether the grid folds the group down to its output members.

members

The FULL member list in its new order. Columns newly listed join the group and move into its block; current members left out are removed and land immediately after it. A group always has at least one member and at least one output: an empty list is refused (ungroup to dissolve the group), and so is a list with no output flagged.

name

New name. Set to null to restore the default label.

Required string length: 1 - 255
run_condition

Definition of a manual column: typed, user-editable cells.

ui_color

Semantic tint token, shared by a column and by a column GROUP.

Stored as a token rather than a hex value because the grid renders in both a light and a dark theme, and a single stored colour is only legible in one of them. The client maps each token to a per-mode value.

Deliberately excludes teal: the brand primary is used for range selection and the anchor outline, so a teal column would read as permanently selected.

Lives HERE rather than in table_column_prefs, where it started, because two domains now need it and the layering only allows one direction. A column's tint is stored in table_column_prefs (org-shared appearance, keyed by column) while a group's is a field on the group row itself in table_column, and table_column_prefs sits ABOVE table_column in the domain layers, so the token had to move DOWN to be reachable from both. table_column_prefs.types re-exports it, which is why that move touched no existing import.

One enum for both on purpose: a colour token is a shared vocabulary (a team agreeing that amber means "needs review" is agreeing about it across columns and groups alike) and the organisation's renaming of the palette (table_column_color_labels) is keyed by this token, so a second enum would give groups colours the rename dialog could not name.

Available options:
gray,
red,
orange,
amber,
green,
blue,
purple,
pink

Response

Successful Response

A user-managed column group, membership resolved in position order.

collapsed
boolean
required

Whether the grid folds the group down to its output members. Purely presentational: folded members' cells are still fetched, so expanding costs nothing.

created_at
string<date-time>
required
id
string<uuid>
required
members
TableColumnGroupMemberSchema · object[]
required

The member columns in position order, with their output flags.

name
string | null
required

The group's name; null renders the client default label.

table_id
string<uuid>
required
ui_color
enum<string> | null
required

Palette token for the group's band, or null for a neutral band. A token rather than a hex: the grid renders light and dark, and one stored colour is only legible in one of them.

Available options:
gray,
red,
orange,
amber,
green,
blue,
purple,
pink
updated_at
string<date-time>
required
run_condition
ManualColumnDefinition · object

The group's per-row gate, verbatim; null gates nothing. Every member without a gate of its own carries a copy in its run_condition (marked by run_condition_group_id), so the columns themselves say what runs.