Name: PDF to Text API: Extract Text and Markdown from PDFs
Brand: compasslab-1
SKU: api-compasslab-1-pdf-to-text
Availability: InStock
Author: API Market

WPTOOLS

# PDF to Text API

## Overview

The PDF to Text API extracts the text layer of a PDF and returns it in the form your code or your language model needs. It has 1 endpoint. You either upload the PDF as a multipart `file` or pass its public URL as `file_url`, optionally choose the pages to read (`1-5,8` or `10-`), and pick one of three output formats: `text` returns one plain string, `markdown` returns Markdown with the title, section headings, paragraphs and bullet lists, with hyphenated line breaks joined back together, and `pages` returns one entry per page with its own text and word count. Every answer also carries the total page count, the pages actually read, the document metadata (title, author, subject, creator, producer, created and modified dates), the detected language, the total word count and the list of scanned pages that have no text layer.

It is built for teams feeding papers, reports, manuals and contracts into RAG and AI pipelines, search indexing and archiving jobs, and document workflows that need to know which pages are scans before sending them to an OCR service. The response is one JSON object. Only the field that matches your `format` is filled (`text`, `markdown` or `pages`) and the other two are `null`. Dates are ISO 8601, the language is an ISO 639-1 code, and `truncated` tells you when not every selected page was read. The API does not do OCR: scanned pages are listed in `scanned_pages` with empty text instead of returning unreadable output.

## Features

*   **1 endpoint**: `POST /v1/pdf/text` extracts text from one PDF per call.
*   **Two ways to send a PDF**: A multipart upload in the `file` field, or a public `http` or `https` URL in `file_url` (as a form field or in a JSON body).
*   **Three output formats**: Plain text, Markdown, or page by page with a word count and a text-layer flag per page.
*   **Page selection**: Read only the pages you need with `pages`, for example `1-5,8` or `10-`.
*   **Document metadata**: Title, author, subject, creator, producer, created and modified dates, plus the detected language.
*   **Scan detection**: Pages with no text layer are listed in `scanned_pages`. There is no OCR, so their text is empty.
*   **Clear errors**: Password-protected files return `422 encrypted`, a URL that does not serve a PDF returns `422 not_pdf` and a broken file returns `422 corrupt_pdf`. PDFs that only restrict printing or copying are read normally.
*   **Size limits**: Up to 15 MB per file and up to 200 pages per call (50 by default). Larger files are rejected with `413` before any parsing.
*   **Rate limit**: 1 request per second on FREE, 3 on PRO, 5 on ULTRA and 10 on MEGA.

## Use Cases

*   **RAG and AI pipelines**: Turn papers, reports, manuals and contracts into Markdown that a model can chunk and embed.
*   **Search indexing**: Pull plain text and metadata out of PDFs to index them in a search engine.
*   **Archiving**: Store the text, page count, author and dates alongside each archived document.
*   **OCR pre-check**: Find out which pages are scans so only those pages go to an OCR service.
*   **Long documents**: Extract just the chapter or page range you need from a large report.
*   **Per-page processing**: Use `format=pages` to cite, split or review a document page by page.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/compasslab-1/pdf-to-text
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Extract text from a PDF

Reads a PDF sent as an upload or a URL and returns its text as plain text, Markdown or one entry per page, with the page count, the pages read, the document metadata, the detected language, the word count and the scanned pages. Send the request as `multipart/form-data`. When you only have a URL, you can also send the same fields as a JSON body with `Content-Type: application/json`, in which case `file_url` is required.

**Method:** `POST`

**Endpoint:** `/v1/pdf/text`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `file` | form | The PDF file to read. Send either `file` or `file_url`. | file (binary) | One of `file` or `file_url` | - | 15 MB |
| `file_url` | form | Public `http` or `https` URL of the PDF, instead of `file`. Can also be sent in a JSON body. | string | One of `file` or `file_url` | - | 2,048 characters |
| `pages` | form | Pages to read, for example `1-5,8` or `10-`. | string | No | All pages | 200 characters |
| `format` | form | Output format: `text` (one string), `markdown` (Markdown) or `pages` (one entry per page). | string | No | `text` | - |
| `max_pages` | form | Read at most this many of the selected pages. Minimum 1. | integer | No | `50` | 200 |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/compasslab-1/pdf-to-text/v1/pdf/text" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -F "file_url=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" \
  -F "format=markdown"
```

To upload a local file instead, replace the `file_url` field with `-F "file=@document.pdf"`.

**Example Response (200 OK):**

```json
{
  "page_count": 1,
  "pages_processed": [
    1
  ],
  "metadata": {
    "title": null,
    "author": "Evangelos Vlachogiannis",
    "subject": null,
    "creator": "Writer",
    "producer": "OpenOffice.org 2.1",
    "created": "2007-02-23T17:56:37+02:00",
    "modified": null
  },
  "language": null,
  "word_count": 3,
  "format": "markdown",
  "text": null,
  "markdown": "Dummy PDF file",
  "pages": null,
  "scanned_pages": [],
  "truncated": false,
  "encrypted": false
}
```

With `format=pages`, `pages` is an array of objects with `page` (1-based page number), `text`, `word_count` and `has_text_layer` (`false` for scanned pages). `encrypted: true` means the PDF is encrypted without a user password, for example print-protected, and was still read. `language` is `null` when it cannot be detected from the text, as with the very short sample above.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The PDF was read. Check `scanned_pages` for pages with no text layer and `truncated` for pages that were selected but not read. |
| 400 | Bad Request | The request was invalid. The body has an `error` code and a readable `detail` that says what to fix. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path is wrong. Check that you are calling `/v1/pdf/text` under the base URL. |
| 413 | Payload Too Large | The PDF is larger than 15 MB. It is rejected before any parsing. |
| 422 | Unprocessable Entity | The file could not be read as a PDF: `not_pdf` (for example a URL that serves HTML), `encrypted` (password-protected) or `corrupt_pdf` (a broken file). |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 503 | Service Unavailable | The service is temporarily overloaded. Retry after a short delay. |

## Rate Limits

Each plan has its own per-second limit: FREE allows 1 request per second, PRO 3, ULTRA 5 and MEGA 10. The plans include 50, 2,000, 10,000 and 50,000 calls respectively, and each PDF you send counts as one call. The FREE plan stops at its 50 calls, while the paid plans keep working past their included calls and bill the extra calls. Requests above the per-second limit, or on the FREE plan after its calls are used up, return `429 Too Many Requests`. Back off before retrying and honour any `Retry-After` header. Large PDFs take longer to read, so when you process many long documents, keep your concurrency at or below your plan's limit.

## FAQ

**Does it do OCR?**

No. Scanned pages have no text layer, so they are listed in `scanned_pages` with empty text. Use that list to send only those pages to an OCR service.

**Can it open password-protected PDFs?**

No. A PDF that needs a password to open returns `422` with the error `encrypted`. PDFs that only restrict printing or copying open normally and come back with `encrypted: true`.

**How big can a PDF be?**

Up to 15 MB and up to 200 pages per call. Files over 15 MB get `413` before anything is parsed. By default only the first 50 selected pages are read; raise `max_pages` to read up to 200.

**How do I get one page at a time?**

Use `format=pages` to get one entry per page, and `pages` to pick exactly which pages to read, for example `pages=3` or `pages=1-5,8`.

**What does `truncated` mean?**

It is `true` when not every selected page was read, either because the selection was longer than `max_pages` or because the time limit was reached. `pages_processed` lists the pages that were read.

**How are tables handled?**

Tables in the page layout come out as lines of text. The Markdown format adds a title, headings, paragraphs and bullet lists, but not Markdown tables.

**Does the provider store my files?**

The provider states that files are processed in memory and never stored, and that its logs keep only counts, timings and status codes.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


PDF to text API that returns plain text, Markdown or per-page text from an uploaded PDF or URL, with page count, metadata, language and scanned pages.

PDF to Text API: Extract Text and Markdown from PDFs