> ## 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.

# Quickstart

> Your first conversion to Markdown.

# Quickstart

You need:

* The URL base of the API.
* A API key (`x-api-key`). See [Authentication](/docs/authentication).
* A document PDF, DOCX, CSV, XLSX, PPTX, TXT or ZIP.

## Convert a local file

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.markpdf.tech/convert/raw?filename=report.pdf&mode=fast" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "content-type: application/pdf" \
    --data-binary "@report.pdf"
  ```

  ```python Python theme={null}
  import httpx

  with open("report.pdf", "rb") as fh:
      r = httpx.post(
          "https://api.markpdf.tech/convert/raw",
          params={"filename": "report.pdf", "mode": "fast"},
          headers={"x-api-key": "YOUR_API_KEY", "content-type": "application/pdf"},
          content=fh.read(),
          timeout=300,
      )
  print(r.text)
  ```

  ```javascript JavaScript theme={null}
  const data = await file.arrayBuffer();
  const res = await fetch(
    "https://api.markpdf.tech/convert/raw?filename=report.pdf&mode=fast",
    {
      method: "POST",
      headers: { "x-api-key": "YOUR_API_KEY", "content-type": "application/pdf" },
      body: data,
    },
  );
  console.log(await res.text());
  ```
</CodeGroup>

The default response is `text/markdown`. If the service returns `202` instead of `200`, the backends are temporarily saturated and your request was automatically queued: see [Jobs](/docs/api/jobs) for the polling pattern.

## Convert from signed URL

If your document is already in storage (S3, R2, Supabase, GCS, Azure Blob), it is more efficient to send the signed URL instead of uploading the binary:

```bash theme={null}
curl -X POST "https://api.markpdf.tech/convert/from-url" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://storage.example.com/signed/report.pdf",
    "filename": "report.pdf",
    "mode": "fast"
  }'
```

Full detail in [POST /convert/from-url](/docs/api/convert-from-url), including anti-SSRF security and BYOS exit (`output_url`).

## Convert by uploading the file as a form

If your client already handles `multipart/form-data` (for example a web form with `<input type="file">`), use `POST /convert`:

```bash theme={null}
curl -X POST "https://api.markpdf.tech/convert?mode=fast" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@report.pdf"
```

See [POST /convert](/docs/api/convert) for full details.

## Primeros pasos recomendados

1. **Starts with `mode=fast`** (this is the default) unless the document has complex tables or irregular layout.
2. **Review the response headers** (`X-Token-Saved-Estimate`, `X-Conversion-Ms`) to understand the real savings in your use case. See [Response and headers](/docs/api/response).
3. **If you are converting the same document several times**, save `ETag` and resend with `If-None-Match` to avoid reconversion. See [Cache](/docs/concepts/caching).
4. **If PDF is large and you are only interested in part of it**, try [`POST /pdf/index`](/docs/api/pdf-index) first before converting the entire document.
5. **Handle `202`**: In high traffic, API can automatically queue your request. The SDK/client must know how to poll `/jobs/{id}`. See [Jobs](/docs/api/jobs).

## Modos

| Modo      | Uso                                                                |
| --------- | ------------------------------------------------------------------ |
| `fast`    | Maximum speed. Recommended for agents. Default.                    |
| `quality` | Slower, better for difficult documents.                            |
| `auto`    | The API decides, starting quickly and moving up only if necessary. |

Detail in [Conversion modes](/docs/concepts/modes).

## Useful headers

The response includes observability headers:

| Header                   | Significado                                          |
| ------------------------ | ---------------------------------------------------- |
| `X-Input-Bytes`          | Bytes of the processed document.                     |
| `X-Markdown-Bytes`       | Markdown output size.                                |
| `X-Token-Saved-Estimate` | Estimation of saved tokens.                          |
| `X-Conversion-Engine`    | Used conversion engine.                              |
| `X-Conversion-Ms`        | Conversion time in milliseconds.                     |
| `ETag`                   | Hash for cache. See [Cache](/docs/concepts/caching). |

Complete reference in [Response and headers](/docs/api/response).

## Common mistakes when starting

* **`401`**: header `x-api-key` is missing or the key is invavalid. Check [Authentication](/docs/authentication).
* **`415`**: `content-type` or `content-encoding` is not a supported one. In `/convert/raw` only `gzip` or `zstd` is accepted as compression.
* **`422`**: in `/convert/from-url` the field `url` is missing in the JSON body or in the query.
* **`413`**: The document exceeds the size/page limit. See [Weights and limits](/docs/api/heavy-and-limits).

Complete list in [Errors](/docs/errors).

## Siguiente paso

<Card title="Summary of API" icon="compass" href="/docs/api/overview">
  All endpoints, base URL and response model at a glance.
</Card>