PDFHQ logo

Documents

DocumentationDocuments & intelligence

Plain-English PDF page editing API

Preview bounded, deterministic page edits against a verified PDF, review the exact output sequence, and approve a separately HQTools-metered task.

Server-side API keys Signed storage uploads

Preview before billing or modifying a PDF#

Upload and seal a PDF using POST /v1/documents/uploads. Then call POST /v1/ai/edit-plans/preview with an owned upload_id and an explicit page instruction. The preview parses deterministic commands; it does not call an LLM or spend HQ credits. Supported actions are clockwise/counterclockwise rotation, delete, keep, duplicate, move, reverse and reorder of pages. Unknown instructions are rejected instead of guessed. Original documents remain unchanged.

cURL
POST https://api.pdfhq.io/v1/ai/edit-plans/preview
x-api-key: PROJECT_API_KEY
Content-Type: application/json

{"upload_id":"SEALED_UPLOAD_UUID","instruction":"Delete page 3; rotate page 1 clockwise"}

# Response includes tool="organize", options.pages, exact input/output page mapping,
# source_revision, approval_token and approval_expires_at (15 minutes).

Optional paid, provider-generated page proposals#

For requests beyond the strict deterministic phrasing, an operator-certified HQTools tariff may enable operation pdfhq.ai.edit_plan. This is disabled by default. The AI model returns only a small array of proposed page commands, never arbitrary processing options or edited PDF bytes. Each command must pass the deterministic parser and each model claim must have citations. A model suggestion is NOT approval to modify the document.

cURL
# Discover only activated HQTools tariffs for pdfhq.ai.edit_plan
GET https://api.pdfhq.io/v1/ai/billing/prices
POST https://api.pdfhq.io/v1/ai/billing/quotes
{"price_id":"CERTIFIED_AI_EDIT_PLAN_PRICE_ID","quantity":"1"}

# Only AFTER explicit approval of the HQ-credit quote and excerpt sharing:
POST https://api.pdfhq.io/v1/ai/jobs
Idempotency-Key: STABLE_RANDOM_IDEMPOTENCY_KEY
{"operation":"pdfhq.ai.edit_plan","upload_id":"SEALED_UPLOAD_UUID",
 "quote_id":"AI_QUOTE_ID","question":"Rotate the appendix page clockwise",
 "allow_external_ai":true,"allow_ocr":false}

GET https://api.pdfhq.io/v1/ai/jobs/AI_JOB_UUID
# Upon success, validate the proposed commands against the ORIGINAL sealed PDF:
POST https://api.pdfhq.io/v1/ai/edit-plans/from-job
{"job_id":"AI_JOB_UUID"}
# Returns exact page map and 15-minute user-review token, NOT a paid editing job.

AI suggestions consume a separate HQ credits charge. The user must then inspect the page map and obtain a second HQTools document-task price to apply the changes. AI model results cannot bypass approval or rewrite page content. Signed/form PDFs and changed or expired source revisions are refused.

Get an HQTools quote and explicitly approve the exact plan#

Create POST /v1/tasks with tool organize, then attach the same verified upload using POST /v1/tasks/TASK_ID/files. GET /v1/tasks/TASK_ID/quote estimates HQ Credits using the current HQTools tariff. Only after the customer reviews the page list and the price, call POST /v1/tasks/TASK_ID/process with both options.pages from preview and its signed approval_token.

cURL
POST https://api.pdfhq.io/v1/tasks
{"tool":"organize"}

POST https://api.pdfhq.io/v1/tasks/TASK_ID/files
{"upload_id":"SEALED_UPLOAD_UUID"}

GET https://api.pdfhq.io/v1/tasks/TASK_ID/quote

POST https://api.pdfhq.io/v1/tasks/TASK_ID/process
{"options":{"pages":[{"source":1,"rotation":90},{"source":2,"rotation":0}]},
 "approval_token":"SIGNED_PREVIEW_APPROVAL"}

GET https://api.pdfhq.io/v1/tasks/TASK_ID
GET https://api.pdfhq.io/v1/tasks/TASK_ID/download-url

Approval is scoped to account, API project, PDF SHA-256, upload ID, page options and short expiry. Changing the document or page list invalidates this token. Standard task clients without preview tokens continue to work. Signed PDFs and form PDFs are rejected by this editor. It cannot rewrite existing text, hide content securely or place cryptographic signatures.

Open the page-edit review interface →
PDFHQ logo

PDF tools and document intelligence. Prepare, understand and work with your documents.

© 2026 PDFHQ. All rights reserved.