TokenJam API

A read-only JSON API over everything published on tokenjam.dev. Public, unauthenticated, and described by an OpenAPI 3.1 document. Built so an agent can read the TokenJam docs without scraping HTML.

Base URL and authentication

Base URL is https://tokenjam.dev. There is no authentication: no API key, no OAuth flow, no signup. Do not send an Authorization header. No application-level rate limit is enforced, though sustained abusive volume may be throttled at the CDN edge.

curl -s https://tokenjam.dev/api/v1/index.json

That discovery document lists every endpoint below, plus the other machine-readable files on this site. If you only remember one URL, remember that one.

JSON endpoints

Operation	Path	Returns
`getApiIndex`	`/api/v1/index.json`	API discovery document
`listBlogPosts`	`/api/v1/posts.json`	List all published blog posts
`getBlogPost`	`/api/v1/posts/{postId}.json`	Get one blog post, including its markdown body
`listDocs`	`/api/v1/docs.json`	List all documentation pages
`getDoc`	`/api/v1/docs/{docId}.json`	Get one documentation page, including its markdown body
`listProducts`	`/api/v1/products.json`	List the TokenJam optimization analyzers
`getProduct`	`/api/v1/products/{productSlug}.json`	Get one analyzer, including its mechanism and confidence tiers
`getOpenApiDocument`	`/openapi.json`	This OpenAPI document

Markdown and text endpoints

Every documentation page and blog post is also served as clean markdown by appending .md to its path. These are the cheapest way to fill a context window, since they carry no navigation, styles, or scripts.

Operation	Path	Returns
`getAgentInstructions`	`/agents.md`	Agent instructions: when to use TokenJam and how to call it
`getLlmsIndex`	`/llms.txt`	llms.txt index of the site
`getLlmsFullText`	`/llms-full.txt`	Full-text dump of the site for LLM ingestion
`getBlogPostMarkdown`	`/blog/{postId}.md`	Get a blog post as plain markdown
`getDocMarkdown`	`/docs/{docId}.md`	Get a documentation page as plain markdown

Example requests

# What exists, and where
curl -s https://tokenjam.dev/api/v1/index.json

# Every published post, newest first
curl -s https://tokenjam.dev/api/v1/posts.json

# One post, with its full markdown body
curl -s https://tokenjam.dev/api/v1/posts/2026-08-05-ai-budget-overruns-forecasting-agent-spend.json

# The docs tree, with section and ordering
curl -s https://tokenjam.dev/api/v1/docs.json

# One analyzer, with mechanism, confidence tiers, and citations
curl -s https://tokenjam.dev/api/v1/products/downsize.json

# The same doc as raw markdown instead of JSON
curl -s https://tokenjam.dev/docs/quickstart.md

Response shape

Collections use a list envelope and are returned in full; there is no pagination. Every item carries three links so you can move between representations without guessing at URLs: url for the HTML page, markdown_url for the markdown, and api_url for the JSON.

{
  "object": "list",
  "resource": "doc",
  "count": 34,
  "data": [
    {
      "object": "doc",
      "id": "quickstart",
      "title": "Quickstart",
      "description": "Peek in 15 seconds with no install…",
      "section": "getting-started",
      "order": 2,
      "url": "https://tokenjam.dev/docs/quickstart",
      "markdown_url": "https://tokenjam.dev/docs/quickstart.md",
      "api_url": "https://tokenjam.dev/api/v1/docs/quickstart.json",
      "updated_at": null
    }
  ]
}

Errors

Unknown paths return a 404. When the site is served by the Node server in server/index.mjs, the body is a JSON error object; the current static CDN deployment returns the same 404 status with the markdown 404 page instead. Both are documented in the OpenAPI spec.

{
  "error": {
    "code": "not_found",
    "message": "No such resource: /api/v1/posts/nope.json",
    "status": 404,
    "hint": "List valid identifiers at https://tokenjam.dev/api/v1/posts.json",
    "documentation_url": "https://tokenjam.dev/api"
  }
}

Versioning and deprecation

The version lives in the 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.

A deprecation is announced four ways at once:

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.

A deprecated endpoint keeps responding for at least 90 days after the Deprecation header first appears. The same policy is machine-readable as x-api-lifecycle in the OpenAPI document and lifecycle in the discovery document.

This is not the TokenJam local API

The TokenJam CLI runs its own REST API on http://127.0.0.1:7391 when you run tj serve. That one reads your private telemetry, requires the ingest secret as a bearer token, and publishes its own OpenAPI document at /api/v1/openapi.json on the local host. See Export & integrate for it. The API on this page only serves public website content.

Related resources

/agents.md — when to use TokenJam and how to call it, written for agents
/openapi.json — the OpenAPI 3.1 document (also at /api/openapi.json)
/llms.txt — index of every page with its markdown URL
/llms-full.txt — the whole site as one text file
/developers — the developer portal: SDKs, CLI, MCP, and this API in one place
/.well-known/mcp.json — MCP server manifest (server.json schema)
MCP server — TokenJam tools inside an agent's own loop
Python SDK and TypeScript SDK

Support

Questions about the API go to support@tokenjam.dev. If an endpoint returns something the spec does not describe, that is a bug worth filing.