Tables
Space MCP tools in the Tables scope (tables). Reach these with a wks_live_ key over space-mcp or space-api.
Tools in the tables scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants tables.
add_row_comment
Scope: tables:write
Add a comment to a table row's discussion thread (posted as the agent).
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
row_id | string | yes | |
body | string | yes |
create_table
Scope: tables:write
Create a new table. Pass name (plural label, e.g. 'Invoices') and optionally columns to define the schema in one call — same shape as create_table_column args ({key,label,type,...}). Slug is auto-generated and de-duplicated. The first text column becomes the row title unless title_field_key is set.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Plural label, e.g. 'Invoices'. |
singular_label | string | Defaults to name. | |
slug | string | ||
icon | string | Lucide icon name or emoji. | |
color | string | ||
description | string | ||
title_field_key | string | ||
columns | object[] | Initial columns: [{key,label,type,options?,reference_target?,field_config?,required?,default_value?,icon?}]. |
create_table_column
Scope: tables:write
Add a column to a table. key must be snake_case (^[a-z][a-z0-9_]*$). All field types are supported (text, number, select, rating, attachment, formula, lookup, rollup, ...). For select/multi_select pass options:[{value,label,color?}]; for reference pass reference_target:{kind:'contact'|'task'|'calendar_event'} or {kind:'table',table_id}; for formula/lookup/rollup/button/currency-style config pass field_config (formula: {expression}, lookup: {source_column_key,target_column_key}, rollup: {source_column_key,target_column_key,aggregator}).
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
key | string | yes | snake_case column key, e.g. 'vin'. |
label | string | yes | |
type | string | yes | |
description | string | ||
options | array | select/multi_select choices: [{value,label,color?}]. | |
reference_target | object | reference target: {kind:'contact'} or {kind:'table',table_id}. | |
field_config | object | Type-specific config (formula expression, lookup/rollup source, button action, number format, ...). | |
required | boolean | ||
default_value | — | ||
display_order | number | ||
icon | string | Optional emoji shown in the column header. |
create_table_row
Scope: tables:write
Create a row in a table. Pass column values in data.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
data | object | yes | Map of column key → value. |
create_table_rows
Scope: tables:write
Bulk-insert up to 100 rows into a table in one call. rows is an array of data objects (column key → value).
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
rows | object[] | yes |
create_table_share_link
Scope: tables:write
Create a PUBLIC view-only share link for a table. Anyone with the URL sees a read-only rendering of the given view (its filters and hidden fields are enforced server-side). Omit view_id to share the table's default view. Returns the shareable URL.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
view_id | string | Share this specific view. Defaults to the table's default view. | |
name | string | Label shown in the share-links list. |
create_table_snapshot
Scope: tables:write
Capture a named save point of a table's full state (schema + rows + views). Do this before risky bulk edits so the user can restore.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
label | string |
create_table_view
Scope: tables:write
Create a view for a table. type: grid | kanban | gallery | calendar | dashboard. config holds the per-view filters/sort/group/layout (kanban needs config.group_by, calendar needs config.date_field, dashboard needs config.widgets).
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
name | string | yes | |
type | string | Defaults to grid. | |
config | object | Per-view filters/sort/grouping/layout settings. | |
display_order | number | ||
is_default | boolean | Make this the table's default view (clears any prior default). |
delete_table
Scope: tables:write
Delete a table. Default is ARCHIVE (reversible via update_table {archived:false}). Pass hard_delete:true to permanently delete the table and all its rows/columns/views — a safety snapshot is captured first.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
hard_delete | boolean |
delete_table_column
Scope: tables:write
Delete a table column (drops its data from all rows).
| Parameter | Type | Required | Description |
|---|---|---|---|
column_id | string | yes |
delete_table_row
Scope: tables:write
Delete one row from a table. Irreversible (but the table History keeps a before-state).
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
row_id | string | yes |
delete_table_rows
Scope: tables:write
Bulk-delete up to 100 rows by id in one call.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
row_ids | string[] | yes |
delete_table_view
Scope: tables:write
Delete a table view.
| Parameter | Type | Required | Description |
|---|---|---|---|
view_id | string | yes |
get_table
Scope: tables:read
Get one table's full definition: metadata, columns (schema), views, and row count. Call this before reading/writing rows so you know the column keys and types.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes |
get_table_view
Scope: tables:read
Get one table view including its full config (filters, sort, grouping, layout settings).
| Parameter | Type | Required | Description |
|---|---|---|---|
view_id | string | yes |
list_row_comments
Scope: tables:read
List the comment thread on a table row (oldest first).
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
row_id | string | yes | |
limit | number |
list_table_columns
Scope: tables:read
List a table's columns (its schema). Needed before creating rows so you know the column keys/types.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes |
list_table_rows
Scope: tables:read
List/query rows of a table with optional filters (AND-combined, ops: eq|neq|contains|gt|lt|is_empty|is_not_empty on column keys), multi-column sort, and search (substring match on the title column, or search_column). Returns rows plus total/has_more for pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
limit | number | ||
offset | number | ||
filters | object[] | [{column_key, op, value?}] — AND-combined. | |
sort | object[] | [{column_key, direction:'asc'|'desc'}] — also accepts created_at/updated_at. | |
search | string | ||
search_column | string |
list_table_share_links
Scope: tables:read
List a table's public view-only share links (URL, view, revoked state).
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes |
list_table_snapshots
Scope: tables:read
List a table's Time Machine snapshots (save points + auto-captured session snapshots), newest first.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
limit | number |
list_table_views
Scope: tables:read
List the saved views (grid/kanban/gallery/calendar) of a table. Per-view filters/sort/group live in each view's config.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes |
list_tables
Scope: tables:read
List user-defined tables (record types) in the space.
restore_table_snapshot
Scope: tables:write
Restore a table to a snapshot's state (schema + rows + views). Atomic; a pre-restore snapshot is captured automatically so this is reversible.
| Parameter | Type | Required | Description |
|---|---|---|---|
snapshot_id | string | yes |
revoke_table_share_link
Scope: tables:write
Revoke a public share link — the URL stops working immediately.
| Parameter | Type | Required | Description |
|---|---|---|---|
link_id | string | yes |
update_table
Scope: tables:write
Edit table metadata: labels, slug, icon, color, description, title_field_key, display_order. Pass archived:true to archive (hide) the table, archived:false to restore it.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
name | string | Alias for plural_label. | |
singular_label | string | ||
plural_label | string | ||
slug | string | ||
icon | string | ||
color | string | ||
description | string | ||
title_field_key | string | ||
display_order | number | ||
archived | boolean |
update_table_column
Scope: tables:write
Edit a table column (label, type, options, required, etc.).
| Parameter | Type | Required | Description |
|---|---|---|---|
column_id | string | yes | |
key | string | ||
label | string | ||
type | string | ||
description | string | ||
options | array | ||
reference_target | object | ||
field_config | object | ||
required | boolean | ||
default_value | — | ||
display_order | number | ||
icon | string |
update_table_row
Scope: tables:write
Patch a row's data (merged into existing JSON, not replaced).
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
row_id | string | yes | |
data | object | yes |
update_table_rows
Scope: tables:write
Bulk-patch up to 100 rows in one call. updates = [{row_id, data}] — each data object is merged into that row. Per-row failures are reported, not fatal.
| Parameter | Type | Required | Description |
|---|---|---|---|
table_id | string | yes | |
updates | object[] | yes |
update_table_view
Scope: tables:write
Edit a table view (name, type, config, order, or default flag).
| Parameter | Type | Required | Description |
|---|---|---|---|
view_id | string | yes | |
name | string | ||
type | string | ||
config | object | ||
display_order | number | ||
is_default | boolean |