Create attributions

curl https://api.tokenpath.ai/v1/attributions \
  -H "Content-Type: application/json" \
  -d '{
    "document": "The Oregon Duck is the mascot of the University of Oregon. It is based on Disney'\''s Donald Duck. The mascot wears a green and yellow costume and a green beanie cap. The costume was redesigned in 2002.",
    "question": "What colors does the Oregon Duck wear?",
    "answer": "The Oregon Duck wears green and yellow."
  }'

import httpx

response = httpx.post(
    "https://api.tokenpath.ai/v1/attributions",
    json={
        "document": (
            "The Oregon Duck is the mascot of the University of Oregon. "
            "It is based on Disney's Donald Duck. "
            "The mascot wears a green and yellow costume and a green beanie cap. "
            "The costume was redesigned in 2002."
        ),
        "question": "What colors does the Oregon Duck wear?",
        "answer": "The Oregon Duck wears green and yellow.",
        "offset_encoding": "utf-32",
    },
    timeout=90.0,
)
response.raise_for_status()
spans = response.json()["spans"]

const response = await fetch("https://api.tokenpath.ai/v1/attributions", {
  method: "POST",
  credentials: "omit",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    document:
      "The Oregon Duck is the mascot of the University of Oregon. " +
      "It is based on Disney's Donald Duck. " +
      "The mascot wears a green and yellow costume and a green beanie cap. " +
      "The costume was redesigned in 2002.",
    question: "What colors does the Oregon Duck wear?",
    answer: "The Oregon Duck wears green and yellow.",
  }),
});
const { spans } = await response.json();

{
  "spans": [
    {
      "answer": { "start": 22, "end": 38, "text": "green and yellow" },
      "source": {
        "start": 115,
        "end": 131,
        "text": "green and yellow",
        "confidence": 0.704467
      }
    }
  ],
  "offset_encoding": "utf-16"
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient prepaid token credits.",
    "details": {
      "available_tokens": 40,
      "required_tokens": 69,
      "billing_mode": "enforced"
    },
    "request_id": "req_..."
  }
}

POST https://api.tokenpath.ai/v1/attributions

Send the document, question, and answer your application used. TokenPath picks out the phrases in the answer worth citing and returns, for each one, the supporting range in the document and a confidence. Omit Authorization for keyless access, or send a Bearer API key with the attributions:write scope for normal billed access. Invalid supplied credentials are rejected.

Keyless access

Small requests work without an account or API key and do not consume credits. The response format and attribution model are the same as for keyed requests.

Input	Keyless limit
`document`	20,000 Unicode characters
`question`	2,000 Unicode characters
`answer`	2,000 Unicode characters
Explicit `spans`	32 ranges

Keyless requests use one model context and do not split long documents into windows. Oversized inputs return 413 anonymous_input_too_large. These character counts are independent of your chosen offset encoding. The initial shared budget is 60 keyless requests per minute per service process, across all callers. It is best-effort access, not a guaranteed per-user allowance. A busy service returns 429 with Retry-After; wait that many seconds before retrying. Limits may change during the experiment. If keyless access is temporarily disabled, requests without a key return 401 missing_api_key. Browser applications can call this endpoint directly with JSON and credentials: "omit". Responses expose Retry-After and X-Request-ID. Browser sandbox network policies still apply. Use a valid API key for larger inputs and your usual billed limits. Generation and raw heatmaps continue to require authentication.

Request body

string

required

The source text the model read. Keyless: 1 to 20,000 Unicode characters. Keyed: 1 to 4,000,000 characters and at most 1,050,000 tokens. Keyed documents that do not fit one model context are split into overlapping windows automatically. See Long documents.

string

required

The question or task the model was given. 1 to 2,000 Unicode characters without a key, or 10,000 with a key.

string

required

The model’s answer, exactly as you display it. 1 to 2,000 Unicode characters without a key, or 10,000 with a key.

string

default:"utf-16"

The unit for every offset in the request and response: utf-16 (JavaScript, Java, C#, Swift), utf-32 (Python, Ruby), or utf-8 (Go, Rust). See Offsets and encoding.

array of [integer, integer]

Optional. Exact answer ranges to attribute instead of letting TokenPath choose. Each range is half-open, in offset_encoding units, and must satisfy 0 <= start < end <= len(answer). Send at least one range, and at most 32 without a key. [] and null are rejected, so omit the field to use automatic selection. See Explicit answer spans.

number

default:"0.001"

Attention below this value is ignored when resolving sources. Range 0 to 1. The default suits almost every use.

Response

array of object

One entry per attributed phrase, in answer order. With explicit spans, one entry per range you sent, in the order you sent them. An empty array means nothing in the answer could be tied to the document.

Show properties

object

The attributed phrase: start and end offsets into your answer, and text, the exact substring they cover.

object | null

The supporting text, or null when TokenPath found none.

start, end: offsets into your document.
text: the exact substring of document they cover.
confidence: link strength from 0 to 1, for ranking and annotation. See Confidence.

string

The unit every start and end is counted in.

curl https://api.tokenpath.ai/v1/attributions \
  -H "Content-Type: application/json" \
  -d '{
    "document": "The Oregon Duck is the mascot of the University of Oregon. It is based on Disney'\''s Donald Duck. The mascot wears a green and yellow costume and a green beanie cap. The costume was redesigned in 2002.",
    "question": "What colors does the Oregon Duck wear?",
    "answer": "The Oregon Duck wears green and yellow."
  }'

import httpx

response = httpx.post(
    "https://api.tokenpath.ai/v1/attributions",
    json={
        "document": (
            "The Oregon Duck is the mascot of the University of Oregon. "
            "It is based on Disney's Donald Duck. "
            "The mascot wears a green and yellow costume and a green beanie cap. "
            "The costume was redesigned in 2002."
        ),
        "question": "What colors does the Oregon Duck wear?",
        "answer": "The Oregon Duck wears green and yellow.",
        "offset_encoding": "utf-32",
    },
    timeout=90.0,
)
response.raise_for_status()
spans = response.json()["spans"]

const response = await fetch("https://api.tokenpath.ai/v1/attributions", {
  method: "POST",
  credentials: "omit",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    document:
      "The Oregon Duck is the mascot of the University of Oregon. " +
      "It is based on Disney's Donald Duck. " +
      "The mascot wears a green and yellow costume and a green beanie cap. " +
      "The costume was redesigned in 2002.",
    question: "What colors does the Oregon Duck wear?",
    answer: "The Oregon Duck wears green and yellow.",
  }),
});
const { spans } = await response.json();

{
  "spans": [
    {
      "answer": { "start": 22, "end": 38, "text": "green and yellow" },
      "source": {
        "start": 115,
        "end": 131,
        "text": "green and yellow",
        "confidence": 0.704467
      }
    }
  ],
  "offset_encoding": "utf-16"
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient prepaid token credits.",
    "details": {
      "available_tokens": 40,
      "required_tokens": 69,
      "billing_mode": "enforced"
    },
    "request_id": "req_..."
  }
}

Explicit spans

To attribute exact ranges, pass spans. Keep each range fact-sized, such as a number, a name, or a date:

{
  "document": "Adobe reported revenue of $5.87 billion in Q2, up 11% year over year.",
  "question": "How did Adobe do in Q2?",
  "answer": "Adobe earned $5.87 billion in revenue, up 11%.",
  "spans": [[13, 26], [42, 45]],
  "offset_encoding": "utf-32"
}

Timeouts

Documents that fit one model context usually return in a few seconds, so a 90-second client timeout is plenty. Keyed windowed requests for long documents run sequentially and return only when every window succeeds. Give those a client timeout of at least 300 seconds.

Errors

In addition to the authentication errors:

Status	Code	Meaning
`413`	`anonymous_input_too_large`	Reduce the input to the keyless limits, or use an API key.
`402`	`insufficient_credits`	Your balance cannot cover the estimated cost. Nothing ran.
`413`	`context_token_limit_exceeded`	The document has more than 1,050,000 tokens.
`413`	`too_many_context_chunks`	The document needs more windows than one request allows.
`413`	`prompt_too_long`	The question and answer leave no room for document text.
`413`	`long_context_attributions_disabled`	Windowing is temporarily off. Documents of 400,000 characters or fewer still work.
`422`	`validation_error`	A field is missing, empty, too long, or out of range, or a span is invalid.
`429`	`rate_limited`, `gpu_saturated`	Too many requests, or capacity is briefly full. Retry after `Retry-After`.
`5xx`	`gpu_backend_*`, `long_context_timeout`, `internal_error`	A server-side failure. Retry with backoff. Nothing is charged.

See Errors for details and a retrying client.

curl https://api.tokenpath.ai/v1/attributions \
  -H "Content-Type: application/json" \
  -d '{
    "document": "The Oregon Duck is the mascot of the University of Oregon. It is based on Disney'\''s Donald Duck. The mascot wears a green and yellow costume and a green beanie cap. The costume was redesigned in 2002.",
    "question": "What colors does the Oregon Duck wear?",
    "answer": "The Oregon Duck wears green and yellow."
  }'

import httpx

response = httpx.post(
    "https://api.tokenpath.ai/v1/attributions",
    json={
        "document": (
            "The Oregon Duck is the mascot of the University of Oregon. "
            "It is based on Disney's Donald Duck. "
            "The mascot wears a green and yellow costume and a green beanie cap. "
            "The costume was redesigned in 2002."
        ),
        "question": "What colors does the Oregon Duck wear?",
        "answer": "The Oregon Duck wears green and yellow.",
        "offset_encoding": "utf-32",
    },
    timeout=90.0,
)
response.raise_for_status()
spans = response.json()["spans"]

const response = await fetch("https://api.tokenpath.ai/v1/attributions", {
  method: "POST",
  credentials: "omit",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    document:
      "The Oregon Duck is the mascot of the University of Oregon. " +
      "It is based on Disney's Donald Duck. " +
      "The mascot wears a green and yellow costume and a green beanie cap. " +
      "The costume was redesigned in 2002.",
    question: "What colors does the Oregon Duck wear?",
    answer: "The Oregon Duck wears green and yellow.",
  }),
});
const { spans } = await response.json();

{
  "spans": [
    {
      "answer": { "start": 22, "end": 38, "text": "green and yellow" },
      "source": {
        "start": 115,
        "end": 131,
        "text": "green and yellow",
        "confidence": 0.704467
      }
    }
  ],
  "offset_encoding": "utf-16"
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient prepaid token credits.",
    "details": {
      "available_tokens": 40,
      "required_tokens": 69,
      "billing_mode": "enforced"
    },
    "request_id": "req_..."
  }
}

Overview

Endpoints

Create attributions

Keyless access

Request body

Response

Explicit spans

Timeouts

Errors

​Keyless access

​Request body

​Response

​Explicit spans

​Timeouts

​Errors

Keyless access

Request body

Response

Explicit spans

Timeouts

Errors