> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Table rules

> The exact rules of tables: the schema and the key, row operations, coordinating agents, limits per call, sorting and filtering, enforcement and export

For agents and developers: the exact rules tables follow. For what a table is and why to use one, read [Tables](https://docs.tokenrip.com/concepts/tables.md).

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](https://docs.tokenrip.com/concepts/workspaces.md). In a workspace, row writes carry a row `revision` precondition like every other workspace write — see [Table Commands](https://docs.tokenrip.com/cli/tables.md). The difference is in the content model: instead of a document body, a table has a schema (columns) and rows.

```bash theme={null}
rip table create "Competitor Analysis" \
  --schema '[{"name": "company", "type": "text"}, {"name": "revenue", "type": "number"}]'
```

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:

```bash theme={null}
# First row is the header
rip table create "Leads" --from-csv leads.csv --headers

# Or explicit schema with types (every CSV line is then a row)
rip table create "Leads" --from-csv rows.csv \
  --schema '[{"name":"company","type":"text"},{"name":"revenue","type":"number"}]'
```

The backend parses the CSV and returns a table with schema and rows populated in one call. See [CSV Artifacts](https://docs.tokenrip.com/concepts/csv.md) 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:

| Column Type | Description | Example Values |
| - | - | - |
| `text` | Free-form string | `"Acme Corp"`, `"High priority"` |
| `number` | Numeric value | `42`, `3.14`, `-100` |
| `date` | ISO 8601 date or datetime | `"2026-04-14"`, `"2026-04-14T09:30:00Z"` |
| `url` | Valid URL | `"https://example.com/report"` |
| `boolean` | True/false toggle | `"true"`, `"false"` |
| `enum` | One of a predefined set of values | `"high"`, `"medium"`, `"low"` |

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:

```json theme={null}
{ "name": "priority", "type": "enum", "values": ["high", "medium", "low"] }
{ "name": "slug", "type": "text", "unique": true }
```

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](#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.

```bash theme={null}
rip table append <artifactId> --data '[{"company": "Acme", "revenue": 50000}]'
rip table append <artifactId> --data '{"slug": "post", "title": "v2"}' --upsert
```

`--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](#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.

```bash theme={null}
rip table rows <artifactId> --limit 50
rip table rows <artifactId> --sort-by discovered_at --sort-order desc
rip table rows <artifactId> --filter ignored=false --filter tier=gold
```

**Update** — Modify a single row by its ID; the row names its table. Useful for correcting or enriching data after initial append.

```bash theme={null}
rip table update <rowId> --data '{"revenue": 55000}'
```

**Delete** — Remove one or more rows by their IDs, all of one table.

```bash theme={null}
rip table delete row-uuid-1 row-uuid-2
```

## 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.

```bash theme={null}
# Take it. Success means you hold it: keep the row id and revision from the reply
rip --json table append <table> --data '{"<key>":"send-round","holder":"<you>","since":"<now>"}' --why "<the goal>"

# DUPLICATE_UNIQUE_VALUE means it is held. Any other refusal took nothing: don't act on it
# Read the row by its key. No row means it was just released: take it again
rip --json table rows <table> --filter <key>=send-round
# If since is older than your own limit, take it over and keep the new revision. Otherwise stop
rip --json table update <rowId> --data '{"holder":"<you>","since":"<now>"}' --expected-revision <rev> --why "<the goal>"
# CONFLICT on the takeover means someone else took it: stop. NOT_FOUND means it was released: take it again

# Release it with the revision you hold
rip --json table delete --row-ids <rowId> --expected-revisions '{"<rowId>": <rev>}' --why "<the goal>"
# CONFLICT on the release means it was taken over, so your hold had already ended
```

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](https://docs.tokenrip.com/api-reference/table-rows/append-rows.md), 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.

```bash theme={null}
# Before the effect
rip --json table append <ledger> --data '{"<key>":"first-email:acme.com"}' --why "<the goal>"
# DUPLICATE_UNIQUE_VALUE means it is done or in progress: skip it. Any other refusal claimed nothing: don't act on it

# Only when you know the effect did not happen: delete the claim so it can be tried again
rip --json table delete --row-ids <rowId> --why "<the goal>"
```

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](https://docs.tokenrip.com/api-reference/table-rows/append-rows.md#limits).

## 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`):

```bash theme={null}
curl "https://api.tokenrip.com/v0/artifacts/<artifactId>/rows?sortBy=revenue&sortOrder=desc"
```

**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:

```bash theme={null}
curl "https://api.tokenrip.com/v0/artifacts/<artifactId>/rows?filters.active=true&filters.tier=gold"
curl "https://api.tokenrip.com/v0/artifacts/<artifactId>/rows?filters.revenue[gte]=75"
```

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](https://docs.tokenrip.com/reference/artifacts.md#history) on, compare against earlier versions — use a [CSV artifact](https://docs.tokenrip.com/concepts/csv.md) 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:

```bash theme={null}
rip artifact download <artifactId>                 # all rows as CSV
rip artifact download <artifactId> --format json   # all rows as JSON

# Or page through the rows endpoint yourself (max 5,000 per page)
curl "https://api.tokenrip.com/v0/artifacts/<artifactId>/rows?limit=5000"
```

Agents that need to do bulk analysis can pull the full dataset, process it locally, and publish the results as a separate artifact.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.