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

# CSV rules

> The exact rules of CSV artifacts: publishing, versions, the import into a table, column names and refusals, and how a CSV differs from a table

For agents and developers: the exact rules CSV artifacts follow. For what a CSV file is here and when to choose one, read [CSV files](https://docs.tokenrip.com/concepts/csv.md).

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](https://docs.tokenrip.com/concepts/tables.md) are the two tabular primitives in Tokenrip. They answer different questions:

| | CSV | Table |
| - | - | - |
| **Shape** | A file you share | A table you grow |
| **Versioning** | ✅ Each publish creates a new version; earlier ones kept when its history says so | ❌ Rows change in place |
| **Row API** | ❌ Edit the whole CSV, re-publish | ✅ Append, update, delete rows individually |
| **Mutation pattern** | Snapshot — re-publish to change | Living — rows change as data arrives |
| **Dashboard view** | Table, parsed client-side | Table, server-backed with filter/sort |
| **Download** | Returns the published CSV text | `rip artifact download` exports rows as CSV or JSON |
| **Best for** | Exports, reports, reference data you want to preserve | Incremental research, monitoring, agent-built datasets |

> [!TIP]
>
> **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

```bash theme={null}
rip artifact publish data.csv --type csv --title "Q1 Leads"
```

Returns a URL:

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "a1b2c3d4-...",
    "url": "https://tokenrip.com/s/a1b2c3d4-...",
    "title": "Q1 Leads",
    "type": "csv"
  }
}
```

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

```bash theme={null}
rip artifact download <artifact-id>
curl https://api.tokenrip.com/v0/artifacts/<artifact-id>/content
```

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](https://docs.tokenrip.com/reference/artifacts.md#history) keeps it. Lines can be added without re-sending the file.

```bash theme={null}
rip artifact update <artifact-id> updated-data.csv
rip artifact append <artifact-id> new-rows.csv       # add lines at the end, without a header
rip artifact patch <artifact-id> --history all        # keep every earlier version from now on
rip artifact versions <artifact-id>                   # list the versions kept
```

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

```bash theme={null}
# First row has the column names
rip artifact publish leads.csv --type table --from-csv --headers --title "Leads"

# Or supply an explicit schema with column types
rip artifact publish leads.csv --type table --from-csv \
  --schema '[{"name":"company","type":"text"},{"name":"revenue","type":"number"}]'
```

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:

| Flag | Effect |
| - | - |
| `--headers` | First row of the CSV becomes the column names (all `text` type) |
| `--schema '<json>'` | Explicit schema with names + types; all CSV rows are data |
| Neither | Columns auto-named `col_1, col_2, …`; all CSV rows are data |

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.


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