# Extract text

Use `/extractText` to read a PDF's text by page. The output can feed search indexes, scanned-document workflows, or data extraction from invoices and reports.

## Endpoint

```
POST /extractText
```

## Authentication

Send a valid API key or OAuth token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

See [Authentication](https://pdf-mcp.io/docs/authentication) for details.

---

## Request body

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pdf_base64` | string | Conditional | Base64-encoded PDF file |
| `pdf_url` | string | Conditional | URL to fetch the PDF from |
| `file` | file | Conditional | PDF file upload (multipart only) |
| `pages` | array/string | No | Page numbers to extract (1-indexed) |

**Note:** You must provide exactly one of: `pdf_base64`, `pdf_url`, or `file`.

### Field details

**pdf_base64** (conditional)

A base64-encoded PDF file. Use this when you have the PDF data in memory or need to send it as part of a JSON payload. The encoded string should not include the data URI prefix.

**pdf_url** (conditional)

A publicly accessible URL where the PDF can be fetched. The server will download the PDF from this URL before processing. Supports redirects.

**file** (conditional, multipart only)

Upload a local PDF as multipart form data.

**pages** (optional)

Specify which pages to extract text from:
- **JSON format**: Array of integers `[1, 2, 5]`
- **Multipart format**: Comma-separated string `"1,2,5"`

Page numbers are 1-indexed (first page is 1, not 0). If omitted, text is extracted from all pages.

---

## Request examples

### Base64 PDF in JSON

```bash
# First, encode your PDF to base64
PDF_BASE64=$(base64 -i document.pdf)

curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_base64": "'"$PDF_BASE64"'"
  }'
```

### PDF URL

```bash
curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/documents/report.pdf"
  }'
```

### Selected pages

```bash
curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/documents/report.pdf",
    "pages": [1, 3, 5]
  }'
```

### Multipart file upload

```bash
curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"
```

### File upload with selected pages

```bash
curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "pages=1,2,3"
```

---

## Response

### Success

Returns JSON with extracted text organized by page.

```json
{
  "text": "Full combined text from all extracted pages...",
  "pages": [
    {
      "page": 1,
      "text": "Text content from page 1..."
    },
    {
      "page": 2,
      "text": "Text content from page 2..."
    }
  ],
  "total_pages": 5
}
```

**Response fields:**

| Field | Type | Description |
|-------|------|-------------|
| `text` | string | Combined text from all extracted pages, separated by double newlines |
| `pages` | array | Array of page objects with individual page text |
| `pages[].page` | integer | Page number (1-indexed) |
| `pages[].text` | string | Extracted text from this page |
| `total_pages` | integer | Total number of pages in the PDF |

### Error

```json
{
  "error": "Failed to extract text",
  "message": "Error description"
}
```

**Status codes:**

| Code | Description |
|------|-------------|
| 200 | Success - Text extracted and returned as JSON |
| 401 | Unauthorized - Missing or invalid Authorization header |
| 403 | Forbidden - Invalid API key or OAuth token |
| 500 | Internal Server Error - Text extraction failed |

---

## Extraction behavior

### How it works

The API uses PyPDF to extract text from PDFs. This works best with:

- **Native PDFs**: PDFs created digitally (Word, LaTeX, HTML-to-PDF converters)
- **Text-layer PDFs**: Scanned documents with OCR text layer applied
- **Structured PDFs**: Documents with proper text encoding

### Limitations

Extraction results depend on how the PDF stores its content:

- **Scanned images without OCR**: Pure image scans won't have extractable text
- **Complex layouts**: Multi-column layouts may have text in unexpected order
- **Embedded fonts**: Some custom fonts may not extract properly
- **Encrypted PDFs**: Password-protected PDFs cannot be processed

### Text order

Text is extracted in reading order as determined by the PDF structure. For complex layouts, the order may not match visual reading order. Consider post-processing if precise ordering is required.

---

## Examples

### Invoice data

```bash
curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/invoices/INV-2024-001.pdf"
  }'
```

Process the response to extract invoice numbers, dates, amounts, and line items.

### Search indexing

```bash
curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@legal-contract.pdf"
```

Use the extracted text to build a searchable index of your document library.

### First-page summary

```bash
curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/documents/whitepaper.pdf",
    "pages": [1]
  }'
```

Extract the first page when you need only its title, abstract, or summary.

---

## Implementation notes

### Choose an input method

- Upload a local file with multipart form data
- Use base64 when the PDF is already in memory
- Supply a URL for a PDF that is already hosted online

### Limit processing

- Extract only the pages you need using the `pages` parameter
- For large PDFs, consider extracting in batches
- Cache extracted text to avoid re-processing

### Process the text

- Extracted text may contain extra whitespace - normalize as needed
- Page breaks are indicated by the `pages` array structure
- Use the combined `text` field for full-document search or analysis

### Handle errors

- Validate PDFs before sending (check file extension, magic bytes)
- Handle cases where pages contain no extractable text
- Implement retry logic for URL-based extraction (network failures)

---

## Related endpoints

- [Page count](https://pdf-mcp.io/docs/api-page-count): get the number of pages in a PDF
- [Extract pages](https://pdf-mcp.io/docs/api-extract-pages): create a PDF from selected pages
- [PDF to image](https://pdf-mcp.io/docs/api-pdf-to-image): convert PDF pages to images

## Credit usage

Each request costs **0.01 credits**, regardless of page count.