ExactPDF API v1

OpenAPI for ChatGPT Actions

Use https://exactpdf.com/openapi.json when wiring ExactPDF into custom GPTs, ChatGPT Actions, or enterprise agent platforms that import OpenAPI. The first stable spec intentionally covers JSON-friendly document intelligence endpoints: account, PDF info, text extraction, and structured Markdown. Binary file-returning operations and the public ChatGPT Apps MCP endpoint are separate surfaces so review, auth, and file-handling stay clean.

curl https://exactpdf.com/openapi.json | jq '.info.title, .paths | keys'

POST /api/v1/pdf-to-json

One file (PDF). Returns metadata, pages with per-page text and character counts, full text, page_count, and extraction_mode. 1 crediton success. This is text-layer JSON; scanned PDFs need OCR first and table cell reconstruction is not guaranteed.

POST /api/v1/pdf-structured-markdown

One file (PDF). Optional field mode set to developer, academic, or rag (defaults to developer). Academic inserts --- between pages — ideal for auditors crawling long PDF audits. Rag collapses hyphen breaks + short-line fragments — ideal for embeddings. Use output_format=json for Markdown plus page/chunk provenance,markdown for a direct .md response, or jsonl for deterministic bounded RAG chunks. OCR is not run, images are not extracted, and tables remain reading-order text. 1 credit on success. Max upload 12MB — same safeguard as plain text extraction (CPU bound).

curl (Bearer key)

curl https://exactpdf.com/api/v1/pdf-structured-markdown \
  -H "Authorization: Bearer sk_live_..." \
  -F "mode=rag" -F "output_format=jsonl" \
  -F "file=@paper.pdf"

RAG ingestion pattern

For retrieval pipelines, prefer pdf-structured-markdown with mode=rag. Keep the returned chunks or request output_format=jsonl. Store the stable chunk ID, page number, and page anchor with each embedding. Tables are reading-order text, not reconstructed cells.

Node: fetch Markdown, then split on headings

import { readFile } from 'node:fs/promises'

const form = new FormData()
form.append('mode', 'rag')
form.append('file', new Blob([await readFile('manual.pdf')]), 'manual.pdf')

const res = await fetch('https://exactpdf.com/api/v1/pdf-structured-markdown', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EXACTPDF_API_KEY}` },
  body: form,
})
if (!res.ok) throw new Error(await res.text())

const { chunks, warnings, capabilities } = await res.json()
for (const chunk of chunks) {
  await vectorStore.upsert({
    id: chunk.chunk_id,
    text: chunk.text,
    metadata: {
      source: 'manual.pdf',
      page: chunk.page_number,
      anchor: chunk.page_anchor,
    },
  })
}
console.warn({ warnings, capabilities })

Python: heading-aware chunks for vector databases

import os, re, requests

with open("manual.pdf", "rb") as f:
    r = requests.post(
        "https://exactpdf.com/api/v1/pdf-structured-markdown",
        headers={"Authorization": f"Bearer {os.environ['EXACTPDF_API_KEY']}"},
        files={"file": f},
        data={"mode": "rag"},
    )
r.raise_for_status()
payload = r.json()

chunks = [{
        "id": chunk["chunk_id"],
        "text": chunk["text"],
        "metadata": {
            "source": "manual.pdf",
            "page": chunk["page_number"],
            "anchor": chunk["page_anchor"],
        },
    } for chunk in payload["chunks"]]

POST /api/v1/voice-preview

JSON or multipart/form-data. Generates a short MP3/WAV voice sample before a paid background speech job. Fields: text (server-capped at 600 characters), output_format (mp3 or wav), voice_style, voice_id, language, and speed. Requires an API key but costs 0 credits.

curl https://exactpdf.com/api/v1/voice-preview \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Preview this narrator before generating the full audiobook.","voice_style":"professional","language":"en"}' \
  -o preview.mp3

POST /api/v1/pdf-to-audiobook

Compatibility aliases: POST /api/v1/pdf-to-speech and POST /api/v1/generate-audiobook. One file (PDF). This creates a background PDF-to-speech/audiobook job and returns HTTP 202 with job_id and status_url. Optional fields: output_format (mp3, m4b, mp4), voice_style, voice_id, language, speed, page_range, normalize_pauses, preserve_chapters, pronunciation_fixes, callback_url, and webhook_secret. Credits are estimated from selected PDF text before queueing: 15 credits/minute for MP3/M4B; 20 for MP4.

curl

curl https://exactpdf.com/api/v1/generate-audiobook \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@training.pdf" \
  -F "voice_style=professional" \
  -F "output_format=mp3"

GET /api/v1/jobs/:id

Speech compatibility aliases: GET /api/v1/speech-jobs/:id and GET /api/v1/speech-jobs/:id/download. Poll an async job created by pdf-to-speech, pdf-to-audiobook, generate-audiobook, translate-and-speak, or presentation-narration. Succeeded jobs include a temporary result_url for download. Failed jobs include error_code and error_message. Polling is free.

Webhooks are best-effort completion callbacks. If webhook_secret is supplied, ExactPDF sends x-exactpdf-timestamp, x-exactpdf-event, and x-exactpdf-signature. Verify the signature by computing HMAC-SHA256 over timestamp.body and comparing it with the header value after sha256=.

curl https://exactpdf.com/api/v1/speech-jobs/JOB_ID \
  -H "Authorization: Bearer sk_live_..."

curl -L https://exactpdf.com/api/v1/speech-jobs/JOB_ID/download \
  -H "Authorization: Bearer sk_live_..." \
  -o audiobook.mp3

POST /api/v1/translate-and-speak

One file (PDF) plus required target_language. When enabled, creates a background job that extracts PDF structure, translates the selected text, and generates native speech audio with chapter/page preservation. Sprint 4 live validation starts with hi, es, and fr; the worker is designed for additional Google Cloud TTS languages such as mr, de, ja, and ar. Pricing is 45 credits per estimated generated minute when the feature is eventually certified.

Optional fields: source_language, output_format, voice_style, speed, page_range, segmentation_mode (chapters or pages), translation_glossary, callback_url, and webhook_secret. Use segmentation_mode=pages when narrating presentation PDFs.

curl https://exactpdf.com/api/v1/translate-and-speak \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@report.pdf" \
  -F "target_language=es" \
  -F "voice_style=professional"

POST /api/v1/presentation-narration

One file (PDF) creates a page-timed presentation narration job. Each PDF page is treated as a slide and the default output is mp4. Pricing is 20 credits per estimated generated minute.

Optional fields: output_format, voice_style, speed, page_range, callback_url, and webhook_secret.

curl https://exactpdf.com/api/v1/presentation-narration \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@slides.pdf" \
  -F "voice_style=presenter"

MCP (ChatGPT / Cursor / Claude / Codex)

Hosted MCP endpoint for ChatGPT Developer Mode: https://exactpdf.com/mcp. This first hosted surface is read-only: it helps ChatGPT choose ExactPDF workflows, set up OpenAPI actions, plan audio duration, and understand current capabilities without asking users to paste secrets in chat. It returns structured output through a CSP-declared app resource and does not receive files, access accounts, create jobs, process payments, or write request-level usage logs. Authenticated PDF processing remains available through OpenAPI/API-key actions while OAuth and file-reference handling are prepared for public ChatGPT Apps review.

Package @exactpdf/mcp is the ExactPDF stdio server for agent clients. Set EXACTPDF_API_KEY and wire stdio in your MCP client. Start with exactpdf_first_run_checklist, then exactpdf_account and exactpdf_pdf_info before paid work. Tools: exactpdf_account, exactpdf_pdf_info, exactpdf_merge_pdfs, exactpdf_split_pdf, exactpdf_rotate_pdf, exactpdf_compress_pdf, exactpdf_compress_pdf_to_target, exactpdf_compress_pdf_to_100kb, exactpdf_compress_pdf_to_200kb, exactpdf_compress_pdf_to_500kb, exactpdf_compress_pdf_to_1mb, exactpdf_pdf_to_images, exactpdf_images_to_pdf, exactpdf_extract_text, exactpdf_pdf_to_json, exactpdf_pdf_structured_markdown, exactpdf_ocr_pdf, exactpdf_estimate_speech_cost, exactpdf_voice_preview, exactpdf_pdf_to_speech, exactpdf_pdf_to_audiobook, exactpdf_generate_audiobook, exactpdf_translate_and_speak, exactpdf_presentation_narration, exactpdf_job_status, exactpdf_get_speech_job, exactpdf_download_audio. Optional: EXACTPDF_API_OUTPUT_DIR or EXACTPDF_MERGE_OUTPUT_DIR for saved PDF, ZIP, and audio outputs. English audio submission tools queue bounded paid jobs. Translate-and-speak intentionally remains disabled.

{
  "mcpServers": {
    "exactpdf": {
      "command": "npx",
      "args": ["-y", "@exactpdf/mcp"],
      "env": { "EXACTPDF_API_KEY": "sk_live_..." }
    }
  }
}