API Reference

Endpoints, authentication, error codes, rate limits and idempotency for the PDF-2-Markdown conversion API. See the pricing page for plans.

Authentication

Send your API key as a bearer token, never as a query parameter:

Authorization: Bearer pk_live_...

Endpoints

One endpoint per format, all POST, all returning JSON. Send the file contents as the raw request body — JSON/HTML as text, CSV as the raw file, DOCX as raw binary. No multipart, no base64 wrapping.

POST /v1/convert/json

curl -X POST https://pdf-2-markdown.com/v1/convert/json \
  -H "Authorization: Bearer pk_live_..." \
  -d '{"name":"example","items":[1,2,3]}'

Response — 200:

{"markdown":"- **name:** example\n\n- 1\n- 2\n- 3","itemCount":2}

POST /v1/convert/csv

curl -X POST https://pdf-2-markdown.com/v1/convert/csv \
  -H "Authorization: Bearer pk_live_..." \
  --data-binary @file.csv

Response — 200:

{"markdown":"| a | b |\n| --- | --- |\n| 1 | 2 |","rowCount":2,"columnCount":2,"delimiter":","}

POST /v1/convert/html

curl -X POST https://pdf-2-markdown.com/v1/convert/html \
  -H "Authorization: Bearer pk_live_..." \
  -d '<h1>Title</h1><p>Text</p>'

Response — 200:

{"markdown":"# Title\n\nText","charCount":13}

POST /v1/convert/docx

curl -X POST https://pdf-2-markdown.com/v1/convert/docx \
  -H "Authorization: Bearer pk_live_..." \
  --data-binary @file.docx

Response — 200:

{"markdown":"# Heading\n\nParagraph text.","charCount":29,"warnings":[]}

Errors

Every error, from every endpoint, uses the same shape:

{"error":{"code":"quota_exceeded","message":"No conversions remaining this billing period."}}

Status	Code	Meaning
401	unauthorized	Missing or invalid API key.
402	quota_exceeded	No conversions remaining this billing period.
403	subscription_past_due	Payment failed, renewals paused.
403	subscription_canceled	Access has ended.
404	unknown_format	No converter for that path.
405	method_not_allowed	Use POST.
413	payload_too_large	Body exceeds the 10MB limit.
422	invalid_input	Body could not be converted (bad JSON, empty body, corrupt file, etc).
429	rate_limited	Too many requests; see the Retry-After header.

Rate limits & quota

Each key allows up to 60 requests per minute, independent of your monthly plan quota — this caps abuse from a leaked key or a retry-loop bug, not normal usage. Hitting it returns 429 with a Retry-After header (seconds to wait). Your monthly call allowance resets on each billing renewal and does not roll over. A failed conversion (bad input, corrupt file) never costs you a call — only a successful one does.

Idempotency

Retrying a request after a network timeout can accidentally double-submit the same conversion. Add an Idempotency-Key header (any unique string you generate) and a retry with the same key returns the original response instead of processing again or spending another call:

curl -X POST https://pdf-2-markdown.com/v1/convert/json \
  -H "Authorization: Bearer pk_live_..." \
  -H "Idempotency-Key: 5f8c1e2a-..." \
  -d '{"a":1}'

Keys are remembered for 5 minutes — enough to cover a client retry, not meant as a long-lived cache.

Getting a key

Subscribe on the pricing page — your key is emailed to you once payment completes. For the Scale tier, or any question before subscribing, contact us directly.