# Ask a document

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

Documentation index: https://webcite.co/llms.txt
Canonical page: https://webcite.co/api-docs/ask
API origin: https://api.webcite.co
Authentication: x-api-key header. Keep keys on your server.

## 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

POST /api/v1/ask

5 credits to queue the work. Polling is free.

### curl

```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"
}'
```

### Node.js

```javascript
const response = await fetch("https://api.webcite.co/api/v1/ask", {
  method: "POST",
  headers: {
    "x-api-key": process.env.WEBCITE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "question": "What was revenue in FY2025?",
  "documentText": "Revenue for FY2025 was $12 million.",
  "documentName": "Example annual report"
}),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());
```

### python

```python
import os
import json
import requests

payload = json.loads("{\n  \"question\": \"What was revenue in FY2025?\",\n  \"documentText\": \"Revenue for FY2025 was $12 million.\",\n  \"documentName\": \"Example annual report\"\n}")
response = requests.post(
    "https://api.webcite.co/api/v1/ask",
    headers={"x-api-key": os.environ["WEBCITE_API_KEY"]},
    json=payload,
    timeout=(10, 300),
)
response.raise_for_status()
print(response.json())
```

## Response

HTTP 202 returns an id. Poll GET /api/v1/ask/{id}. Unverified answer values remain null with warnings.

## 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.

## OpenAPI operation

```json
{
  "path": "/api/v1/ask",
  "method": "POST",
  "operation": {
    "description": "Queues an ask job: the document is chunked, top passages are\nretrieved, a derivation is drafted, and every drafted number is checked\nagainst the passages (verbatim match) or recomputed from grounded operands.\nUnverified values return as null, never as claims. Poll GET ask/:id.\n\n**Credits: 5** (retrieval plus a model draft plus verification)",
    "operationId": "ApiV1Controller_ask",
    "parameters": [],
    "requestBody": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateAskDto"
          }
        }
      },
      "required": true
    },
    "responses": {
      "202": {
        "description": "Ask job queued."
      },
      "400": {
        "description": "bad_input or needs_ocr."
      },
      "401": {
        "description": "Unauthorized - API key required"
      },
      "429": {
        "description": "Rate limit exceeded"
      }
    },
    "security": [
      {
        "x-api-key": []
      },
      {
        "bearer": []
      }
    ],
    "summary": "Ask a question over a document",
    "tags": [
      "Public API"
    ]
  },
  "schemas": {
    "CreateAskDto": {
      "properties": {
        "documentName": {
          "description": "Label for diagnostics and evidence.",
          "example": "10-K FY2025",
          "type": "string"
        },
        "documentText": {
          "description": "Document text. v1 accepts text; file ingest with page splits is a later slice.",
          "type": "string"
        },
        "hasTextLayer": {
          "description": "Set false when the caller knows the source is a scan with no text layer.",
          "type": "boolean"
        },
        "question": {
          "description": "The question to answer over the document.",
          "example": "What was net income in FY2025?",
          "type": "string"
        },
        "topK": {
          "default": 8,
          "description": "Retrieved passages fed to the drafter.",
          "type": "number"
        }
      },
      "required": [
        "question",
        "documentText"
      ],
      "type": "object"
    }
  }
}
```