table-columns
mcp-searchable-tool

Create a table column

Create a column. A formula column requests a column-added recompute run over all rows. The run appears on the next active-runs poll; the response never carries a run ID. Manual columns request nothing.

post/tables/{table_id}/columns/

Request

  • Base URL: https://api.getoneprofile.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.getoneprofile.ai/tables/{table_id}/columns/
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

table_idstring uuid required

Request body

auto_runboolean

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'text' | 'paragraph' | 'url' | 'email' | 'image_url' | 'person' | 'select' | 'number' | 'decimal' | 'currency' | 'checkbox' | 'date' | 'multi_select' | 'list' | 'object'

The type a user picks for a table column.

Ordered as the picker shows them, which is also the order the groups below run in: text-ish, then numeric, then choice, then structured.

data_type'string' | 'integer' | 'float' | 'boolean' | 'datetime' | 'date' | 'list' | 'dict'

Type of a property. Used while creating/updating/deleting properties.

descriptionstring nullable

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

display_namestring required

Column display name, unique per table.

expand_output_fieldsboolean

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_namesobject

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.

positioninteger nullable

Insert position; appended when omitted.

refresh_interval_hoursinteger

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.

run_condition_view_idstring uuid nullable

A saved view whose filter this column follows as its run condition. When set, the engine evaluates membership in the view's current filter at run time, so the gate updates automatically when the view's filter changes. Editing the run condition directly detaches from the view. Mutually exclusive with an explicit run_condition. Set one or the other, not both.

run_delay_secondsinteger

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.

suppress_runboolean

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.

Response

Successful Response

ai_madeboolean

Whether the AI assistant created this column through a workspace action. A fact about who made it, not a state: it stays true after a person edits the column.

auto_runboolean

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

column_type'text' | 'paragraph' | 'url' | 'email' | 'image_url' | 'person' | 'select' | 'number' | 'decimal' | 'currency' | 'checkbox' | 'date' | 'multi_select' | 'list' | 'object' required

The type a user picks for a table column.

Ordered as the picker shows them, which is also the order the groups below run in: text-ish, then numeric, then choice, then structured.

created_atstring date-time required
data_type'string' | 'integer' | 'float' | 'boolean' | 'datetime' | 'date' | 'list' | 'dict' required

Type of a property. Used while creating/updating/deleting properties.

definition_versioninteger required

Bumped on definition changes; cosmetic edits leave it untouched.

depends_on_column_idsstring[] required

Direct chain inputs; empty for manual columns.

descriptionstring nullable required

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

display_namestring required
group_idstring uuid nullable 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.

idstring uuid required
is_group_outputboolean 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'manual' | 'formula' | 'enrichment' | 'source' | 'export' | 'sequence' 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, or the messages it sent them, written by the outreach send engine and nobody else: an externally-written leaf with no run plan, no dependencies, no user edits, no retyping. A status column, like EXPORT receipts, may not be referenced in a formula: the status only exists to be looked at, never derived from. A messages column may, the way a SOURCE record may: the engine requests a run of its dependents whenever it rewrites a cell. The columns are created by the sequence that targets the table, not from the add-column catalog.

pending_recomputeboolean

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.

positioninteger required
refresh_interval_hoursinteger

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

run_condition_group_idstring uuid nullable

When set, run_condition is inherited from this column group and is rewritten whenever the group's changes. Set a run_condition on the column to override it, or clear the column's to inherit again.

run_condition_view_idstring uuid nullable

When set, the column follows this saved view's filter as its run condition. The engine evaluates view membership at run time rather than reading run_condition. Editing the run condition directly detaches from the view.

run_delay_secondsinteger

Pre-run wait in seconds; 0 runs immediately.

supported_filter_operatorsTableFilterOperator[] 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.

table_idstring uuid required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.