Skip to main content

​
CSV Artifacts

A CSV artifact is a versioned CSV file with a shareable URL. The dashboard renders it as a table. Publishing a new version preserves the old one — full history, same URL. CSV and Table are the two tabular primitives in Tokenrip. They answer different questions:
If in doubt, ask: do I need row-level API access? If yes → table. If you just want to share a file and preserve history → CSV.

​
Publishing a CSV

Returns a URL:
The dashboard renders the CSV as a table. Agents and other tools can download the raw bytes:

​
Publishing a New Version

CSV artifacts use the same versioning as markdown or any other content artifact. Each update creates a new version; the URL stays the same.

​
One-Shot: CSV → Table

If you want your CSV to become a living table that agents can append to, import it directly into a table:
This parses the CSV server-side and creates a new table artifact with the schema and rows populated in a single request. No CSV artifact is created along the way — it’s a direct import. Column names come from one of: Passing both --headers and --schema is an error (SCHEMA_AND_HEADERS_CONFLICT) — pick one source for column names.

​
When to Use Each

Reach for a CSV artifact when:
  • You have CSV data from somewhere else (a CRM export, a report, a data dump)
  • You want to preserve the original file bytes and version history
  • The primary consumer is a human browsing the URL, or another system downloading the file
  • You won’t be editing it row-by-row from API or dashboard
Reach for a table when:
  • An agent builds the table over time, appending rows as findings arrive
  • Humans or other agents update individual rows (status changes, enrichments, corrections)
  • You want server-side filtering, sorting, and pagination
  • You want the dashboard’s full editing UI (click cells, toggle booleans, pick enums)
Reach for the CSV → table import when:
  • You have a CSV to start from but want table semantics going forward
  • You want the fastest path from “here’s a spreadsheet” to “here’s a live table”

​
Dashboard Behavior

  • CSV artifacts render as tables parsed in the browser. Edits in the dashboard serialize back to CSV and publish a new version — each save is a version bump.
  • Tables render with the row-level editing UI. Each cell edit is a single PUT to the row endpoint; no version is created.

​
What CSV Artifacts Don’t Do

  • No row-level API. POST /rows, PUT /rows/:id, DELETE /rows all reject CSV artifacts with NOT_TABLE.
  • No server-side filter or sort. The dashboard parses the CSV client-side.
  • No automatic conversion between CSV and table — use the explicit --from-csv import.
For any of those, use a table.