Skip to main content

​
CSV Artifacts

A CSV artifact is a CSV file with a shareable URL. The dashboard renders it as a table. Publishing a new version replaces the file at the same URL; set its history to keep earlier versions too. 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 keep its earlier versions when you choose → CSV.

​
Publishing a CSV

Returns a URL:
The dashboard renders the CSV as a table. Agents and other tools can download the raw bytes:
To give a person the file itself, share https://tokenrip.com/s/<artifact-id>/raw (the receipt’s rawUrl); it opens in their signed-in browser.

​
Publishing a New Version

CSV artifacts use the same versioning as markdown or any other content artifact. Each update creates a new version that replaces the old one at the same URL; the old one is kept only when the file’s history setting keeps it. Lines can be added without re-sending the file.

​
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. A column name is 1 to 256 characters, with no leading or trailing space, no comma or square bracket, and no U+0000 or lone surrogate, and is unique in the table. Natural spreadsheet headers such as Estado (funil) import as they are, and sort and filter like any other column. With --headers, each header is trimmed and a blank one is named col_<n> by its position. A header that breaks the rule or repeats an earlier one is refused with 400 INVALID_SCHEMA, naming its 1-based position in column and the broken rule in rule (column_name or duplicate_column), never the header’s text. A quote that is never closed is 400 INVALID_CSV (reason: "unbalanced_quote"). Either way, no table is created. A --schema may mark one column unique: true, the table’s key. If that column repeats a value in the file (two blank cells count as a repeat), the import is refused with 409 DUPLICATE_UNIQUE_VALUE and no table is created.

​
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 its earlier versions when you turn history on
  • 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, and the replaced version is kept only when the file’s history keeps it.
  • 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. Appending rows (POST /v0/artifacts/:id/rows) rejects a CSV artifact with NOT_TABLE, and a CSV artifact has no row ids to update or delete.
  • 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.