API reference - TokenPath

The TokenPath API is a JSON-over-HTTPS REST API. There is no SDK to install. Any HTTP client works.

https://api.tokenpath.ai

Authentication

Small POST /v1/attributions requests support free keyless access. Omit Authorization to use it. Supplied keys retain normal scope checks and billing. GET /health is also public. Send an API key as a Bearer token on protected requests:

Authorization: Bearer tpk_live_...

Create keys at platform.tokenpath.ai. See Authentication for scopes and rotation.

Endpoints

Method	Path	Scope	Description
`POST`	`/v1/attributions`	`attributions:write` when keyed	Link phrases in an answer to their supporting source text. Start here.
`POST`	`/v1/attributions/heatmap`	`attributions:write`	The raw token-by-token attention heatmap.
`POST`	`/v1/generate`	`attributions:write`	Optional demo helper: stream an answer from a TokenPath-selected model.
`GET`	`/v1/me`	`usage:read`	The account that owns the key.
`GET`	`/v1/me/credits`	`usage:read`	Your credit balance.
`GET`	`/v1/me/usage`	`usage:read`	Your billing events.
`GET`	`/health`	none	Liveness check.

Requests and responses are application/json, except /v1/generate, which streams text/event-stream. Large responses are gzip-compressed when your client sends Accept-Encoding: gzip.

Conventions

Offsets. Every character offset is half-open ([start, end)) and counted in the request’s offset_encoding, which defaults to utf-16. See Offsets and encoding.
Strings are never rewritten. Offsets index into the exact document and answer you sent.
Request IDs. Every response has an X-Request-ID header. Include it when you contact support.
Versioning. Endpoints live under /v1/. Breaking changes will ship under a new version prefix.

Limits

The table below describes keyed access. See keyless limits for the smaller input caps and shared budget.

	Limit
`document` on `/v1/attributions`	4,000,000 characters and 1,050,000 tokens
`document` on `/v1/attributions/heatmap`	400,000 characters
`question`, `answer`	10,000 characters each
Attribution rate	120 requests/minute per key, 240 per account
Generation rate	30 requests/minute per key, 60 per account

For higher rate limits, email [email protected].

Errors

Every error uses one envelope:

{
  "error": {
    "code": "missing_scope",
    "message": "API key is missing a required scope.",
    "details": { "missing_scopes": ["attributions:write"] },
    "request_id": "req_..."
  }
}

Branch on code. details appears only when there is extra context. The authentication errors below can come from any authenticated endpoint. Errors lists every code with retry guidance.

Status	Code	Meaning
`401`	`missing_api_key`	No `Authorization` header.
`401`	`invalid_authorization_header`	The header is not in `Bearer <key>` form.
`401`	`invalid_api_key`	The key is malformed or unknown.
`403`	`api_key_inactive`	The key was revoked.
`403`	`account_suspended`	The account is not active.
`403`	`missing_scope`	The key lacks the endpoint’s scope.
`422`	`validation_error`	The request body or query failed validation.

​Authentication

​Endpoints

​Conventions

​Limits

​Errors

Authentication

Endpoints

Conventions

Limits

Errors