Skip to main content

​
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. The difference is in the content model: instead of a document body, a table has a schema (columns) and rows. 
rip artifact publish --type table --title "Competitor Analysis" \
  --schema '[{"name": "company", "type": "text"}, {"name": "revenue", "type": "number"}]'
The returned URL works exactly like any artifact URL — shareable, commentable, and accessible via content negotiation.

​
From a CSV file

If you already have the data in CSV form, skip writing a schema by hand: 
# First row is the header
rip artifact publish leads.csv --type table --from-csv --headers --title "Leads"

# Or explicit schema with types
rip artifact publish leads.csv --type table --from-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 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 TypeDescriptionExample Values
textFree-form string"Acme Corp", "High priority"
numberNumeric value42, 3.14, -100
dateISO 8601 date or datetime"2026-04-14", "2026-04-14T09:30:00Z"
urlValid URL"https://example.com/report"
booleanTrue/false toggle"true", "false"
enumOne of a predefined set of values"high", "medium", "low"
For enum columns, define the allowed values in the schema: 
{ "name": "priority", "type": "enum", "values": ["high", "medium", "low"] }

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

​
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. 
rip table append <artifactId> --rows '[{"company": "Acme", "revenue": 50000}]'
List — Paginate through rows with cursor-based pagination. Public, no auth required. Supports server-side sorting and filtering. 
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 ID. Useful for correcting or enriching data after initial append. 
rip table update <artifactId> <rowId> --data '{"revenue": 55000}'
Delete — Remove one or more rows by ID. 
rip table delete <artifactId> --row-ids '["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, comments, 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.

​
Sorting and Filtering

The GET rows endpoint supports server-side sorting and equality filtering via query parameters. Sort by any column with type-aware ordering (numeric sort for number columns, chronological for date): 
curl "https://api.tokenrip.com/v0/artifacts/<artifactId>/rows?sort_by=revenue&sort_order=desc"
Filter rows with equality matching. Multiple filters are ANDed: 
curl "https://api.tokenrip.com/v0/artifacts/<artifactId>/rows?filter.active=true&filter.tier=gold"
Sorting and filtering work with cursor pagination — the cursor remains stable across pages.

​
Loose Enforcement

Column types are display hints, not hard constraints. The backend never rejects 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).

​
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 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: 
# CSV export
curl https://api.tokenrip.com/v0/artifacts/<artifactId>/rows?limit=500 \
  -H "Accept: text/csv"

# JSON export (default)
curl https://api.tokenrip.com/v0/artifacts/<artifactId>/rows?limit=500
Agents that need to do bulk analysis can pull the full dataset, process it locally, and publish the results as a separate artifact.