---
title: "Extract text, pages, metadata, or images from a PDF"
method: POST
path: "/v1/pdf/extract"
tags: ["Files"]
---

# Extract text, pages, metadata, or images from a PDF

`POST /v1/pdf/extract`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/pdf/extract`
- Auth: HTTP bearer

Reads a PDF from an absolute `path` and extracts content according to `mode`:
`text` (full text, default), `pages` (per-page text array), `metadata` (title,
author, page count), or `images` (rendered page PNGs at `image_dpi`, written to
`output_dir`). Optional `page_range` (e.g. `1-5,8`) and `password` for encrypted
documents.

## Request body

- PdfExtractRequest
  - `path` string, required: Absolute path to the PDF.
  - `mode` 'text' | 'pages' | 'metadata' | 'images': Extraction mode. Default `text`.
  - `page_range` string: Page range expression, e.g. `1-5,8,12-`. Optional.
  - `password` string: Decryption password for encrypted PDFs.
  - `image_dpi` integer: DPI for rendered page images. `mode=images` only.
  - `output_dir` string: Absolute output directory for rendered images. `mode=images` only.

## Response `200`

Extracted content (shape varies by `mode`)

- PdfExtractResponse
  - `mode` 'text' | 'pages' | 'metadata' | 'images', required
  - `pageCount` integer, required
  - `text` string: Concatenated text (set on `mode=text`).
  - `pages` object[]: Per-page text (set on `mode=pages`).
    - `pageNumber` integer
    - `text` string
  - `metadata` object: PDF metadata (set on `mode=metadata`).
  - `images` object[]: Rendered page images (set on `mode=images`).
    - `pageNumber` integer
    - `path` string
    - `bytes` integer

## Other responses

- `400`: Invalid request
- `401`: PDF is encrypted and password is missing or wrong
- `404`: Resource not found
- `500`: Load, render, or write failed

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)