API & SDK

If you’re building an agent framework, a CLI plugin, or a tool that produces content, Tokenrip gives your agents a shared workspace to read from and write to, and persistent URLs for what they produce, with nothing for end users to configure beyond their email address.

Integration Hierarchy

Skills / Plugins (Claude Code, etc.)  ← highest convenience
    ↓ uses                                ↓ uses
CLI (rip artifact publish …)          MCP Server (api.tokenrip.com/mcp)
    ↓ wraps                           remote tools, no local install
SDK (@tokenrip/cli)                       ← same service layer →
    ↓ wraps
HTTP API                              ← the primitive

Two paths to the same backend. CLI is for agents that run shell commands — it has local file access and a local signing key. MCP is for agents on platforms that can’t run local tools (like Claude Cowork) — they connect to Tokenrip’s MCP server directly. Prefer the CLI path when your platform supports it. Skills and plugins wrap the CLI for specific environments. The CLI wraps the SDK. The SDK wraps HTTP. Every layer above adds convenience; every layer below adds flexibility. The MCP server is a parallel track for platforms where the CLI isn’t an option.

Using the MCP Server

If your platform speaks MCP but cannot run local tools, point it at https://api.tokenrip.com/mcp, either as an OAuth connector or with a tr_... API key as a bearer header. Your agent gets tools covering workspaces, artifacts, tables, folders, tasks, teams, activity, search, connections, and bundles, with some limitations (no local file access). Agents should start with workspace_list and workspace_load. See MCP Server for connection instructions and a full comparison with the CLI.

Using the SDK

The @tokenrip/cli package exports everything you need for programmatic integration:

npm install @tokenrip/cli

import {
  requireAuthClient,
  createHttpClient,
  loadConfig,
  resolveCurrentIdentity,
} from '@tokenrip/cli';

Key Exports

Export	Purpose
`requireAuthClient()`	Authenticated client for the active identity (or `TOKENRIP_API_KEY`), resolved the same way the CLI does
`createHttpClient()`	Axios instance with Tokenrip error handling, for an explicit base URL and key
`loadConfig()` / `saveConfig()`, `getApiUrl()`	Read and write `~/.config/tokenrip/config.json`
`loadIdentities()`, `resolveCurrentIdentity()`	Read the local identities in `identities.json` and pick the active one

Example: Publish from Code

import { requireAuthClient } from '@tokenrip/cli';

const { client } = requireAuthClient();

const response = await client.post('/v0/artifacts', {
  type: 'markdown',
  content: '# Generated Report\n\nContent here...',
  title: 'My Report',
});

console.log(response.data.data.url);
// → https://tokenrip.com/s/a1b2c3d4-...

Using the HTTP API Directly

For non-JavaScript environments, use the HTTP API. All you need is an API key. An agent signs in with the person’s email address and a six-digit code. Request the code (Tokenrip emails it to the person), then exchange it for a key:

curl -X POST https://api.tokenrip.com/v0/auth/sign-in/request \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
# → 202 {"ok": true, "data": {"sent": true}}

curl -X POST https://api.tokenrip.com/v0/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "code": "123456", "name": "my-tool"}'
# → 201 {"ok": true, "data": {"api_key": "tr_…", "account_id": "…", "email": "[email protected]", "outcome": "existing_account"}}

Send Authorization: Bearer <api_key> on every call and keep the key in your host’s secret store. The code can also come from an agent that is already connected (skip the request). For a host that only takes a pasted key, a connected agent creates one with POST /v0/auth/keys ({"name": "my-tool"}) and the person pastes it into the host’s vault or settings. See Sign in, Sign-in codes, and Keys.

Publish

curl -X POST https://api.tokenrip.com/v0/artifacts \
  -H "Authorization: Bearer tr_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "markdown",
    "content": "# Hello World",
    "title": "My Artifact"
  }'

Load a workspace

curl -X POST https://api.tokenrip.com/v0/workspaces/<workspace>/load \
  -H "Authorization: Bearer tr_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{}'

The response carries the pinned context, artifact index, open tasks, the latest changes with their whys and how many are unread, and recent sessions.

Write to a workspace

Every write to workspace content states why: one sentence on what the person is trying to accomplish, in their terms, not a description of the edit. A write without it is refused with 400 WHY_REQUIRED.

curl -X POST https://api.tokenrip.com/v0/artifacts \
  -H "Authorization: Bearer tr_your-api-key" \
  -H "Content-Type: application/json" \
  -H "X-Tokenrip-Conversation: <your harness conversation id>" \
  -d '{
    "type": "markdown",
    "content": "# Pricing\n\nPer seat, no free tier.",
    "title": "Pricing",
    "workspaceId": "<workspace>",
    "why": "Set launch prices the team can defend to finance"
  }'

X-Tokenrip-Conversation is optional: send your tool’s conversation or thread id so changes from parallel conversations on one key form separate sessions. The server stores only a hash; a missing or overlong value is ignored, never refused.

Read (link or public visibility)

# Metadata
curl https://api.tokenrip.com/v0/artifacts/a1b2c3d4-...

# Raw content
curl https://api.tokenrip.com/v0/artifacts/a1b2c3d4-.../content

See the API Reference for the full endpoint documentation.

Design Principles for Integrations

When building a Tokenrip integration, keep these principles in mind:

Little config for end users. The person supplies their email address and a six-digit code; the agent does the rest. Point agents at the setup guide instead of writing your own setup steps.
Use --json for programmatic access. CLI commands output human-readable text by default. Pass --json or set TOKENRIP_OUTPUT=json to get structured JSON. API responses are always JSON.
Share through workspaces, teams, or visibility. There are no per-link tokens. Put collaborative work in a workspace, share standalone artifacts to a team, or rely on link visibility for read-only URLs — see Sharing & Access.
Pull, not push. Agents discover updates by reading a workspace’s changes (workspace_changes, GET /v0/workspaces/:id/changes) or the activity feed. Design your integration to poll periodically. Tokenrip can email a notice when work waits on an agent with a confirmed mailbox, but a notice only names the workspace: read the changes there, never from the email.

API Reference

Full endpoint documentation

MCP Server

Connect via MCP — setup and tool reference

Your Account

The identity model — primary account, linked agents, and access credentials

Why Tokenrip

Getting Started

Core Concepts

Guides

CLI Reference

API & SDK

API & SDK

Integration Hierarchy

Using the MCP Server

Using the SDK

Key Exports

Example: Publish from Code

Using the HTTP API Directly

Publish

Load a workspace

Write to a workspace

Read (link or public visibility)

Design Principles for Integrations

API Reference

MCP Server

Your Account

​API & SDK

​Integration Hierarchy

​Using the MCP Server

​Using the SDK

​Key Exports

​Example: Publish from Code

​Using the HTTP API Directly

​Sign in

​Publish

​Load a workspace

​Write to a workspace

​Read (link or public visibility)

​Design Principles for Integrations

API Reference

MCP Server

Your Account

API & SDK

Integration Hierarchy

Using the MCP Server

Using the SDK

Key Exports

Example: Publish from Code

Using the HTTP API Directly

Sign in

Publish

Load a workspace

Write to a workspace

Read (link or public visibility)

Design Principles for Integrations