Skip to main content
POST
Create a table column

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
table_id
string<uuid>
required

Body

application/json

Request body for creating a table column.

​
definition
ManualColumnDefinition · object
required

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

​
display_name
string
required

Column display name, unique per table.

Required string length: 1 - 255
​
auto_run
boolean
default:true

Whether data changes (cell edits, new rows) recompute this column by themselves. Off, its cells go visibly stale and wait for an explicit run. Explicit runs and definition edits ignore it. IGNORED for export columns, which are always created with auto-run off — an export writes into a connected destination, so it may only be set to run by itself in a later, deliberate update.

​
column_type
enum<string> | null

The semantic column type. Required for manual columns; for formula columns it defaults to the plain type for the chain's derived output and must otherwise be able to store it.

Available options:
text,
paragraph,
url,
email,
image_url,
person,
select,
number,
decimal,
currency,
checkbox,
date,
multi_select,
list,
object
​
data_type
enum<string> | null

DEPRECATED — send column_type instead. Accepted for one release so a client from before semantic types keeps working; it is read as the plain column type for that storage type, and is ignored when column_type is set.

Available options:
string,
integer,
float,
boolean,
datetime,
date,
list,
dict
​
description
string | null

Optional note on what the column holds and where it comes from.

Required string length: 1 - 2000
​
expand_output_fields
boolean
default:true

For a multi-field enrichment, also create one child column per declared scalar output field, reading that field out of this column's payload. The payload column itself stays as the record of what came back; the children are what a person sorts, filters and exports on. Ignored for every other kind of column, and for a single-field output — there the parent column already IS the field. Set false to create the payload column alone.

​
output_column_names
Output Column Names · object

What to CALL each fanned-out child column, keyed by output field name. The author names them while setting the column up, so the preview they were shown is what the table gets. A field with no entry keeps the derived name, and a name already taken on the table falls back to the derived one rather than losing the column. Ignored when expand_output_fields is false, and CREATE only — an edit never renames a column that already exists.

​
position
integer | null

Insert position; appended when omitted.

Required range: x >= 0
​
refresh_interval_hours
integer
default:0

How often to re-run this column on its own, in hours. 0 is off. Capped at 8760 (a year), which is the point past which a schedule stops being one.

Required range: 0 <= x <= 8760
​
run_condition
ManualColumnDefinition · object

A formula whose result gates this column per row: the cell runs only where it evaluates truthy, and rows where it does not are left as they are rather than cleared. Null runs every row. A gate that fails to evaluate does NOT hold a row back — an unknown answer runs.

​
run_delay_seconds
integer
default:0

Seconds to wait after the run's conditions are met before this column runs. 0 runs immediately. Capped at 600 (10 minutes) — a longer wait is a schedule, not a delay.

Required range: 0 <= x <= 600
​
suppress_run
boolean
default:false

Create the column without computing it. Its cells are left empty and pending_recompute is set, so the column reads as waiting for a run rather than as one that ran and found nothing. For a formula over a large table, where the author wants the shape saved now and the cost paid when they say so.

​
type_options
SelectOptions · object

Per-type options; omit for the type's defaults.

Response

Successful Response

A table column with its definition and dependency metadata.

​
column_type
enum<string>
required

The semantic type; what the cell renders and validates as.

Available options:
text,
paragraph,
url,
email,
image_url,
person,
select,
number,
decimal,
currency,
checkbox,
date,
multi_select,
list,
object
​
created_at
string<date-time>
required
​
data_type
enum<string>
required

The storage type column_type resolves to, and so which typed value slot the cells live in. Derived, never chosen.

Available options:
string,
integer,
float,
boolean,
datetime,
date,
list,
dict
​
definition
ManualColumnDefinition · object
required

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

​
definition_version
integer
required

Bumped on definition changes; cosmetic edits leave it untouched.

​
depends_on_column_ids
string<uuid>[]
required

Direct chain inputs; empty for manual columns.

​
description
string | null
required

Author-written note on what the column holds; null when unset.

​
display_name
string
required
​
group_id
string<uuid> | null
required

The column group this column belongs to, or null. Groups are user-managed entities delivered on the column list's groups; this field is the membership edge, and the members' order is simply the columns' position order.

​
id
string<uuid>
required
​
is_group_output
boolean
required

Whether this member stays visible while its group is collapsed. Meaningful only while group_id is set. Every group keeps at least one output.

​
kind
enum<string>
required

Kind of a table column.

MANUAL cells are user-editable; FORMULA cells are a pure computed chain over other columns; ENRICHMENT cells are produced by an external action (an AI model, a research agent) run once per row. Formula and enrichment cells are both computed — read-only in the grid — but only enrichment work leaves the process and costs credits.

SOURCE cells hold one imported record verbatim, written only by the table's import source. Like MANUAL it is an externally-written leaf rather than a computed node — it joins no run plan and derives from no other column — but unlike MANUAL nobody may edit or retype it: the whole point is that a refresh can overwrite it wholesale, and every get_path column promoted off it reads paths that only survive while its shape does.

EXPORT cells hold the RECEIPT of pushing the row to a connected destination — status, the destination record id, when it happened — never the row's own data. The mirror image of SOURCE: where a source column is an externally-written leaf, an export column is an externally-READ leaf. It joins the run plan like a computed column (its mappings are dependencies, so a changed input re-pushes) but nothing may depend on it in turn, nobody may edit it (a hand-edited receipt would silently pin the row out of future pushes), and re-running it means "push again", not "re-answer".

SEQUENCE cells hold a contact's live status in an email sequence, written by the outreach send engine and nobody else: an externally-written leaf — no run plan, no dependencies, no user edits, no retyping — and, like EXPORT receipts, nothing may reference it in a formula: the status only exists to be looked at, never derived from. The column is created by the sequence that targets the table, not from the add-column catalog.

Available options:
manual,
formula,
enrichment,
source,
export,
sequence
​
position
integer
required
​
supported_filter_operators
enum<string>[]
required

Every filter operator this column admits, in display order. The server owns the list so a picker cannot offer a pairing the rows query will reject: value operators follow the storage slot, and a computed column additionally admits the execution-state family (has an error, has results, has not run, is stale, ...), which reads run metadata a manual column never writes.

A row filter predicate.

Which operators are legal depends on the column's data type; the service validates the pairing and rejects a mismatch, so an operator here is a vocabulary entry rather than a promise it applies everywhere.

Two families live here. The VALUE operators ask about what a cell holds and are keyed off the column's storage slot. The STATE operators ask about what the last run DID to the cell — errored, skipped, never ran, went stale — and are keyed off the column's kind instead: they read the compute metadata that only a computed column ever writes, and mean nothing on a hand-typed one.

Available options:
eq,
neq,
gt,
gte,
lt,
lte,
contains,
not_contains,
contains_any_of,
not_contains_any_of,
starts_with,
is_true,
is_false,
is_empty,
is_not_empty,
has_error,
has_no_error,
has_results,
has_no_results,
has_not_run,
is_stale,
is_not_stale,
run_condition_not_met,
run_stopped
​
table_id
string<uuid>
required
​
type_options
SelectOptions · object
required

Per-type options; null means the type's defaults.

​
updated_at
string<date-time>
required
​
auto_run
boolean
default:true

Whether data changes recompute this column by themselves; explicit runs ignore it.

​
pending_recompute
boolean
default:false

The definition has changed since these cells were last computed, so they are stale. Set by a save made with suppress_run, cleared when the column next finishes a run.

​
refresh_interval_hours
integer
default:0

Self re-run cadence in hours; 0 is off.

​
run_condition
ManualColumnDefinition · object

The per-row gate, verbatim; null runs every row.

​
run_delay_seconds
integer
default:0

Pre-run wait in seconds; 0 runs immediately.