---
title: "Run a pipeline"
method: POST
path: "/v1/tools/pdf_run_pipeline"
tags: ["Tools"]
---

# Run a pipeline

`POST /v1/tools/pdf_run_pipeline`

## Request

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

Apply 1–10 steps in order and write one new PDF. Step actions: extract, remove, rotate, crop, scale, flatten, labels, watermark, metadata-clear; options as in the matching tools (e.g. {"action":"rotate","options":{"pages":"1","angle":90}}).

Same tool as the MCP server's pdf_run_pipeline. Runs before responding; for long work, POST /v1/jobs instead.

## Request body

- PdfRunPipelineInput
  - `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.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - object
        - `action` 'remove', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - object
        - `action` 'rotate', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `angle` union: Clockwise rotation in degrees.
            - 90
            - 180
            - 270
      - object
        - `action` 'crop', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `margin` number: Points trimmed from each edge.
      - object
        - `action` 'scale', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `factor` number: Scale factor, 0.1–4.
      - object
        - `action` 'flatten', required
        - `options` object: Options as in the matching tool.
      - object
        - `action` 'labels', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `text` string
          - `position` 'top' | 'bottom'
      - object
        - `action` 'watermark', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `text` string, required
      - 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.

## Response `200`

The result. Any new files are written inside the allowed folders.

- NewFile
  - `output` string, required
  - `pages` integer, required
  - `bytes` integer, required

## 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.
- `409`: The output file already exists. superPDF never overwrites; choose a new name.
- `413`: The body is larger than 1 MB.
- `415`: The body is not application/json.
- `422`: Invalid input (errors names each field), a path outside the allowed folders, or a document the tool could not process.
- `429`: Too many tool calls are running and waiting (4 at once, 2 of them LibreOffice conversions; 64 more wait their turn).
- `500`: Unexpected server failure.

---

[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)