Ask a document

POST/api/v1/askhttps://api.webcite.co

When to use it

This endpoint accepts documentText, not an asset ID. Extract the document first and check its coverage. Set hasTextLayer: false when the supplied source is a scan without usable text. topK defaults to 8 retrieved passages.

Request

5 credits after a completed billable job. Admission and polling are free; failed drafts and empty retrievals do not charge customer credits.

Examples run on your server. Set WEBCITE_API_KEY first. Python examples use the requests package.

curl

curl --fail-with-body -X POST 'https://api.webcite.co/api/v1/ask' \
  -H "x-api-key: $WEBCITE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "question": "What was revenue in FY2025?",
  "documentText": "Revenue for FY2025 was $12 million.",
  "documentName": "Example annual report"
}'

Request body

documentNamestring

Label for diagnostics and evidence.

documentTextstringrequired

Document text. v1 accepts text; file ingest with page splits is a later slice.

hasTextLayerboolean

Set false when the caller knows the source is a scan with no text layer.

questionstringrequired

The question to answer over the document.

topKnumber

Retrieved passages fed to the drafter.

Default: 8

Response

HTTP 202 returns a job id, operation_id, billing_status pending, and usage.credits null. Poll GET /api/v1/ask/{id} for the terminal result and settlement state. Unverified answer values remain null with warnings.

202 response

See the response guidance above. A complete JSON schema is not published for this response.

Errors

A missing model or billing reservation returns 503 before drafting. For 400, check the request fields. For 401, check your API key. For 429, wait for the retry interval. Preserve an unknown settlement for reconciliation instead of submitting a second job.

400: bad_input or needs_ocr.
401: Unauthorized - API key required
429: Rate limit exceeded

Error handling and retry guidance