---
title: "Run a tool in the background"
method: POST
path: "/v1/jobs"
tags: ["Jobs"]
---

# Run a tool in the background

`POST /v1/jobs`

## Request

- Base URL: `http://127.0.0.1:7341`
- URL: `http://127.0.0.1:7341/v1/jobs`
- Auth: HTTP bearer

Queues a tool call and returns at once with the job. Jobs run one at a time. Poll GET /v1/jobs/{id}, or pass callback_url to receive a signed event when it finishes. Failed callback deliveries are retried up to 5 times with exponential backoff (1, 2, 4 and 8 seconds).

## Request body

- union: A tool call to run in the background.
  - object
    - `tool` 'pdf_list_files', required
    - `input` PdfListFilesInput, required
      - `folder` string: Folder inside an allowed folder. Omit for the first allowed folder.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_info', required
    - `input` PdfInfoInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_read_text', required
    - `input` PdfReadTextInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `max_chars` integer
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_extract_structure', required
    - `input` PdfExtractStructureInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `format` 'markdown' | 'html' | 'json'
      - `max_chars` integer
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_merge', required
    - `input` PdfMergeInput, required
      - `inputs` string[], required: PDF paths in the order to combine.
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_extract_pages', required
    - `input` PdfExtractPagesInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string, required: Page numbers or ranges, such as "1, 3-5".
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_remove_pages', required
    - `input` PdfRemovePagesInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string, required: Page numbers or ranges, such as "1, 3-5".
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_rotate_pages', required
    - `input` PdfRotatePagesInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `angle` union: Clockwise rotation in degrees.
        - 90
        - 180
        - 270
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_add_page_labels', required
    - `input` PdfAddPageLabelsInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `text` string
      - `position` 'top' | 'bottom': Where on the page the label goes.
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_add_watermark', required
    - `input` PdfAddWatermarkInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `text` string, required
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_split', required
    - `input` PdfSplitInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `mode` 'ranges' | 'pages'
      - `output_folder` string, required: Folder for the new files, inside an allowed folder; created if missing.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_from_office', required
    - `input` PdfFromOfficeInput, required
      - `input` string, required: Path to the Office file inside an allowed folder (absolute, or relative to the first allowed folder).
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_remove_metadata', required
    - `input` PdfRemoveMetadataInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_repair', required
    - `input` PdfRepairInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_protect', required
    - `input` PdfProtectInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `password` string, required
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_unlock', required
    - `input` PdfUnlockInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `password` string
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_run_pipeline', required
    - `input` PdfRunPipelineInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `steps` PipelineStep[], required: Steps run in order, such as [{"action":"rotate","options":{"pages":"1","angle":90}}].
        - union
          - object
            - `action` 'extract', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'remove', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'rotate', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'crop', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'scale', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'flatten', required
            - `options` object: Options as in the matching tool.
          - object
            - `action` 'labels', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'watermark', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'metadata-clear', required
            - `options` object: Options as in the matching tool.
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_run_batch', required
    - `input` PdfRunBatchInput, required
      - `inputs` string[], required: PDF paths to process.
      - `steps` PipelineStep[], required: Steps run in order, such as [{"action":"rotate","options":{"pages":"1","angle":90}}].
        - union
          - object
            - `action` 'extract', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'remove', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'rotate', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'crop', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'scale', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'flatten', required
            - `options` object: Options as in the matching tool.
          - object
            - `action` 'labels', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'watermark', required
            - `options` object: Options as in the matching tool.
              - …
          - object
            - `action` 'metadata-clear', required
            - `options` object: Options as in the matching tool.
      - `output_folder` string, required: Folder for the new files, inside an allowed folder; created if missing.
      - `suffix` string: Added to each output file name.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_to_docx', required
    - `input` PdfToDocxInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `output` string, required: Path for the new Word document (ending in .docx), inside an allowed folder. Must not exist yet.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_extract_tables', required
    - `input` PdfExtractTablesInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `format` 'xlsx' | 'csv' | 'json' | 'markdown'
      - `output` string, required: Path for the new file, ending in .xlsx, .csv, .json or .md to match the format, inside an allowed folder. Must not exist yet.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_fill_form', required
    - `input` PdfFillFormInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `values` object, required: Field name → value, such as {"Name": "Ada Lovelace", "Agree": true}.
      - `flatten` boolean: Make the filled values part of the page (no longer editable).
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_add_text', required
    - `input` PdfAddTextInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `text` string, required
      - `x` number: Points from the left edge.
      - `y` number: Points from the bottom edge.
      - `size` number: Font size in points.
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_flatten', required
    - `input` PdfFlattenInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_resize_pages', required
    - `input` PdfResizePagesInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `mode` 'crop' | 'scale', required
      - `margin` number: Points trimmed from each edge (crop).
      - `factor` number: Scale factor (scale).
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_from_images', required
    - `input` PdfFromImagesInput, required
      - `inputs` string[], required
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_from_markdown', required
    - `input` PdfFromMarkdownInput, required
      - `input` string, required: Path to a Markdown file (.md) inside an allowed folder.
      - `page_size` 'A4' | 'Letter'
      - `title` string
      - `output` string, required: Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_to_pptx', required
    - `input` PdfToPptxInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - `output` string, required: Path for the new PowerPoint file (ending in .pptx), inside an allowed folder. Must not exist yet.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_to_epub', required
    - `input` PdfToEpubInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `title` string
      - `author` string
      - `language` string: Language tag, such as en or pt-BR.
      - `split` 'headings' | 'pages'
      - `output` string, required: Path for the new e-book (ending in .epub), inside an allowed folder. Must not exist yet.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_compare', required
    - `input` PdfCompareInput, required
      - `before` string, required: Path to the earlier PDF inside an allowed folder.
      - `after` string, required: Path to the revised PDF inside an allowed folder.
      - `max_chars` integer: Most characters of marked text returned per page.
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.
  - object
    - `tool` 'pdf_outline', required
    - `input` PdfOutlineInput, required
      - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
      - `format` 'markdown' | 'json'
    - `callback_url` string: Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>.

## Response `202`

Queued.

- Job
  - `id` string, required
  - `tool` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required
  - `progress` object, nullable, required: Latest progress from tools that report it (merge, split, pipelines, batches).
    - `progress` number, required
    - `total` number, required
    - `message` string
  - `created_at` string, required: ISO 8601 time.
  - `started_at` string, nullable, required: ISO 8601 time.
  - `finished_at` string, nullable, required: ISO 8601 time.
  - `result` unknown
  - `error` Problem: RFC 9457 Problem Details.
    - `type` string, required: Stable problem type URI: urn:superpdf:problem:<code>.
    - `title` string, required
    - `status` integer, required
    - `detail` string, required: What went wrong and how to fix it.
    - `instance` string, required: URN for this problem occurrence.
    - `code` 'bad_request' | 'unauthorized' | 'forbidden' | 'not_found' | 'method_not_allowed' | 'conflict' | 'payload_too_large' | 'unsupported_media_type' | 'validation' | 'operation_failed' | 'too_many_jobs' | 'busy' | 'internal', required
    - `request_id` string, required
    - `errors` object[]: The fields to fix, for validation and conflict problems.
      - `field` string, required
      - `message` string, required
  - `callback` object
    - `url` string, required
    - `status` 'pending' | 'delivering' | 'delivered' | 'failed', required
    - `attempts` integer, required
    - `last_status` integer, nullable, required: HTTP status of the last attempt; null when the receiver could not be reached.

## Other responses

- `400`: The body is not valid JSON.
- `401`: The bearer token is missing or wrong.
- `403`: The Host or Origin header is not allowed.
- `413`: The body is larger than 1 MB.
- `415`: The body is not application/json.
- `422`: Invalid input, or a callback_url that is not allowed.
- `429`: Too many jobs are waiting.

---

[API](https://skmtc.dev/superpdf/apis/superpdf-local-api.md) · [All operations](https://skmtc.dev/superpdf/apis/superpdf-local-api/llms.txt) · [OpenAPI document](https://skmtc.dev/superpdf/apis/superpdf-local-api/revisions/53f71d44b156?raw)