Jobs

Run one action or chain up to eight on your files, get the result by waiting, polling or webhook, and read the receipt.

A job runs steps on files: one action, or a chain where each step works on the last step's result.

One action

Each action has a shortcut, POST /v1/pdf/<action>, which is a one-step job:

curl https://api.fynepdf.com/v1/pdf/ocr \
  -H "Authorization: Bearer $FYNEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id":"file_01jc8x4m2k9q7r3t5vwy6z"}'

A chain of steps

POST /v1/jobs takes the input files and up to eight steps:

curl https://api.fynepdf.com/v1/jobs \
  -H "Authorization: Bearer $FYNEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": ["file_01jc8x4m2k9q7r3t5vwy6z", "file_01jc8x5n7p2s4u6w8y0a1b"],
    "steps": [
      {"action": "merge"},
      {"action": "compress", "params": {"target_size_bytes": 5000000}},
      {"action": "page_numbers", "params": {"position": "bottom-right"}}
    ],
    "wait": 30
  }'

Rules of a chain:

• Most actions take one file; merge and image_to_pdf take all of them.
• A step that makes something other than a PDF (Word, Excel, images in a ZIP) must be the last step.
• GET /v1/actions lists every action with its parameters and price, and each has a page in this menu.

Getting the result

Pick one:

• Wait in the call: wait (0 to 60 seconds). A job that finishes in time answers 200; otherwise 202, and you carry on below. Shortcuts wait 30 seconds unless told otherwise; POST /v1/jobs answers at once unless you set wait.
• Poll: GET /v1/jobs/{id} until status is succeeded, failed or canceled. The Location header of a 202 points there.
• Webhook: give webhook_url and we call it when the job ends. See Webhooks.

A job is queued while it waits for a free slot and running once its first step starts; started_at is set then, so the receipt's time counts work, not waiting.

Results are named after the first input. When the result is the same type, the name says what was done: report.pdf compressed comes back as report-compressed.pdf, so it can be saved next to the original. A different type keeps the plain name (report.docx).

The receipt

Every job has one: each step's status, pages and bytes before and after, time taken, credits, and step details (a compress step says whether it met its target; a redact step says how many matches it removed and that none can still be found).

{
  "receipt": {
    "steps": [
      { "step": 1, "action": "merge", "status": "succeeded", "credits": 1, "pages_after": 22 },
      { "step": 2, "action": "compress", "status": "succeeded", "credits": 1, "bytes_before": 14200000, "bytes_after": 4800000, "target_met": true },
      { "step": 3, "action": "page_numbers", "status": "succeeded", "credits": 1, "pages_after": 22 }
    ],
    "credits": 3,
    "duration_ms": 9100
  }
}

Price it first

POST /v1/jobs/quote takes the same body and answers with the credits it would cost, without running anything.

When things go wrong

• A step that fails is never charged, and a job that fails or is canceled gives back everything it spent.
• POST /v1/jobs/{id}/cancel stops a job before its next step.
• error on a failed job says which step failed and why; see Errors.
• Send an Idempotency-Key header so a retried request never runs twice (Keys and authentication).