Jobs

Create a conversion job

Accepts a PDF file (multipart) or a link to a PDF (JSON). Maximum file size — 10 MB. Priority is assigned by the number of device runs per day for the selected converter (minimum 4). Processing lasts up to 5 minutes; if exceeded, the job fails with an error. The result is stored for 1 hour after it is ready.

post/jobs

Request

  • Base URL: https://pdf2md.dev
  • URL: https://pdf2md.dev/jobs
  • Auth: HTTP bearer

Headers

Idempotency-Keystring
Example:req-123e4567

Idempotency key for safe retries of job-creation requests (ttl 24h)

X-Timestampinteger required
Example:1700000000

Unix time (sec) for the request signature (±300s window, see docs/security.md)

X-Noncestring required
Example:bXlfbm9uY2UtdjE

Random string (base64url), unique per request (TTL 5 minutes, anti-replay)

X-Body-SHA256string required
Example:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

hex sha256 of the request body (for GET/DELETE — sha256 of an empty body)

X-Signaturestring required
Example:MEYCIQCZqlk3E1p5k2y1hZ0ykjW9tzjO4GDBWJ3QYw9UWF2gtwIhAKuQKk8NfZp7uA9u6YzKxHnD7bHkHHRp2tkMZ0QYpQMb

Signature of the canonical string (ES256), see docs/security.md

Request body

urlstring uri required

Direct link to a PDF

file_namestring

File name for display (optional)

converter_codestring required

Converter code (MVP: pdf_to_md)

ocr_lang'ru' | 'en' | 'ja' | 'es' | 'pt' | 'de' | 'fr'

OCR language hint (EP-070, additive). Selects the OCR recognition model for scanned pages / forced OCR in BOTH engines (MinerU maps ja→japan and es/pt/de/fr→latin; docling builds a per-request EasyOCR list <lang>+en). Only affects OCR: PDFs with a digital text layer are extracted, not recognized, and ignore this hint. Absent → the engine's env default (current ru+en behavior). Unknown values are rejected with 400.

Example request

{
  "url": "https://example.com/files/report.pdf",
  "file_name": "report.pdf",
  "converter_code": "pdf_to_md"
}

Response

Job queued

job_idstring uuid required
status'queued' | 'processing' | 'ready' | 'error' | 'canceled' | 'deleted' required

Job status

converter_codestring required
status_sincestring date-time required

Time of entry into the current status (UTC)

priorityinteger required

A lower number — higher priority. v2 (EP-023, §7.7): a band scale, min is no longer 4 — the client treats the value as opaque (timers are computed from status_since/ready_at, not from priority).

priority_assigned_atstring date-time required

When priority was assigned/lowered

error_messagestring nullable
error_codestring nullable

Stable machine error code for a failed job (EP-031). Additive — absent on success and on older records. Clients localize by this code; the human error_message is a fallback.

file_namestring required
output_sizeinteger nullable

Markdown size (bytes), only for ready

download_urlstring uri nullable

Populated for ready

pagesinteger nullable

Number of pages in the source PDF (EP-018). An additive field — absent on the old backend/old jobs; clients should ignore it if missing.

truncatedboolean

true — the result is partial: conversion reached the soft time budget and a disclaimer was appended to the end of the Markdown (EP-018). Additive, backward-compatible: absence/false = full result.

Example response

{
  "converter_code": "pdf_to_md"
}

Changes

No recorded changes to this operation across all 1 revision of this API.