Chat with PDF API
Answer PDF questions with revision-bound, page-labeled evidence using approved AI models and mandatory quote acceptance.
Question answering grounded in source PDF#
Use operation pdfhq.ai.chat with question up to 2,000 characters, verified uploads and matching HQTools quote. Single-PDF chat requires quantity 1. Optional multi-document chat supports up to four PDFs when activated after HQTools tariff certification. Seal each PDF first; quote quantity must equal document count. All uploads belong to the same account and API project; together they must total at most 12 MiB. The worker ranks immutable excerpts across sources and rejects unsupported or fabricated citation IDs.
POST https://api.pdfhq.io/v1/ai/jobs
x-api-key: PROJECT_API_KEY
Idempotency-Key: stable-idempotency-key
Content-Type: application/json
{"operation":"pdfhq.ai.chat","upload_id":"UPLOAD_UUID","quote_id":"QUOTE_ID","question":"Which invoices are overdue?","allow_external_ai":true,"allow_ocr":false}Multi-document chat (when available)#
GET /v1/ai/billing/prices advertises multi_document_available, which is disabled by default. For three uploaded PDFs, request an active chat tariff quote with quantity 3. The original upload is Document 1 and additional_upload_ids are Documents 2 and 3.
POST https://api.pdfhq.io/v1/ai/billing/quotes
x-api-key: PROJECT_API_KEY
Content-Type: application/json
{"price_id":"ACTIVE_CHAT_PRICE_ID","quantity":"3"}
POST https://api.pdfhq.io/v1/ai/jobs
x-api-key: PROJECT_API_KEY
Idempotency-Key: stable-multi-source-key
Content-Type: application/json
{"operation":"pdfhq.ai.chat","upload_id":"PDF_1_UUID","additional_upload_ids":["PDF_2_UUID","PDF_3_UUID"],"quote_id":"QUOTE_WITH_QUANTITY_3","question":"Which invoices are overdue?","allow_external_ai":true,"allow_ocr":false}Reusing an idempotency key with a different source set returns 409. Missing or changed source revisions, cross-account uploads or an insufficient quote are rejected before provider inference. Citations identify source document and original PDF page.
Private multi-turn conversations (up to four turns)#
Continue a successful chat without uploading the PDFs again. Each follow-up needs a fresh quote, consent and a new idempotency key. Pass previous_job_id but omit upload_id and additional_upload_ids: the backend inherits exactly the same account- and project-owned, SHA-256-verified PDF sources. A multi-document follow-up requires a quantity-matched quote for all inherited PDFs. Reusing the old quote or changing documents is not a permitted shortcut.
# Review cited results, then quote the NEXT turn
GET https://api.pdfhq.io/v1/ai/jobs/FIRST_CHAT_JOB_UUID/conversation
x-api-key: PROJECT_API_KEY
POST https://api.pdfhq.io/v1/ai/billing/quotes
x-api-key: PROJECT_API_KEY
Content-Type: application/json
{"price_id":"ACTIVE_CHAT_PRICE_ID","quantity":"1"}
POST https://api.pdfhq.io/v1/ai/jobs
x-api-key: PROJECT_API_KEY
Idempotency-Key: unique-follow-up-request-key
Content-Type: application/json
{"operation":"pdfhq.ai.chat","previous_job_id":"FIRST_CHAT_JOB_UUID","quote_id":"NEW_QUOTE_ID","question":"What happens if that payment is late?","allow_external_ai":true,"allow_ocr":false}Only up to three prior turns may be included. Previous answers are untrusted conversational context, not documentary evidence: fresh citations must point to the current verified PDF excerpts. Erased or expired results and foreign API projects cannot be reused. Start a new chat to change the source documents.
Response answers are model-generated and must be checked. The system verifies citation IDs, not the truth of the inference. Missing text, poor scans and limited retrieved context can make a correct answer impossible.
