AI job lifecycle
Quote → verify source → start an asynchronous AI job → poll validated citations and download structured results.
End-to-end: quote, reserve, process, settle#
AI operations follow the same verified PDF admission as conventional tasks. An active HQTools AI price and an account-scoped quote for quantity 1 are required. Unlike PDF tools, a quoted AI job is submitted to POST /v1/ai/jobs and progresses through a separate durable ledger. PDFHQ reserves HQ credits in the worker BEFORE contacting the provider, and settles only after a result is stored. This feature is disabled by default until production rollout gates are verified.
# 1. Upload and seal your PDF using /v1/documents/uploads
# 2. Inspect prices and create a quote
curl 'https://api.pdfhq.io/v1/ai/billing/prices' -H 'x-api-key: PROJECT_API_KEY'
curl -X POST 'https://api.pdfhq.io/v1/ai/billing/quotes' \
-H 'x-api-key: PROJECT_API_KEY' -H 'Content-Type: application/json' \
-d '{"price_id":"ACTIVE_PRICE_ID","quantity":"1"}'
# 3. Submit one immutable job
curl -X POST 'https://api.pdfhq.io/v1/ai/jobs' \
-H 'x-api-key: PROJECT_API_KEY' -H 'Idempotency-Key: your-stable-request-key-123' \
-H 'Content-Type: application/json' \
-d '{"operation":"pdfhq.ai.chat","upload_id":"UPLOAD_UUID","quote_id":"QUOTE_ID","question":"What is the payment deadline?","allow_ocr":false,"allow_external_ai":true}'
# 4. Poll the result
curl 'https://api.pdfhq.io/v1/ai/jobs/AI_JOB_UUID' -H 'x-api-key: PROJECT_API_KEY'Machine-readable status#
Batch invoice users can open the invoice batch review workspace . The browser orchestrates up to ten independently quoted and idempotent`pdfhq.ai.extract` jobs with HQ credits. There is no invented bulk discount, batch-priced API endpoint, or automatic retry of uncertain provider outcomes. Each row can export verified invoice fields, line items and cited source excerpts for human review.
Queued → reserving → executing → settling → succeeded. Failed jobs release their HQ-credit reservation when the provider is known not to have successfully completed. The state needs_reconciliation means the provider outcome is uncertain; DO NOT automatically resubmit as a new job. A retry with the same idempotency key recovers the same logical job. Use GET /v1/ai/jobs to list jobs and DELETE /v1/ai/jobs/{id} to erase terminal content while preserving noncontent billing receipts.
AI project keys need pdfhq.ai.execute scope and api.enabled entitlement; quotation uses pdfhq.ai.quote. Browser sessions use a CSRF-protected HQ account.
