DocuShell
PProduct HuntLaunch offer: reserve 1 month of Pro free before limited slots open.Reserve free Pro

Reference

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.

Reference5 min
View as Markdown
Getting startedShared auth, idempotency, status, and download behavior.OverviewSee how this lane fits into the overall endpoint inventory.

Section

What It Does

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

Reference

Endpoint Reference

POST/v1/markdown-to-pdf

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

Auth

Bearer token required.

Idempotency

Supports optional Idempotency-Key replay protection.

Content Type

application/json

Headers

NameTypeRequiredLocationDescription
AuthorizationBearer <API_KEY>YesheaderUser-owned API key created in the DocuShell dashboard.
Idempotency-KeystringNoheaderRecommended for safely retrying submit requests without creating duplicate jobs.
Content-Typeapplication/jsonYesheaderJSON body with Markdown content.

Request Fields

NameTypeRequiredLocationDescription
markdownstringYesbodyMarkdown source. The public lane enforces a 2 MB request body limit.
file_namestringNobodyOptional source name used to derive the output filename.
page_sizeA4 | Letter | LegalNobodyTarget print size for the generated PDF.Default: A4

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"
  }'

Try It Now

Console placeholder for safe sandbox execution.

Coming soon

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

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.

Oversized request body

400invalid_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

401invalid_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

409idempotency_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

403webhook_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

429rate_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"
  }
}