Docs·API reference

Answers

POST /v1/answers answers one question from one document, with the exact span, Yes/No, or no answer.

HTTP
POST https://platform.xerj.ai/v1/answers
Authorization: Bearer $XERJ_API_KEY
Content-Type: application/json

Request #

Field Type Required Description
document string yes The text to read. Up to 1,000,000 characters.
question string yes One question. Up to 300 characters.
min_confidence number no The bar an answer must clear, with 0 < x < 1. Default 0.5. Raise it for fewer, safer answers; lower it to answer more. See the trade-off.
model string no Default xerj-reader-1, the only model available today.
JSON
{
  "model": "xerj-reader-1",
  "document": "From: Maria Keller <[email protected]>\n…",
  "question": "How much is invoice INV-20931?",
  "min_confidence": 0.5
}

Response #

Field Type Description
id string Unique id of this answer, ans_….
object string Always "answer".
created integer Unix time, in seconds.
model string The model that answered.
answer object The answer. See below.
best_guess object or null The closest candidate when answer.type is "none", else null.
usage object input_tokens, output_tokens, total_tokens.
latency_ms integer Time spent on our side, in milliseconds.

The answer object #

Field Type Description
type string "span", "yes", "no" or "none".
text string or null span: the exact text, document[start:end]. yes/no: "Yes" or "No". none: null.
start integer or null Character offset where the span starts (inclusive). null when there is no span.
end integer or null Character offset where the span ends (exclusive).
confidence number Between 0 and 1. For none, the confidence of the best guess.

Offsets count Unicode code points. In JavaScript, convert them when the text has emoji.

The best_guess object #

{text, start, end, confidence}, present only when answer.type is "none" and a candidate span exists. Show it as “closest passage”. Do not act on it. More.

Examples #

All four use the shipment email from the inbox example. Values are for illustration; id, created and latency_ms are left out.

A span #

curl
curl https://platform.xerj.ai/v1/answers \
  -H "Authorization: Bearer $XERJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"document": "…the shipment email…", "question": "Who will be the account manager from December?"}
EOF
Python
res = client.answers.create(
    document=email,
    question="Who will be the account manager from December?",
)
JavaScript
const res = await client.answers.create({
  document: email,
  question: "Who will be the account manager from December?",
});
JSON
{
  "object": "answer",
  "model": "xerj-reader-1",
  "answer": {"type": "span", "text": "Priya Shah", "start": 711, "end": 721, "confidence": 0.95},
  "best_guess": null,
  "usage": {"input_tokens": 234, "output_tokens": 3, "total_tokens": 237}
}

Yes or No, with a supporting span #

Question: “Do both shipments leave Rotterdam on the same day?”

JSON
{
  "object": "answer",
  "model": "xerj-reader-1",
  "answer": {"type": "no", "text": "No", "start": 496, "end": 507, "confidence": 0.88},
  "best_guess": null,
  "usage": {"input_tokens": 235, "output_tokens": 1, "total_tokens": 236}
}

document[496:507] is 17 November, the day the second shipment leaves.

Yes or No, without a supporting span #

Question: “Are PO-5512 and PO-5513 for the same model?”

JSON
{
  "answer": {"type": "no", "text": "No", "start": null, "end": null, "confidence": 0.83},
  "best_guess": null
}

Not in the document, with a best guess #

Question: “Who is the CEO of Acme Retail?”

JSON
{
  "object": "answer",
  "model": "xerj-reader-1",
  "answer": {"type": "none", "text": null, "start": null, "end": null, "confidence": 0.21},
  "best_guess": {"text": "Tom Baker", "start": 62, "end": 71, "confidence": 0.21},
  "usage": {"input_tokens": 230, "output_tokens": 0, "total_tokens": 230}
}

The email names Tom Baker at Acme Retail, but never says he is the CEO. The answer is none, and the guess is there for display only.

Errors #

Status Code When
400 invalid_json The body is not a JSON object.
400 missing_document document is missing or empty.
400 missing_question question is missing or empty.
400 document_too_long document has more than 1,000,000 characters.
400 question_too_long question has more than 300 characters.
400 invalid_min_confidence min_confidence is not a number with 0 < x < 1.
401 missing_api_key, invalid_api_key, revoked_api_key See errors.
403 access_not_active The account's access is not active yet. See errors.
404 model_not_found The model does not exist or is not available yet.
429 requests_per_minute, tokens_per_day See rate limits.
503 queue_full, queue_timeout Busy. Retry after retry-after seconds.

Every error has the same shape. See errors.