---
title: "Fill a PDF form"
method: POST
path: "/v1/tools/pdf_fill_form"
tags: ["Tools"]
---

# Fill a PDF form

`POST /v1/tools/pdf_fill_form`

## Request

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

Fill form fields by name (pdf_info lists them): text fields take text, check boxes true or false, choices one of their options. With flatten, the filled values become part of the page and can no longer be edited.

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

## Request body

- PdfFillFormInput
  - `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.

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