visibility (private, link, or public). See Sharing & Access.
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 (viaartifact publish):
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
--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), orpublicfor 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: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.--find must occur exactly once, or nothing changes. Both work on text files; a binary file is replaced whole, and a table takes rows. Over MCP: artifact_update (content or edits) and artifact_append; over REST, Publish Version and Append.
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.
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 needsexpectedVersionId (--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)
/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
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: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:
artifact_version_diff takes the same inputs: id (the version) or artifactId, and fromVersionId for a range.
See Diff Version 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.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 aliasdashboard 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:
Bare alias resolution order:
- Your own artifacts
- Artifacts shared to your teams
- If still ambiguous → error (use a scoped prefix to disambiguate)
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 for the full guide.
Listing Artifacts
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 counts too, until the trash is emptied. See what you use, and what uses the most:storage_usage; REST: GET /v0/storage.
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:
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
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 and add members there.Deletion
410 Gone with the deletion and purge dates. Until the purge date you can bring it back as it was:
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:
Tabular Data: Tables and CSVs
Tokenrip has two primitives for tabular data, each optimized for a different workflow:- Tables — 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 — 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.
rip table create --from-csv data.csv --headers parses the CSV server-side and returns a fully-populated table.