# Markdown to PDF

This endpoint accepts Markdown and a small set of rendering options, then delivers the finished PDF through the shared DocuShell jobs API.

Source: https://docs.docushell.com/markdown-to-pdf
Category: Reference
Read time: 5 min

## Related

- [Getting started](/getting-started.md): Shared auth, idempotency, status, and download behavior.
- [Overview](/index.md): See how this lane fits into the overall endpoint inventory.

## What It Does

Submit Markdown, choose a print size, and let DocuShell render the output as a queued PDF generation job.

## Endpoint Reference

- Method: `POST`
- Path: `/v1/markdown-to-pdf`
- Auth: Bearer token required.
- Idempotency: Supports optional `Idempotency-Key` replay protection.
- Content type: `application/json`

Queue a Markdown render job and download the finished PDF through the shared jobs API.

### Headers

| Name | Type | Required | Location | Description |
| --- | --- | --- | --- | --- |
| Authorization | Bearer <API_KEY> | Yes | header | User-owned API key created in the DocuShell dashboard. |
| Idempotency-Key | string | No | header | Recommended for safely retrying submit requests without creating duplicate jobs. |
| Content-Type | application/json | Yes | header | JSON body with Markdown content. |

### Request Fields

| Name | Type | Required | Location | Description |
| --- | --- | --- | --- | --- |
| markdown | string | Yes | body | Markdown source. The public lane enforces a 2 MB request body limit. |
| file_name | string | No | body | Optional source name used to derive the output filename. |
| page_size | A4 \| Letter \| Legal | No | body | Target print size for the generated PDF. Default: A4 |

### Sample Requests

#### First request

```bash
curl -X POST "https://api.docushell.com/api/v1/markdown-to-pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  -d '{
    "markdown": "# DocuShell\n\nRendered through the public API.",
    "file_name": "quickstart.md",
    "page_size": "A4"
  }'
```

### Queued Response

#### Queued response

```json
{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 1000,
  "service": "markdown-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}
```

### Status Response

#### Status response

```json
{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "done",
  "service": "markdown-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "result": {
    "filename": "quarterly-report.pdf",
    "sizeBytes": 184322,
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  },
  "completed_at": "2026-04-24T10:12:56.145Z",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}
```

Completed jobs return a public download link and keep the file streaming URL behind the gateway. Downloads use application/pdf.

### Poll And Download

- Poll the shared jobs endpoint until the job status becomes `done`.
- Completed jobs expose a single PDF download URL through the gateway.

### Failure Notes

- Malformed JSON or missing `markdown` content returns `invalid_request`.
- Bodies larger than 2 MB are rejected before a job is created.
- `backend_unavailable` indicates the render service was unreachable before the queue handoff completed.

### Error Examples

#### Oversized request body

- Status: `400`
- Code: `invalid_request`

The Markdown payload or overall JSON request exceeds the configured 2 MB limit.

##### 400 error

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request body exceeds the 2 MB limit.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

#### Authentication failure

- Status: `401`
- Code: `invalid_api_key`

Returned when the bearer token is missing, revoked, expired, or not allowed to use the API lane.

##### 401 error

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "type": "auth_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

#### Idempotency conflict

- Status: `409`
- Code: `idempotency_key_reused`

Returned when the same Idempotency-Key is reused with a different payload than the original request.

##### 409 error

```json
{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

#### Webhook access disabled

- Status: `403`
- Code: `webhook_access_disabled`

Returned when a Starter API key submits webhook fields. Pro, Growth, and Scale include webhooks.

##### 403 error

```json
{
  "error": {
    "code": "webhook_access_disabled",
    "message": "Webhooks are available on Pro, Growth, and Scale. Starter includes API access without webhooks.",
    "type": "billing_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

#### Rate limit

- Status: `429`
- Code: `rate_limit_exceeded`

Returned when the API key or caller fingerprint exceeds the configured request rate.

##### 429 error

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "type": "rate_limit_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```