Upload a document and retrieve ordered JSON

Before you start

Use one bearer key with uploads.create, extractions.create, and extractions.read. Keys are shown once when issued, so keep the credential in your secret store.

The examples create no payment and no subscription. An extraction reserves prepaid credit when accepted, then charges only pages that finish successfully.

Download a complete example

• curl and jq
• Python 3
• Node.js 20+

Run it

export PDFSCRIBE_API_BASE="https://api.pdfscribe.ai/v1"
export PDFSCRIBE_API_KEY="YOUR_API_KEY"
export PDFSCRIBE_FILE="./invoice.pdf"
python3 quickstart.py

The scripts create an upload slot with the exact local file size and an Idempotency-Key. Retry POST /uploads with the same key and unchanged body to recover the same upload ID after a lost response. A changed body returns a conflict. A pending slot replay receives a refreshed signed URL that never outlives the slot. Once the upload is completed, replay returns no write URL. An expired slot stays expired and requires a new key. The scripts send the file directly to the signed object-store URL while preserving every returned header, verify the upload, submit an OCR extraction with an Idempotency-Key, poll until a terminal status, then fetch the ordered result. They also request /credits and the first /usage ledger page. Successful and partially successful jobs proceed to result retrieval; failed, cancelled, and expired jobs stop with a clear outcome. Polling stops after 300 seconds by default; set PDFSCRIBE_POLL_TIMEOUT_SECONDS to an integer from 1 to 3600 to change that limit. A timeout does not cancel the job: resume polling its existing extraction ID rather than creating a duplicate. A dead_letter job may be recovered by an operator and is not a terminal success.

curl outline

curl -sS -H "Authorization: Bearer $PDFSCRIBE_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-upload-20261005-001" \
  -d '{"content_type":"application/pdf","size_bytes":12345}' "$PDFSCRIBE_API_BASE/uploads"

curl -sS -H "Authorization: Bearer $PDFSCRIBE_API_KEY" -H "Idempotency-Key: invoice-20261005-001" \
  -H "Content-Type: application/json" -d '{"upload_id":"upl_...","mode":"ocr","pages":"all"}' \
  "$PDFSCRIBE_API_BASE/extractions"

Reuse the same idempotency key only when retrying the same extraction payload. A changed payload with the same key is rejected.