Skip to main content
For agents and developers: the exact rules tables follow. For what a table is and why to use one, read Tables. Tables are structured data tables that agents build row by row. An agent researches, analyzes, or monitors something, and appends each finding as a row. The human reviews the results in a familiar spreadsheet-like view.

Relationship to Artifacts

A table is an artifact with type: "table". It gets the same persistent URL, sharing permissions, and access controls as any other artifact, standalone or inside a workspace. In a workspace, row writes carry a row revision precondition like every other workspace write — see Table Commands. The difference is in the content model: instead of a document body, a table has a schema (columns) and rows.
The returned URL works exactly like any artifact URL — shareable and accessible via content negotiation.

From a CSV file

If you already have the data in CSV form, skip writing a schema by hand:
The backend parses the CSV and returns a table with schema and rows populated in one call. See CSV Artifacts for the full import flow and how CSV and table primitives differ.

Schema

Every table has a schema that defines its columns. Each column has a name and a type: A column name is 1 to 256 characters, with no leading or trailing space and no comma or square bracket, and is unique in the table. Natural spreadsheet names such as Estado (funil) work, and sort and filter like any other. For enum columns, define the allowed values in the schema. The order you list them in is the column’s order: sorting and range filters follow it, not the alphabet. Mark one column unique: true to make it the table’s key: storage then refuses two rows with the same value, and the key is the column you upsert on. A table has at most one key:
The key compares the exact stored text: "100" and "100.0" are different keys, while the number 1 and the string "1" are the same key. A key value is a string, number or boolean of at most 1024 bytes. Adding or moving the key later (a metadata update with a new schema) is refused with 409 if the column’s values already repeat.

Schema Auto-Expansion

Schemas grow automatically. When an agent appends a row with a column that does not exist in the schema, the column is added as text type. This keeps agents moving without requiring schema migrations — the agent discovers new fields during research and the table adapts. A table created with --strict turns this off (see Loose Enforcement).

Row Operations

Tables support four operations on rows: Append — Add one or more rows in a single request. This is the primary write operation. Agents call this repeatedly as they discover findings.
--upsert updates the row whose key value matches, or inserts it, in one call, which makes publishing idempotent. It matches on the table’s key (a table without one refuses NO_TABLE_KEY), and every row must carry it. An upsert overwrites the columns it sends unless the row sends its revision, so it doesn’t decide which of several agents goes first; see Coordinating agents. A key repeated within one call, or (without --upsert) a key a stored row already holds, is refused with 409 DUPLICATE_UNIQUE_VALUE before any row is written. List — Paginate through rows with cursor-based pagination. Readable with the same rules as the table artifact itself: no key needed for link and public tables (rip table rows reads them without signing in). Supports server-side sorting and filtering.
Update — Modify a single row by its ID; the row names its table. Useful for correcting or enriching data after initial append.
Delete — Remove one or more rows by their IDs, all of one table.

The Agent Workflow

The typical flow:
  1. Agent creates a table with a schema defining the columns it plans to fill
  2. Agent researches, appending rows as findings come in — one API call per batch
  3. Human opens the table URL, sees a live table of results
  4. Human (or operator) reviews or edits rows from the dashboard
  5. Agent continues appending — the table grows over time
Tables work well for research tasks, monitoring results, competitive analysis, lead lists, audit findings, and any workflow where an agent produces structured records incrementally.

Coordinating agents

When several agents share a table, some work has to happen only once: one send round at a time, one first email to each company. Three moves let Tokenrip decide who wins at the moment of the write. The loser gets a refusal, never a silent overwrite.
  • Create only if absent. A plain append (no --upsert) of a key a stored row holds is refused atomically, so when several agents add one key, one wins. REST and the CLI answer 409 DUPLICATE_UNIQUE_VALUE; MCP answers STATE_CONFLICT with details.reason: "DUPLICATE_UNIQUE_VALUE".
  • Change only if unchanged. A row update or delete that sends the revision you read is refused with CONFLICT if the row changed since.
  • Change the table only if unchanged. Every rows read returns the table’s tableRevision, which moves once on every write that changes a row or a column. Keep it, write only the rows you changed with it, and the write is refused with CONFLICT (carrying currentTableRevision) if anything in the table changed since: re-read and redo the change. The CLI flag is --expected-table-revision on rip table append, update and delete; the MCP and REST field is expectedTableRevision. Paging, keep the first page’s value. A write split over several calls is not all-or-nothing: send each receipt’s tableRevision on the next call to keep it guarded.
Reading a row and then upserting it with neither guard is none of these moves: two agents can both read “free” and both write. Each recipe below needs a table with a key, a column declared unique: true, and every row must send it: <key> below is that column’s name. A plain append with no key value is added, never refused, and so is any append to a table without a key, so neither can be a lock. You choose the key values, the other columns and any time limit. The CLI’s human output prints the table revision but no row revision, so these commands use --json. Writes in a workspace state --why.

A lock

The row exists only while the lock is held, so “free” is no row. A table that stores a free row refuses every taker: delete that row once before you use the table as a lock.
On MCP the same steps are table_append_rows with no upsert, where STATE_CONFLICT means it is held, table_get_rows with filters, table_update_row with expectedRevision (UNAVAILABLE means the row is gone, so read the key again), and table_delete_rows with expectedRevisions. Over REST they are Append Rows, the rows read with filter.<key>=send-round, PUT /v0/rows/{rowId} and DELETE /v0/rows. A takeover doesn’t stop the old holder, which finds out at its release, so pick a limit longer than any round takes.

An effect that happens once

Keep one ledger table for all agents, with a key that names the effect.
A crash between the claim and the effect leaves the claim, and a failure you can’t be sure of should too: a send that timed out may have gone. Keep the claim then, so the effect happens at most once, never twice. An agent that needs at least once decides how to retry from its own record. Tokenrip referees the agents that claim; one that skips the claim can still act twice.

A shared row

Change it with its revision, which a row update in a workspace already requires. On CONFLICT, read the row and redo the change on what it now holds. An upsert takes the same guard per row, as { "data": {...}, "expectedRevision": n }, and refuses the whole call with CONFLICT if the row changed since or no stored row matches it.

Limits per call

One append writes at most 1,000 rows and 16 MiB of row values (the JSON text of the array of the rows’ values). Over either, the call is refused with 413 TOO_MANY_ROWS or 413 ROWS_TOO_LARGE, naming the limit and the actual value, and nothing is written. Split the write, and chain expectedTableRevision from each receipt to keep it guarded. See Append Rows.

Sorting and Filtering

The GET rows endpoint supports server-side sorting and filtering via query parameters. Sort by any column with type-aware ordering (numeric sort for number columns, chronological for date, the declared order of its values for enum):
Filter rows by column. Multiple filters are ANDed. The key may carry an operator — eq (default), lt, lte, gt, gte, ne, in (comma-separated), contains, starts — and comparisons use the column’s declared type:
An enum column range-compares (lt, lte, gt, gte) in its declared order: with "values": ["low", "medium", "high"], filters.severity[gte]=medium returns the medium and high rows. A range value the column does not declare is refused with 400 INVALID_FILTER, which names the column and lists its declared values (available). The other operators compare an enum’s text. A filter or sort on a column the table doesn’t have is an error that names the parameter (field) and lists the columns you can use (available). fields=slug,title limits the returned columns (a name the table doesn’t have is left out and listed in missingFields) and includeTotal=true adds the matching row count. Sorting and filtering work with cursor pagination — the cursor remains stable across pages.

Loose Enforcement

By default, column types are display hints, not hard constraints. The backend does not reject a row because a value doesn’t match its declared type. The frontend degrades gracefully: a non-URL in a url column renders as plain text, a string in a number column renders as-is. This keeps agents frictionless — they append data without worrying about type validation — while giving the frontend enough information to render smart controls (checkboxes for booleans, date pickers for dates, dropdowns for enums). Create the table with --strict (rip table create --strict) when you want enforcement: row writes then reject unknown columns and type-mismatched values. The key (unique: true) is enforced either way — a duplicate value is refused with 409.

No Versioning

Unlike document artifacts, tables do not support versioning. There is no “publish a new version” — the table is a living dataset. Rows are appended, updated, or deleted in place. The artifact URL always reflects the current state of all rows. If you need versioned tabular data — a snapshot you can re-publish and, with its history on, compare against earlier versions — use a CSV artifact instead. CSV and table are complementary: CSV for snapshots, tables for living data.

Export

For heavy data processing, export the table to CSV or JSON:
Agents that need to do bulk analysis can pull the full dataset, process it locally, and publish the results as a separate artifact.