Name: PDF to Text API: Convert PDF Links to Markdown and Text
Brand: steadyscrape
SKU: api-steadyscrape-pdf-to-text-markdown
Availability: InStock
Author: API Market

# PDF to Text and Markdown API

## Overview

The PDF to Text and Markdown API converts public PDF links into clean Markdown or plain text, with the page count, title, author and file size of each document. `GET /v1/pdf/extract` converts one PDF and returns the result in the same response, usually in under 10 seconds. `POST /v1/pdf/jobs` starts a job for up to 10 PDF links, and `GET /v1/pdf/jobs/{jobId}` returns the results when the job has finished. It reads digital PDFs with a text layer, up to 25 MB and 200 pages each, and returns the first 20,000 characters of each PDF, with `truncated` set when the text was cut.

It is built for RAG and LLM pipelines, search indexing, document automation and research tools that need the text of public reports, forms and papers. You pay only for PDFs that return text: scanned image-only, encrypted, empty and unreachable files, and links that are not PDFs, cost 0 units. In our tests the IRS Form W-9 came back as Markdown starting with "Form W-9 (Rev. March 2024)", the W3C sample PDF returned its text "Dummy PDF file" with 1 page and its author, a job for both files finished on the first poll, and an HTML page returned `fetch_error` with 0 units charged.

## Features

*   **3 endpoints**: one synchronous conversion and an async job with polling.
*   **Markdown or text**: `markdown`, `text` or `both`.
*   **Metadata**: page count, title, author and size in bytes for every file.
*   **Batch jobs**: up to 10 PDF links per job, results kept for 24 hours.
*   **Fair billing**: 1 unit per PDF that returns text; failures, scans and polls cost 0.
*   **Idempotent jobs**: retry with the same `Idempotency-Key` to get the same job back.

## Use Cases

*   **RAG and LLM pipelines**: turn PDF links into Markdown chunks for embeddings.
*   **Search indexing**: index the text of public reports and papers.
*   **Document automation**: read forms and notices without a PDF library.
*   **Research tools**: extract the text of many PDFs in one job.

## API Documentation

### Base URL

All requests use the following base URL.

```
https://prod.api.market/api/v1/steadyscrape/pdf-to-text-markdown
```

### Authentication

All requests are authenticated with the `x-api-market-key` header.

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

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Convert one PDF

Converts one public PDF and returns the result in the same response.

**Method:** `GET`

**Endpoint:** `/v1/pdf/extract`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Public https link to a PDF | string | Yes | - | - |
| `format` | query | `markdown`, `text` or `both` | string | No | `markdown` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/steadyscrape/pdf-to-text-markdown/v1/pdf/extract?url=https://www.irs.gov/pub/irs-pdf/fw9.pdf&format=markdown' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "success": true,
  "endpoint": "pdf.extract",
  "ocr": false,
  "count": 1,
  "partial": false,
  "billable": true,
  "items": [
    {
      "position": 1,
      "source": "https://www.irs.gov/pub/irs-pdf/fw9.pdf",
      "status": "ok",
      "note": null,
      "text": null,
      "markdown": "Form W-9\n(Rev. March 2024)\nRequest for Taxpayer\nIdentification Number and Certification\nDepartment of the Treasury\nInternal Revenue Service Go to www.irs.gov/FormW9 for instructions and the latest information.\nGive form to the\nrequester. Do not\nsend to the IRS.\nBefore you begin. For guidance...",
      "pageCount": 6,
      "chars": 0,
      "title": "Form W-9 (Rev. March 2024)",
      "author": "SE:W:CAR:MP",
      "bytes": 140815,
      "truncated": true
    }
  ]
}
```

The `markdown` value above is shortened. A link that does not return a PDF is reported per item and costs 0 units:

```json
{
  "success": true,
  "endpoint": "pdf.extract",
  "ocr": false,
  "count": 1,
  "partial": false,
  "billable": false,
  "items": [
    {
      "position": 1,
      "source": "https://example.com/",
      "status": "fetch_error",
      "note": "URL did not return a PDF (got HTML). Not charged.",
      "text": null,
      "markdown": null,
      "pageCount": null,
      "chars": null,
      "title": null,
      "author": null,
      "bytes": null
    }
  ]
}
```

#### 2. Start a PDF job

Starts a job for up to 10 PDF links and returns its id with `202 Accepted`.

**Method:** `POST`

**Endpoint:** `/v1/pdf/jobs`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `Idempotency-Key` | header | Optional. Retrying with the same key and body returns the same job (8 to 80 letters, digits, `_` or `-`). | string | No | - | - |
| `pdfUrls` | body | Public https links to PDFs | array of strings | Yes | - | 10 |
| `format` | body | `markdown`, `text` or `both` | string | No | `markdown` | - |
| `includeMetadata` | body | Return page count, title, author and size | boolean | No | true | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/steadyscrape/pdf-to-text-markdown/v1/pdf/jobs' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"pdfUrls": ["https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "https://www.irs.gov/pub/irs-pdf/fw9.pdf"], "format": "text", "includeMetadata": true}'
```

**Example Response (202 Accepted):**

```json
{
  "success": true,
  "endpoint": "pdf.jobs",
  "implementation": "actor_contract_mapped_digital_only",
  "ocr": false,
  "count": 0,
  "partial": false,
  "items": [],
  "job": {
    "id": "2bb3984bd65252f62fb32a81a255b62746f9a62897ab77e75e54bc5d817550b6",
    "status": "running",
    "partial": false,
    "truncated": false,
    "billable": false,
    "expiresAt": "2026-11-15T18:57:14.054Z"
  }
}
```

#### 3. Get job results

Returns the job status and, when it has finished, one item per PDF. Poll every 5 to 10 seconds.

**Method:** `GET`

**Endpoint:** `/v1/pdf/jobs/{jobId}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `jobId` | path | The 64-character job id from the start call | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/steadyscrape/pdf-to-text-markdown/v1/pdf/jobs/JOB_ID' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "success": true,
  "endpoint": "pdf.jobs",
  "implementation": "actor_contract_mapped_digital_only",
  "ocr": false,
  "count": 2,
  "partial": false,
  "items": [
    {
      "position": 1,
      "source": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
      "status": "ok",
      "note": null,
      "text": "Dummy PDF file",
      "markdown": null,
      "pageCount": 1,
      "chars": 14,
      "title": null,
      "author": "Evangelos Vlachogiannis",
      "bytes": 13264
    },
    {
      "position": 2,
      "source": "https://www.irs.gov/pub/irs-pdf/fw9.pdf",
      "status": "ok",
      "note": null,
      "text": "Form W-9\n(Rev. March 2024)\nRequest for Taxpayer\nIdentification Number and Certification\nDepartment of the Treasury\nInternal Revenue Service Go to www.irs.gov/FormW9 for instructions and the latest...",
      "markdown": null,
      "pageCount": 6,
      "chars": 37694,
      "title": "Form W-9 (Rev. March 2024)",
      "author": "SE:W:CAR:MP",
      "bytes": 140815,
      "truncated": true
    }
  ],
  "job": {
    "id": "2bb3984bd65252f62fb32a81a255b62746f9a62897ab77e75e54bc5d817550b6",
    "status": "succeeded",
    "partial": false,
    "truncated": false,
    "billable": true,
    "expiresAt": "2026-11-15T18:57:14.054Z"
  }
}
```

The `text` values above are shortened. A job that is still running returns `202` with `"status": "running"`. An unknown job id returns `404`:

```json
{
  "success": false,
  "endpoint": "pdf.jobs",
  "implementation": "actor_contract_mapped_digital_only",
  "ocr": false,
  "count": 0,
  "partial": false,
  "items": [],
  "job": null,
  "error": {
    "code": "not_found",
    "message": "Unknown job."
  }
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 202 | Accepted | The job was accepted, or is still running when you poll it. |
| 400 | Bad Request | The input is not valid, for example a missing `url` or more than 10 links in a job. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The job id is unknown, or the path does not match an endpoint of this API. |
| 409 | Conflict | The `Idempotency-Key` was already used with a different body. |
| 410 |  | The job results have expired. Results are kept for 24 hours. |
| 429 | Too Many Requests | You went over 10 requests per second, used up the units of your plan, or reached the daily cap of 50 unbilled results. The cap resets at 00:00 UTC. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 10 requests per second. The Free trial includes 50 units, Starter 2,000 units per month for $9.99, Pro 8,000 for $29.99 and Business 25,000 for $79.99. One unit is one PDF that returns text. Unbilled results (failed, empty, refused and image-only files) are capped at 50 per account per day. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **Which PDFs are supported?**
    Digital PDFs with a text layer, up to 25 MB and 200 pages. Scanned image-only PDFs are not read, because there is no OCR, and they cost 0 units.

*   **Why is my text cut short?**
    Each PDF returns its first 20,000 characters, about 3 to 8 pages of dense text. `truncated` is true when the text was cut.

*   **When should I use a job instead of extract?**
    Use `extract` for one PDF and an answer in the same response. Use a job for up to 10 PDFs, then poll `GET /v1/pdf/jobs/{jobId}` every 5 to 10 seconds.

*   **Which calls cost units?**
    Only PDFs that return text, 1 unit each. Polls, failures, scans, empty files and links that are not PDFs cost 0 units.

*   **How long are job results kept?**
    24 hours. After that the poll returns `410`.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


Convert public PDF links to clean Markdown or plain text with page count, title and author. Batch jobs for 10 PDFs; scans and failures are free.

PDF to Text API: Convert PDF Links to Markdown and Text

Free trial