This is the indexable HTML mirror of /llms.txt.
hugepdf.io Agent Operator Instruction Card
You are connected to hugepdf.io, a PDF processing service for agents. From now on, when we say You, we mean You, the agent client.
You are reading this because someone or something pointed you here and wants you to process a PDF.
Welcome. We are at your service.
PUBLIC PREVIEW: processing is currently FREE, up to 100 pages per PDF, subject to per-IP and server capacity limits.
No account or wallet setup is required. Paid access and pricing will be announced separately. Do not send on-chain payments.
The promotion is funded by HugePDF and depends on available server-side processing credits. If those run out, follow section 6.4; no payment is required from you or the user.
Public preview token: hugepdf-free-preview
This token is intentionally public; you may use it without asking the user to supply a token.
After creating a job, POST to its `activation_url` (or `/api/jobs/{job_id}/bypass-pay`) with:
`X-HugePDF-Bypass-Token: hugepdf-free-preview`
`X-HugePDF-Output-Token: {output_token from submission}`
Save the response and follow the monitoring/download instructions below. No payment claim is needed.
---
API
POST /api/jobs
POST /api/jobs/:job_id/bypass-pay
POST /api/jobs/:job_id/outputs/:token/pages/:page/retry
GET /api/jobs/:job_id
GET /api/jobs/:job_id/events
GET /api/jobs/:job_id/preview
GET /api/jobs/:job_id/outputs/:token/results.json
GET /api/jobs/:job_id/outputs/:token/pages/:page
GET /api/jobs/:job_id/outputs/:token/images/:filename
GET /api/jobs/:job_id/outputs/:token/raw/extractor_1/:filename
GET /api/jobs/:job_id/outputs/:token/raw/extractor_2/:filename
GET /receipts/:job_id
For Humans:
GET /jobs/:job_id
---
0. Canonical Flow Summary.
(A) select a PDF -> (B) submit PDF -> (C) activate free processing -> (D) await processing and monitor -> (E) download outputs
1. PDF Submission.
- Submit your PDF to `POST /api/jobs` with either an uploaded PDF or a URL to a PDF.
1.1 Accepted formats.
- `multipart/form-data` with a file field named `file` or `pdf`.
- The uploaded filename must end in `.pdf`
- Public preview limit: 100 pages per PDF. Oversized documents are rejected with HTTP 413, not silently truncated.
- Open the PDF in binary mode and send it as multipart form data.
- `application/json` with `{ "url": "https://...pdf" }`.
- The server downloads the URL and stores it as `source.pdf`.
1.2 Form/JSON fields.
- `prompt` (optional, expected): custom prompt used per-page for processing
- Example: “extract technical data to JSON fields”
- Empty or omitted prompt uses merged-default extraction mode: best-effort merged text from multiple extraction views interpreted by the model.
- A submitted custom prompt is stored as ephemeral job metadata and is purged with the job.
- `model` (optional): HugePDF processing tier alias
- Supported aliases: `hugepdf-fast`, `hugepdf`, `hugepdf-ultra`
- If omitted, uses `hugepdf`
- Current default backend: openai/gpt-5.6-luna via OpenRouter. The backend may change during the preview; keep using the stable `hugepdf` alias. Other aliases may use different models. Model identity is not a privacy or data-retention guarantee.
- Raw provider model names are not part of the API and not configurable.
2. Submission Response.
- Save `job_id`, `output_token`, `status_url`, `preview_url`, `events_url`, and `outputs_manifest_url` from response.
- You will need `job_id` and `output_token` if you want to resume outside your session. Persist it to disk
- If `output_token` is lost, access cannot be recovered for that job; resubmit.
Response:
- job_id : string
- status : string
- pages_total : number
- cost_per_page : string
- cost_per_page_micro_usd : string
- cost_total : string
- cost_total_micro_usd : string
- accepted_tokens : string[]
- chain : string
- payment_address : string
- payment_deadline_seconds : number
- payment_deadline_note : string
- payment_required : false during public preview
- access_mode : "free_preview"
- public_preview_enabled : boolean
- max_pages : number
- activation_url : string
- activation_token : string (public preview credential)
- status_url : string
- preview_url : string
- events_url : string
- output_token : string
- input_prompt : string
- output_token_recovery : string
- output_token_note : string
- outputs_manifest_url : string
- created_at : unix timestamp
- quoted_at : unix timestamp
- paid_at : unix timestamp or null
- started_at : unix timestamp or null
- completed_at : unix timestamp or null
- created_to_paid_seconds : number or null
- paid_to_completed_seconds : number or null
- processing_seconds : number or null
2.1 Result Preview.
- Optional. The user/operator may want to inspect sample quality before activating full processing.
- It must be explicitly requested; don’t assume.
- Request a preview and show a concise quality summary.
- `GET /api/jobs/{job_id}/preview?token={output_token}` returns a truncated first-page extraction sample for quality review.
- Preview lets the agent inspect first-page extraction quality before activating free processing.
- Assess quality and output your assessment. Don’t paste the full preview blob unless the user asks.
3. Free Preview Activation.
- After submission, POST `/api/jobs/{job_id}/bypass-pay` with headers `X-HugePDF-Bypass-Token: hugepdf-free-preview` and `X-HugePDF-Output-Token: {output_token}`. No body is required. The job-specific output token stays private; the preview token alone grants no access to results.
- Example (use the job_id you received):
```
curl --fail-with-body -X POST "https://hugepdf.io/api/jobs/JOB_ID/bypass-pay" \
-H "X-HugePDF-Bypass-Token: hugepdf-free-preview" \
-H "X-HugePDF-Output-Token: OUTPUT_TOKEN"
```
- Activate within 600 seconds of submission. `payment_deadline_seconds` is the legacy field name for this activation window; no money is due.
- Unactivated `awaiting_payment` jobs expire. If the server returns 404, resubmit the PDF and activate the new job.
- New public preview jobs have zero cost and no payment address. Do not install a wallet or call `payment-claims`.
- If the operator separately provides a private bypass token, it can be used with the same endpoint. Unlike the public preview token, private tokens are secrets: do not print, log, or include them in URLs.
4. Activation Response.
- Successful activation returns `ok`, `job_id`, `status`, `paid_amount`, `paid_token`, and `outputs_manifest_url`.
- `paid_amount` is zero for new free preview jobs; `paid_token` is `BYPASS`. The legacy status `paid` means queued for processing, not that money was charged.
- Repeating activation does not restart a paid, processing, or terminal job. If a response is lost, check job status and retry activation only while it is `awaiting_payment`.
- HTTP 403 means a token is missing/invalid, the job is not a free preview job, or the preview is paused; consult this instruction card again. HTTP 429 means wait as instructed. HTTP 503 means the service is unavailable; do not attempt payment.
- The free preview does not create an on-chain payment receipt. Historical payment receipts remain available at their existing URLs.
- Paid access and the updated payment/refund instructions will be published separately. For an earlier unmatched payment, contact hello@hugepdf.io for review.
5. Monitoring a Job.
- Observe progress by either polling or SSE stream until it reaches a terminal state.
- Once you are monitoring, inform users/watchers of your output that the job can be monitored externally in the browser at https://hugepdf.io/jobs/{job_id} -- this is intended for visual browser feedback, dashboards, and/or human consumption.
5.1 Status Lifecycle.
- `awaiting_payment`: job created, free preview activation not yet completed.
- `paid`: free processing activated, job is queued but not yet picked up by a worker.
- `processing`: worker is processing pages.
- `complete`: all pages processed successfully.
- `partial_error`: processing finished; one or more pages failed with retriable page-level errors.
- `failed`: job failed or retries were exhausted without successful completion.
- `rejected_payment`: payment claim was rejected; do not continue processing this job.
- `refunded`: terminal if returned by the API.
- Treat `complete`, `partial_error`, `failed`, `rejected_payment`, `refunded` as terminal states.
- A job with `paid` status but not yet picked up by a worker includes `queue_position` from `GET /api/jobs/{job_id}?token={output_token}`.
- `queue_position` is 1-based.
- `queue_position` is `null` for all statuses except `paid`
- Surface `status`, `pages_processed`, `pages_total`, and `queue_position` to the user/operator for observability.
5.2 Capacity and Submission Backpressure
- The server reports capacity at submission time with `POST /api/jobs` -> HTTP 429
- Treat the submission as not accepted. Do not monitor it. Do not attempt payment.
- Respect the Retry-After header and/or retry_after_seconds.
- Surface the message to the user/operator.
Capacity response:
- error : string
- active_jobs : number
- max_active_jobs : number
- queued_jobs : number
- max_queued_jobs : number
- retry_after_seconds : number
- Too many jobs per IP response:
- error : string
- pending_jobs : number
- max_pending_per_ip : number
- retry_after_seconds : number
5.1 Polling.
- Poll `GET /api/jobs/{job_id}?token={output_token}`.
- Write a small polling script or alternatively perform in-session agent polling based on your target workflow.
- Poll every 2 seconds or slower.
- Use exactly one polling loop per job.
- Always close each HTTP response body, including error/404/409 responses.
- Use one-shot requests with `Connection: close`, or explicitly close the response body after reading it.
- Back off on transport errors, for example 2s, 4s, 8s, 16s, up to 30s.
- Stop and report the issue after 5 consecutive transport errors.
- Stop polling when the status is one of `complete`, `partial_error`, `failed`, `rejected_payment`, `refunded`.
5.2 SSE.
- Open one stream: `GET /api/jobs/{job_id}/events?token={output_token}`
- Keep exactly one SSE stream open per job.
- It may emit `progress` events for worker activity.
- It may emit `page_ready` events with per-page artifact URLs
- It emits `keepalive` comments while idle.
- Close the stream when a terminal status is seen.
- When a `page_ready` event arrives, fetch the provided `page_result_url` or fetch `GET /api/jobs/{job_id}/outputs/{output_token}/pages/{page_number}
6. Consuming Results.
- The status endpoint tells you whether the job finished and whether it finished cleanly; the outputs manifest tells you exactly which artifacts exist and where to download them.
- Call `GET /api/jobs/{job_id}/?token={output_token} to confirm the final `status`, inspect `error_message`, and read `outputs_manifest_url`.
- The outputs manifest is queryable before terminal status; it reflects the artifacts available right now.
- If the `results_url` is `null`, the combined `results.json` file is not available yet.
- If you do not need incremental page consumption, wait for `complete` or `partial_error` and download `results.json` once instead of fetching every page individually.
- If status is `partial_error`, download available outputs and inspect the page results for `error`, `retriable`, `retry_count`, and `retry_exhausted`.
- Be polite: Limit output downloads to 1-4 concurrent requests per job.
Outputs manifest response:
- job_id
- status
- pages_processed
- pages_total
- processing_mode
- model
- download_base_url
- source_pdf_url
- results_url
- extractor_1_pages
- extractor_2_pages
- vision_pages
- llm_result_pages
Download options:
- Final combined results: `GET /api/jobs/{job_id}/outputs/{output_token}/results.json`
- Single page result: `GET /api/jobs/{job_id}/outputs/{output_token}/pages/{page_number}`
- extractor_1 raw text: URLs from `extractor_1_pages`
- extractor_2 raw text: URLs from `extractor_2_pages`
- Vision images: URLs from `vision_pages`
6.1 Consuming Incrementally.
- HugePDF communicates incremental progress: Use it to consume page results as they are ready.
- The SSE stream emits `page_ready` events with per-page artifact URLs.
- When a `page_ready` event arrives, fetch the provided `page_result_url` or other artifact URLs from that event.
- If polling, refresh the outputs manifest and fetch only pages listed in `llm_result_pages`.
- Do not infer that a specific page is ready from `pages_processed` alone. Do not probe future pages.
- If you lose the SSE stream, reconnect and refresh `outputs_manifest_url` to recover the current set of downloadable artifacts.
6.2 Resuming after disconnection.
- Call `GET /api/jobs/{job_id}/?token={output_token} and check `status`, `pages_processed`, `pages_total`, `queue_position`, `error_message`, and `outputs_manifest_url`.
- If `status` is `paid` or `processing` reconnect to `GET /api/jobs/{job_id}/events?token={output_token} or continue polling status.
- Refresh `outputs_manifest_url` and fetch only pages listed in `llm_result_pages` or announced by `page_ready` events.
6.3 Recovery and Per-Page Retry.
- When a page fails its LLM call with a retriable error, the page result includes `retriable: true` and an `error` field.
- Jobs continue processing remaining pages even if one page fails.
- If any retriable page failures remain, the job terminates with `status: partial_error` instead of `complete`
- Retry only pages with `retriable: true`
- Retry failed pages: `POST /api/jobs/{job_id}/outputs/{token}/pages/{page_number}/retry`.
- A retry re-runs LLM processing with the same prompt; raw extraction files are reused.
- Retry is free of cost.
- Each accepted `retry` increments the page’s `retry_count`.
- If no more retriable pages remain, status stays `partial_error`.
- You cannot retry unless the job is in `partial_error` status; API returns 409.
- You cannot retry a page that is not in the results yet; API returns 404.
- You cannot retry a page that is not retriable; API returns 409.
- If the third accepted retry still produces an error, the page is marked `retry_exhausted: true` and the job status becomes `failed`.
- If retries are exhausted, stop retrying and report `error_message`; contact HugePDF for refund review if applicable.
6.4 Promotion Credits and Provider Limits.
- HugePDF pays the upstream model provider during the promotion. An upstream HTTP 402 or provider usage-limit error concerns HugePDF's account, not yours. Do not ask the user to buy credits, supply an API key, create a wallet, or send payment.
- Credit failures are recorded as page errors without automatic retries for those pages. The page `error` may say `LLM request failed (http_error): upstream returned HTTP 402.` or `LLM provider usage limit exceeded. Please try again later.` The `retriable` flag is absent for these failures; do not call the page-retry endpoint for them.
- Remaining pages are still attempted. Once processing finishes, the job is `failed` if only non-retriable errors remain, or `partial_error` if other pages have retriable errors. Neither status means all output is unusable: inspect the manifest and download available successful page results and raw extraction files before expiry. Do not present errored pages as successful output.
- Stop polling at the terminal state. Explain that HugePDF's promotional processing is currently unavailable because of an upstream credit or usage limit. Do not enter a retry/resubmission loop or switch processing tiers to bypass it. Contact hello@hugepdf.io or try a new job after the operator confirms availability; failed jobs do not resume automatically after a top-up.
- The server does not automatically pause new submissions when upstream credits run out; a successful submission or activation is not a guarantee that processing credits remain. Upstream HTTP 402 is recorded in page results, not returned as a request for payment from the client.
7. Storing Data and Expiry.
- Download needed artifacts from manifest URLs to disk.
- Job data and extracted artifacts are ephemeral and purged automatically.
- Current deployment retention is approximately 30 minutes once a job reaches terminal state.
8. Inspecting Results and Completion.
- Return concise summary plus file paths or links to artifacts, not full blobs.
- Do not read full blobs into context--sample or summarize if inspection is needed.
---
For FAQ and extra context, see: https://hugepdf.io/faq
---
hugepdf.io Agent Operator Instruction Card