PDFHQ logo

Documents

DocumentationGetting started

Task lifecycle

Start, attach files, process, poll and retrieve document tasks.

Server-side API keys Signed storage uploads

Start → attach → process → poll → download#

  • POST /v1/tasks: set the operation once.
  • POST /v1/tasks/{task_id}/uploads: obtain a signed direct upload ticket; use its completion endpoint to attach the file automatically.
  • POST /v1/tasks/{task_id}/files: alternatively attach separately completed uploads in order.
  • POST /v1/tasks/{task_id}/process: submit immutable options and queue one charged job.
  • GET /v1/tasks/{task_id}: inspect the real execution status.
  • GET /v1/tasks/{task_id}/download-url: receive a short-lived signed output URL when successful.

List tasks with GET /v1/tasks?limit=20&offset=0, optionally filtering by tool. You can discard waiting tasks with DELETE; processing/completed jobs cannot be deleted or cancelled by this endpoint.

Start task response (representative)
{
  "task_id": "uuid",
  "tool": "compress",
  "status": "waiting",
  "upload_ids": [],
  "job_id": null,
  "progress": 0,
  "output_ready": false,
  "links": {
    "self": "/v1/tasks/uuid",
    "files": "/v1/tasks/uuid/files",
    "process": "/v1/tasks/uuid/process"
  }
}

Idempotency#

Processing uses one internal key derived from the task identifier. Resend identical options to recover a lost response without creating another logical charge. Changing settings after submission returns HTTP 409. The legacy direct job API remains supported.

PDFHQ logo

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

© 2026 PDFHQ. All rights reserved.