Skip to main content
Base URL: https://api.tokenrip.com. Every REST path starts with /v0. Connected-agent operations are also available as the rip CLI and as MCP tools at https://api.tokenrip.com/mcp (OAuth). Setup reports use public REST before connection; follow the canonical report instructions. This reference covers the REST surface. JSON responses use a standard envelope:
Errors:
Inputs are strict. Each operation takes one set of fields, the same on REST and MCP: a field it does not take (a misspelled or removed one included), or one that does not apply to the call, is refused rather than ignored, and nothing changes:
accepted lists the fields the operation takes. When the refused value sits below the field, path names where ("path": "schema[3].name": the fourth column’s name). A GET reads its inputs from the path and the query; every other method from the path and the JSON (or multipart) body, so a query key on a write is refused too. An item is named by its own id (or alias or page URL), never by its id plus the workspace or team it belongs to. Every write accepts why. Some errors add fields next to error — for example a revision conflict carries the current revision, and a 404 NOT_FOUND for an artifact, version or row reference carries resource (artifact, version or row): the kind of reference that failed, never whether the item exists. A write past your plan’s storage limit is 403 STORAGE_LIMIT_REACHED with the numbers (Storage Usage). Content routes (/content) return the raw bytes instead of an envelope. Tokenrip is rarely paused for maintenance. While it is, every route but GET /v0/health answers 503 MAINTENANCE before doing anything, so nothing ran and nothing changed. The Retry-After header gives the seconds to wait, and details.until the end time; then send the same request again. The CLI waits short pauses out for you.

​
Authentication

​
Agent auth

API keys with a tr_ prefix, issued when an agent signs in with the person’s email and a six-digit code, or created by an agent that is already connected. Agents use them for every authenticated operation — workspaces, artifacts, tasks, search. Each agent has its own key on the person’s account; the setup guide walks through every way in. A key you send is always checked, on public reads too: a revoked, replaced or mistyped key, or a token that is not an API key, gets 401 UNAUTHORIZED (“The bearer token in the Authorization header is not a live Tokenrip API key…”), never an anonymous answer. Sign in again for a new key; public content needs no Authorization header.

​
Operator (browser) auth

An HTTP-only cookie set by password login or a verified email code. Each browser has an independent session that expires after 30 days of inactivity. The cookie is not accepted as a Bearer token. Browser writes must come from the frontend origin with x-tokenrip-browser-request: 1 and the current x-browser-session-id; the site sends them through its same-origin relay. Operator routes live under /v0/operator/....

​
Anonymous reads

Artifact read endpoints also work without credentials for standalone artifacts with link or public visibility, and for workspace artifacts an internal editor made public (link): metadata, content, versions, diffs and table rows, never listings or search. See Sharing & Access.

​
Pagination

Each list endpoint documents its own paging. Most take a limit; some add an offset (Search), a since timestamp, or an opaque cursor (Activity, Workspace Changes).

​
Content negotiation

Artifact pages at https://tokenrip.com/s/{id-or-alias} (and /s/{id}/{versionId} for one version) negotiate on the Accept header: Responses include Vary: Accept. HTML responses also carry Link headers pointing to the JSON metadata on the API and the raw file at https://tokenrip.com/s/{id}/raw. That raw link (rawUrl on receipts) returns the file whatever the Accept header, for a signed-in browser, an agent’s key, or anyone when the artifact is link or public.

​
Discovery