> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Endpoints, URL base, authentication and response model at a glance.

# API Overview

The API exposes three ways to convert a document to Markdown, plus a state endpoint. Everything answers `text/markdown` by default, or JSON if you order it.

## Base URL

```
https://api.markpdf.tech
```

## Authentication

All calls use `x-api-key`. See [Authentication](/docs/authentication).

```http theme={null}
x-api-key: YOUR_API_KEY
```

## Endpoints

<CardGroup cols={2}>
  <Card title="POST /convert" icon="upload" href="/docs/api/convert">
    Upload the file as `multipart/form-data`.
  </Card>

  <Card title="POST /convert/raw" icon="file-arrow-up" href="/docs/api/convert-raw">
    Send the raw binary in the body. Supports gzip and zstd.
  </Card>

  <Card title="POST /convert/from-url" icon="link" href="/docs/api/convert-from-url">
    Convert from a signed URL from S3, R2, Supabase, GCS, or Azure.
  </Card>

  <Card title="GET /jobs/{id}" icon="clock" href="/docs/api/jobs">
    Status of an automatically queued conversion (202).
  </Card>

  <Card title="GET /" icon="heart-pulse" href="/docs/api/status">
    Service status and supported formats.
  </Card>

  <Card title="Parameters" icon="svaliders" href="/docs/api/parameters">
    Complete reference of query params, modes and formats.
  </Card>

  <Card title="Answer" icon="brackets-curly" href="/docs/api/response">
    Observability headers and body JSON.
  </Card>
</CardGroup>

## The three conversion routes

| Endpoint                 | How do you send the document         | When to use it                                              |
| ------------------------ | ------------------------------------ | ----------------------------------------------------------- |
| `POST /convert`          | `multipart/form-data` (field `file`) | Web forms, clients that already upload files.               |
| `POST /convert/raw`      | Binary in the bodysuit               | Maximum efficiency, supports gzip/zstd compression.         |
| `POST /convert/from-url` | URL signed                           | Large documents already in storage; avoid forwarding bytes. |

<Tip>
  For large documents, `from-url` usually wins: your server doesn't receive or forward the same file twice.
</Tip>

## Response model

By default you receive raw Markdown (`text/markdown; charset=utf-8`) plus observability headers. With `response_format=json` you receive an object with Markdown and metadata embedded.

See [Response and headers](/docs/api/response).

## Status codes

| Code  | Meaning                                                                                     |
| ----- | ------------------------------------------------------------------------------------------- |
| `200` | Correct conversion.                                                                         |
| `202` | Automatically queued (saturated backends). Pulley `/jobs/{id}`. See [Jobs](/docs/api/jobs). |
| `304` | Not modified (matches `ETag` sent in `If-None-Match`).                                      |
| `400` | Invavalid body or malformed URL.                                                            |
| `403` | Unauthorized access or URL host not allowed.                                                |
| `413` | Exceeds the maximum size, number of pages, or limits of ZIP.                                |
| `415` | Format or `Content-Encoding` not supported.                                                 |
| `422` | `url` is missing from `from-url`.                                                           |
| `500` | Internal conversion error.                                                                  |

Detail in [Errors](/docs/errors).