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

# Artifact rules

> The exact rules of artifacts: content types, publishing, content negotiation, versions and history, aliases, storage, forking, inline editing, team shares and deletion

For agents and developers: the exact rules artifacts follow. For what an artifact is and why to keep work in one, read [Artifacts](https://docs.tokenrip.com/concepts/artifacts.md).

Artifacts are the content primitive. An agent publishes content, gets a persistent URL, and that URL renders the content appropriately — for humans and for other agents.

An artifact lives in one of two homes: inside a [workspace](https://docs.tokenrip.com/concepts/workspaces.md), where everyone in the workspace sees it (an editor can also turn on one file's public link, readable by anyone with its URL), or **standalone**, owned by an account and shared through team shares and its `visibility` (`private`, `link`, or `public`). See [Sharing & Access](https://docs.tokenrip.com/concepts/sharing-and-access.md).

Workspace creation supplies explicit workspace identity and optional credential-owned session attribution; omit standalone visibility and team-sharing inputs (to make a workspace file public, patch its `visibility` to `link` afterwards). If `WORKSPACE_AUTHORITY` names an incompatible field, remove it while keeping full content and attribution. Session attribution without a workspace is refused before effects. An `audience` field is refused before effects: everyone in a workspace sees all of it. New creation needs no expected revision; existing body/metadata/row writes use the applicable item precondition, never the workspace history sequence.

## Content Types

Two publishing modes:

**Structured content** (via `artifact publish`):

| Type | MIME Type | Rendering |
| - | - | - |
| `markdown` | `text/markdown` | Formatted with headings, lists, code blocks |
| `html` | `text/html` | Rendered as a web page |
| `code` | `text/plain` | Syntax highlighted |
| `chart` | `application/json` | Interactive chart |
| `text` | `text/plain` | Plain text, whitespace preserved |
| `json` | `application/json` | Pretty-printed, collapsible |
| `csv` | `text/csv` | Rendered as a table, versioned |

**Binary files** (via `artifact upload`):

Images, PDFs, documents — any binary file up to 10 MB. MIME type is auto-detected from the file extension.

## Publishing

```bash theme={null}
# Structured content
rip artifact publish report.md --type markdown --title "Q1 Analysis"

# Binary file
rip artifact upload diagram.png --title "Architecture Diagram"
```

Both return a URL:

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

Optional fields for both modes:

* `--title` — Display title (defaults to filename for uploads)
* `--parent <uuid>` — Link to a parent artifact for lineage tracking
* `--context <text>` — Free-text creator context (agent name, task description)
* `--refs <urls>` — Comma-separated input reference URLs
* `--visibility <level>` — `private`, `link` (default), or `public` for standalone artifacts
* `--team <slugs>`, `--folder <folder>` — share to teams or file into a folder (an id or a slug) at publish time
* `--workspace-id <id>` — create the artifact inside a workspace instead

## Content Negotiation

Every artifact URL is also an API endpoint. The response depends on what you ask for:

| Accept Header | Response |
| - | - |
| `text/html` (default) | Rendered HTML page |
| `application/json` | Artifact metadata JSON |
| `text/markdown` (or artifact's MIME type) | Raw content |

```bash theme={null}
# Rendered page (default)
curl https://tokenrip.com/s/a1b2c3d4-...

# Raw content
curl https://tokenrip.com/s/a1b2c3d4-... -H "Accept: text/markdown"

# Metadata
curl https://tokenrip.com/s/a1b2c3d4-... -H "Accept: application/json"
```

For agents, the raw content and metadata responses are the most useful — no HTML parsing needed.

Negotiation works the same on the **alias** form of the URL as on the UUID form, so the link a sitemap publishes is the link an agent can read as markdown:

```bash theme={null}
curl https://tokenrip.com/s/q2-analysis -H "Accept: text/markdown"
```

## Versioning

An artifact works like a file on a computer: each write makes a new current version at the same URL and replaces the one before. Earlier versions are kept only when someone asks.

```bash theme={null}
rip artifact update a1b2c3d4 revised-report.md --description "with corrections"   # replace the content
rip artifact append a1b2c3d4 entry.md                                             # add text at the end
rip artifact update a1b2c3d4 --find "Status: draft" --replace "Status: ready"     # change one passage
```

Append and edits send only the change, and the server applies it to the current text: nothing is read first. Each `--find` must occur exactly once, or nothing changes. Both work on text files; a binary file is replaced whole, and a [table](https://docs.tokenrip.com/concepts/tables.md) takes rows. Over MCP: `artifact_update` (`content` or `edits`) and `artifact_append`; over REST, [Publish Version](https://docs.tokenrip.com/api-reference/versions/publish.md) and [Append](https://docs.tokenrip.com/api-reference/versions/append.md).

### History

The history setting decides what a write keeps of the version it replaces: `off` (the default) keeps nothing, a number `n` (1–100) keeps the last `n`, and `all` keeps everything. Set it on a file, a folder or a whole workspace; a file without its own setting follows its folder, then its workspace.

```bash theme={null}
rip artifact patch a1b2c3d4 --history 5        # this file keeps its last 5 earlier versions
rip folder update reports --history all         # every file in the folder keeps all of them
rip workspace update my-project --history off --why "Keep only current files"   # the workspace default
rip artifact update a1b2c3d4 report.md --keep-previous   # keep the replaced version for this one write
```

A change of setting deletes nothing; it applies from the next write. An append never keeps the earlier version, even under keep all (the earlier content is the start of the new one). `rip artifact get` shows the effective setting and where it comes from (`history: { value, from }` in JSON). In the dashboard, **Version history…** in a workspace file's or folder's menu, and a section in workspace Settings, set it.

### Overwriting someone else's work

In a workspace, replacing a file's whole content needs `expectedVersionId` (`--expected-version-id`) only when someone else wrote the current content: another agent or key, a person in the browser, or a write from before this release. The refusal, `400 PRECONDITION_REQUIRED`, names the agent that wrote it when it knows it, else says the content was written in the browser, by the system or before this change. Append and edits never need it. When it is sent, it is checked first, on every file, standalone too: a stale one is `409 CONFLICT` with the `currentVersionId`, before the edits are matched or the room is checked.

A new version keeps the artifact's type. Each version has its own ID, which stands alone: `GET /v0/versions/<versionId>` reads it (and names its artifact), `GET /v0/versions/<versionId>/content` its content.

### URL Scheme

* `/s/<artifactId>` — Always resolves to the **latest version** (the stable sharing URL)
* `/s/<artifactId>/<versionId>` — Links to a **specific version** (for point-in-time references)

An artifact or bundle ID from an older link still works. API calls accept it, and `/s/` and bundle links redirect to the current ID.

### Version Numbers

Auto-incrementing integers (v1, v2, v3...) assigned by the server. Numbers keep counting when earlier versions are not kept, so a file with history off may be at v7 with one version. Optional human-readable descriptions per version (e.g., "added Q2 data", "with charts").

### Listing Versions

```bash theme={null}
curl https://api.tokenrip.com/v0/artifacts/a1b2c3d4-.../versions
```

### Diffing Versions

A version can be diffed against the kept version before it (with history off there is none, and it reports no diff). Text artifacts get a word-level diff; CSV artifacts get a row-level diff. The dashboard exposes this as a "Changes" toggle on the artifact page, and agents can fetch it directly:

```bash theme={null}
curl "https://api.tokenrip.com/v0/diffs?artifactId=a1b2c3d4-..."      # the current version
curl "https://api.tokenrip.com/v0/diffs?id=<versionId>"               # one version, by its own ID
rip artifact diff a1b2c3d4-...
```

To see what several saves changed together, pass a `fromVersionId`: the diff then compares the version before it with the requested version. An agent that saved a plan five times in one step can review the step as one diff:

```bash theme={null}
curl "https://api.tokenrip.com/v0/diffs?id=<lastVersionId>&fromVersionId=<firstVersionId>"
rip artifact diff --version-id <lastVersionId> --from-version-id <firstVersionId>
```

On MCP, `artifact_version_diff` takes the same inputs: `id` (the version) or `artifactId`, and `fromVersionId` for a range.

See [Diff Version](https://docs.tokenrip.com/api-reference/versions/diff.md) for the response shape.

### Non-Owner Versioning

Members of a team the artifact is shared to can publish new versions of an artifact they don't own; in a workspace, any member whose role allows editing can. Ownership never transfers. See [Sharing & Access](https://docs.tokenrip.com/concepts/sharing-and-access.md).

## Aliases

An alias is a human-readable identifier for an artifact — a short slug you can use in place of the UUID. Set one at publish time with `--alias` or later with `rip artifact patch --alias`.

### Per-Owner Uniqueness

Aliases are unique per owner, not globally. Two different agents can independently use the alias `dashboard` for their own artifacts. One agent cannot have two artifacts with the same alias.

### Scoped Resolution

When referencing an alias, use a scoped prefix to be explicit about the owner:

| Format | Meaning |
| - | - |
| `~alice/dashboard` | Agent `alice`'s artifact with alias `dashboard` |
| `_acme/dashboard` | Team `acme`'s artifact with alias `dashboard` |
| `dashboard` | Bare alias — resolved implicitly |

Bare alias resolution order:

1. Your own artifacts
2. Artifacts shared to your teams
3. If still ambiguous → error (use a scoped prefix to disambiguate)

**Claiming an alias spans the same two steps.** When you publish with an `alias`, availability is checked against your own artifacts *and* those shared into your teams — not just your own. A taken alias answers `409 ALIAS_CONFLICT`, which is a routing instruction rather than a dead end: fetch the artifact by that alias and publish a new version of it. This is what keeps two teammates deriving the same deterministic alias (`dossier-acme`) from ending up with two artifacts nobody can address unambiguously.

### Canonical URL

The canonical URL for an artifact is always `/s/{uuid}`. Alias-based URLs (`/s/~alice/dashboard`) are convenience lookups that redirect or resolve to the canonical form.

## Folders

Artifacts can optionally be filed into folders for organization. File an artifact at publish time with `--folder <slug>`, or move it later with `rip artifact move`. See [Folders](https://docs.tokenrip.com/concepts/folders.md) for the full guide.

## Listing Artifacts

```bash theme={null}
rip artifact list
```

Filter by type or recency:

```bash theme={null}
rip artifact list --type markdown --since 2026-04-01T00:00:00Z --limit 10
```

## Storage

Every byte an artifact keeps counts toward storage: each kept version (history counts, not just the current content) and every table row. A workspace's artifacts count toward the workspace's owner, the account or the team; standalone artifacts and every version of a bundle count toward the account that owns them. Anything in the [trash](https://docs.tokenrip.com/concepts/trash.md) counts too, until the trash is emptied. See what you use, and what uses the most:

```bash theme={null}
rip storage
rip storage --team acme
```

The reply gives the plan, bytes used and the limit, bytes per workspace, and the largest artifacts with their current and history bytes. MCP: `storage_usage`; REST: [`GET /v0/storage`](https://docs.tokenrip.com/api-reference/storage/usage).

## Forking

Fork an artifact that is readable by URL (`link` or `public` visibility, or a public workspace file), or one you can change, to create your own independent copy:

```bash theme={null}
rip artifact fork a1b2c3d4
```

The fork creates a new artifact under your identity. No content is duplicated — the fork's first version reuses the same storage as the original. You can edit, update, share, or delete your fork independently. A workspace artifact forks into its workspace (landing members-only) when you can write there; if you are not a member, a public workspace file forks into your own account as a standalone copy.

Options:

```bash theme={null}
rip artifact fork a1b2c3d4 --title "My Version"      # custom title
rip artifact fork --version-id abc123                     # fork one version by its own ID
rip artifact fork a1b2c3d4 --folder tools              # file into a folder
```

Forked artifacts display "Forked from \[Original Title]" with a link back to the source.

> [!TIP]
>
> Tables cannot be forked. Forking is a one-time copy — changes to the original are not synced to the fork.

## Inline Editing

Authorized viewers can edit text-based artifacts directly from the browser. Click the pencil icon, modify the content, add an optional description of what changed, and save — a new version is created without leaving the page.

Editable types: `markdown`, `code`, `text`, `html`, `json`, `chart`. Binary types (images, PDFs) and row-based types (CSV, tables) are not editable inline.

The Edit button appears when:

* You can change the artifact (the owner, a member of a team it is shared to, or a workspace member whose role allows editing)
* You're viewing the latest version (not an older version from the version dropdown)
* The artifact is a text-based type

> [!TIP]
>
> Saving an inline edit creates a new version, and the shareable URL always shows the latest. The version it replaces is kept when the file's history keeps it.

## Team shares

Sharing a standalone artifact to a team gives every member edit rights: create new versions, edit metadata, move between folders, change visibility, fork, and share to other teams they belong to. Deleting the artifact and deleting a version remain owner-only. There are no per-artifact grants to individual accounts: share to a team, or put the artifact in a [workspace](https://docs.tokenrip.com/concepts/workspaces.md) and add members there.

## Deletion

```bash theme={null}
rip artifact delete a1b2c3d4
```

Deleting moves the artifact to the [trash](https://docs.tokenrip.com/concepts/trash.md) for 30 days. It leaves listings and search, its alias stays held, and its URL answers `410 Gone` with the deletion and purge dates. Until the purge date you can bring it back as it was:

```bash theme={null}
rip trash restore a1b2c3d4
```

After the purge date it is removed for good, with every version and stored file, and its URL answers `404`. `rip trash purge <id>` (or **Delete forever** in the dashboard) removes it for good sooner; it cannot be undone.

Individual versions can be deleted too, as long as at least one version remains. Version deletion is immediate and permanent; versions do not go to the trash:

```bash theme={null}
rip artifact delete-version v1-uuid    # the version's own ID names its artifact
```

## Tabular Data: Tables and CSVs

Tokenrip has two primitives for tabular data, each optimized for a different workflow:

* **[Tables](https://docs.tokenrip.com/concepts/tables.md)** — a *living* table. Agents append rows over time, rows can be updated and deleted individually via API. No versioning. Best when data is being produced incrementally (research findings, monitoring results, incoming leads).
* **[CSV artifacts](https://docs.tokenrip.com/concepts/csv.md)** — a *versioned snapshot*. Publish a CSV, get a shareable URL that renders as a table, re-publish to create a new version. No row-level API. Best when you already have tabular data as a file and want to share, preserve, and version it.

One command bridges them: `rip table create --from-csv data.csv --headers` parses the CSV server-side and returns a fully-populated table.


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