Skip to content
Documentation/Documents

Ask a document

Queue a question over document text and retrieve a checked answer when processing finishes.

Markdown
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 to queue the work. Polling is free.

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 an id. Poll GET /api/v1/ask/{id}. 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

For 400, check the request fields and source identifiers. For 401, check your API key. For 429, wait for the retry interval. See the errors guide before retrying a billable request.

400
bad_input or needs_ocr.
401
Unauthorized - API key required
429
Rate limit exceeded
Error handling and retry guidance