How to Use the PDF.ai Ask API

Publish date

Sep 16, 2026

AI summary

The Ask API lets you retrieve free‑form answers from already‑parsed PDFs by sending a prompt and the docIds of those PDFs; it costs 3 credits per page across all docIds, requires an API key, and returns a JSON response with success and answer fields. Use it for automated, multi‑document Q&A in your app, while other tools like Web chat, Extract, or Parse are better for single‑file chats, structured data extraction, or generating markdown content. Follow the steps: generate an API key, parse PDFs to obtain docIds, then POST to /v2/ask with the prompt and docIds, and verify the answer against the source PDFs.

Language

People look up an Ask API when the PDF is already in their product and they need a free-form answer in code — not a schema of named fields, and not a one-off chat in the browser.

This page is the question → answer path on the PDF.ai API v2 Ask endpoint. It does not replace the API Hub (keys and plan live there). It does not re-rank the head term pdf api. For the first-request path (key + first Parse), see How to Get Started with the PDF.ai API. For schema-shaped fields in JSON, see How to Use the PDF.ai Extract API. For chat without code, see How to Chat with a PDF.

What Ask is for

After a clean Ask call on PDF.ai API v2, three things should be true:

You already parsed each PDF and kept its docId (Ask does not accept a raw file or url)

You sent a prompt plus one or more of those docIds

The response includes success and an answer string grounded in those documents

Docs: Ask.

Practical rule: Ask answers a free-form question across already-parsed docs. Extract answers "give me these fields." Parse turns the PDF into markdown/contents first. Use Ask when your next step is a chat-style reply in your app, not a database row.

Browser chat vs Ask API

Path	Best when	What you get
Web chat UI	One file, no code	Answers in the browser
API `POST /v2/ask`	Automation, your product, multi-doc Q&A	JSON (`success` · `answer`) with an `X-API-Key`

Credits before you scale questions

From the live Ask and credit usage docs:

Ask credits: 3 credits × total page count across all docIds in the request

Parse first: every docId must come from a prior Parse; Ask does not parse for you

Total for the Ask call: page count sum × 3 (parse credits were already charged on Parse)

Example from the Ask docs:

Document 1: 10 pages, Document 2: 5 pages → Ask uses (10 + 5) × 3 = 45 credits

API plan examples on credit usage:

Free: $0/month for 200 credits/month, no credit card required

Paid examples: $49 / 3,000, $99 / 10,000, $249 / 30,000, $599 / 100,000 credits per month

Generate the key and manage the plan on https://pdf.ai/developer. The docs say the key is shown only once when generated.

Practical rule: sum pages across every docId you pass. Asking two short docs still bills the combined page count × 3.

How to call Ask

1. Have an API key

Open https://pdf.ai/developer, generate a key, store it as a secret. Send it as the X-API-Key header on every call.

2. Parse first and keep each `docId`

Ask only accepts documents that were previously parsed. Run POST https://pdf.ai/api/v2/parse (see How to Get Started with the PDF.ai API), store each returned docId, then pass those IDs into Ask.

3. POST a prompt and `docIds`

Endpoint from the docs: POST https://pdf.ai/api/v2/ask

Content type: application/json.

Required (from Ask):

prompt — the question about the documents

docIds — string array of already-parsed document IDs (one or more)

Example shape (Python), matching the docs sample:

import requests

url = "https://pdf.ai/api/v2/ask"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "prompt": "What is the main topic of this document?",
    "docIds": ["your-document-id-1", "your-document-id-2"]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

A successful response includes success and answer.

4. Check the output before you trust it

Confirm success and that answer matches the question you asked

Spot-check the claim against the source PDF (Ask returns an answer string; it is not a citation table like Extract)

If you get Invalid API key / No API key present, fix the header before you change the prompt

If Ask rejects a docId, parse that file first and retry with the returned id

Practical rule: a fluent answer is still a model reply. Read it against the source pages before you show it to end users as fact.

When Ask is the wrong tool

You only need one chat answer in a browser. Use How to Chat with a PDF. No API key required for that job.

You need named fields / tables as JSON. Use POST https://pdf.ai/api/v2/extract with a schema (How to Use the PDF.ai Extract API).

You only need searchable markdown / contents. Prefer Parse first (How to Get Started with the PDF.ai API).

You wanted a generic “pdf api” category hub. Stay on https://pdf.ai/developer. This page is the Ask how-to, not a replacement hub.

A short action plan

Open https://pdf.ai/developer, create a key, store it once.

Parse each PDF and keep the docIds.

Check credit usage: Ask is 3 × total pages across those docIds.

POST https://pdf.ai/api/v2/ask with prompt + docIds, then verify answer against the source PDFs before you wire production.

Sibling guides: How to Get Started with the PDF.ai API, How to Use the PDF.ai Extract API, PDF OCR API: Run OCR from Your Code, How to Chat with a PDF.

If you want the rest of the PDF workflow after the answer is clean, start at PDF.ai. Use the Ask API when the next step is a free-form reply in your product, not a single upload box.