TokenJam for developers

Every programmatic surface TokenJam exposes, in one place. Nothing here needs an account: the CLI runs locally, the SDKs are published packages, and the website content API is public and unauthenticated.

Quickstart

Current release: tokenjam 0.6.11 on PyPI, @tokenjam/sdk 0.6.11 on npm.

# Peek at what your Claude Code sessions already cost — no install, nothing written
npx tokenjam

# Install the CLI
pipx install tokenjam

# Wire up Claude Code or Codex with zero code changes
tj onboard --claude-code

# See where the tokens went, and what is recoverable
tj optimize

Full paths for every runtime are in the Quickstart, and the install matrix is in Install & upgrade.

The surfaces

Surface	What it's for	Start here
CLI	Everything TokenJam does, from a terminal.	CLI reference
Python SDK	In-process capture from your own agent: `@watch()` and `patch_*()`.	Python SDK
TypeScript SDK	`@tokenjam/sdk` — spans from a Node or edge agent.	TypeScript SDK
MCP server	TokenJam's own data as tools inside an agent's loop.	MCP server
OTLP ingest	Any OpenTelemetry emitter, no SDK and no patch.	Frameworks
Local REST API	Your telemetry, queryable while `tj serve` runs.	Export & integrate
Website content API	This site's docs, posts, and analyzer catalog as JSON.	API reference

Authentication and keys

There are no API keys to issue, because nothing here is gated. Two different reasons:

The website content API is public. Read-only, unauthenticated, no signup. Do not send an Authorization header.
The local API is yours. tj serve binds to 127.0.0.1 and authenticates with the ingest secret generated on your own machine, which is why there is no key for us to give you. See Configuration.

There is no hosted sandbox either. The equivalent is tj demo, which seeds a throwaway local store so you can explore every command against realistic data without touching your own sessions.

MCP

tj mcp starts a stdio MCP server exposing status, cost, traces, alerts, drift, budget headroom, and the optimize report as tools. A manifest following the Model Context Protocol registry's server.json schema is published at /.well-known/mcp.json.

It declares a package rather than a remote, because TokenJam runs on your machine and there is no hosted MCP endpoint to point at. Worth reading the cost note in the MCP docs before wiring it into a subscription-billed coding agent.

API versioning and deprecation

The content API is versioned in the URL path, and v1 is current. Breaking changes ship as a new version segment (/api/v2/), never in place. Within a version, fields may be added but existing fields are not removed, renamed, or retyped.

When an endpoint is deprecated, you find out four ways:

Deprecation header (RFC 9745) — Set on every response from a deprecated endpoint, carrying the date the deprecation was announced.
Sunset header (RFC 8594) — Set alongside Deprecation, carrying the date the endpoint stops responding.
deprecated: true in the OpenAPI document (OpenAPI 3.1) — Marked on the operation as soon as the deprecation is announced.
A note on the API page and in the changelog — Written explanation of what replaces the endpoint.

The guarantee: a deprecated endpoint keeps responding for at least 90 days after the Deprecation header first appears. Nothing is removed without that notice. The same policy is machine-readable as x-api-lifecycle in the OpenAPI document and as lifecycle in the discovery document.

Machine-readable index

File	Format	What it holds
/openapi.json	OpenAPI 3.1	Every operation of the content API.
/api/v1/index.json	JSON	Discovery: endpoints, auth, lifecycle.
/.well-known/mcp.json	MCP server.json	How to run the MCP server.
/agents.md	Markdown	When to use TokenJam, and how to call it.
/llms.txt	Text	Every page, with its markdown URL.
/llms-full.txt	Text	The whole site as one document.

Source and support

github.com/metabuilder-labs/tokenjam — MIT licensed, PRs welcome
PyPI and npm — published packages
Issues — bugs and feature requests
support@tokenjam.dev — anything else

Reading this as an agent? https://tokenjam.dev/agents.md is the same information written for you, and it is the file to fetch first.