A PDF in.
A useful response out.

01. Upload and inspect

Send one PDF as multipart field file. Inspection is free and rate-limited. You can also send JSON with a public HTTPS url.

curl https://api.micropdf.cloud/v1/documents \
  -F 'file=@report.pdf'

Save the returned id and token securely. The token is shown once and authorizes this document’s quotes, jobs and results. Do not put it in a URL or public log.

# Use values from the upload response.
DOCUMENT_ID='your-document-id'
DOCUMENT_TOKEN='your-document-token'

curl "https://api.micropdf.cloud/v1/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $DOCUMENT_TOKEN"

02. Create a quote

Page numbers are one-based. Omit pages to select all pages. Use "ocr":"auto" to recognize scanned pages, or "never" for native text only. This example assumes at least two pages.

curl "https://api.micropdf.cloud/v1/documents/$DOCUMENT_ID/quotes" \
  -H "Authorization: Bearer $DOCUMENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"pages":[1,2],"ocr":"auto"}'

The response includes a quote id, amount, network, expiresAt and executeUrl. Amounts are integer strings in atomic USDC units: 1000 = 0.001 USDC. Quotes currently expire after 15 minutes, or sooner if the document expires.

03. Authorize with x402

POST to the quote’s execute URL with the document token and a stable Idempotency-Key (8–128 letters, digits, dots, underscores, colons or hyphens). Do not send extraction options in this request.

QUOTE_ID='your-quote-id'
IDEMPOTENCY_KEY='a-unique-key-for-this-quote'

curl -i -X POST \
  "https://api.micropdf.cloud/v1/quotes/$QUOTE_ID/execute" \
  -H "Authorization: Bearer $DOCUMENT_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

The server returns 402 and a PAYMENT-REQUIRED header. Use an x402 v2 client to read the requirements, verify the recipient, resource, network and amount against your policy, then sign with a test wallet. Retry the same URL and idempotency key with PAYMENT-SIGNATURE.

A successful settlement returns 202, a job ID and a PAYMENT-RESPONSE receipt. Signing and settlement happen in your client and the facilitator; never send your private key to MicroPDF.

Runnable TypeScript example

Download extract.ts. It uploads a PDF, checks a spending cap, uses the official x402 SDK, and polls for Markdown. Review it before running. It submits a real testnet payment using the supplied test wallet.

npm init -y
npm pkg set type=module
npm install @x402/core@2.27.0 @x402/evm@2.27.0 viem@2.56.9 tsx

# Set TEST_PRIVATE_KEY securely in your local environment.
# Use a dedicated Base Sepolia test wallet with test USDC.
API_URL=https://api.micropdf.cloud \
MAX_PAYMENT_ATOMIC=50000 \
node --import tsx extract.ts report.pdf

The cap above is 0.05 test USDC. The example does not supply funds, manage your wallet, or enable mainnet. Learn about the protocol at x402.org.

04. Poll and retrieve

The paid job ID is the quote ID. Poll until succeeded or failed. A successful job may still contain partial output: check partial, each page’s method, and all warnings.

curl "https://api.micropdf.cloud/v1/jobs/$QUOTE_ID" \
  -H "Authorization: Bearer $DOCUMENT_TOKEN"

# After status becomes succeeded:
curl "https://api.micropdf.cloud/v1/jobs/$QUOTE_ID/result?format=markdown" \
  -H "Authorization: Bearer $DOCUMENT_TOKEN"

Use format=json for the complete result. It includes schemaVersion, pages, markdown, warnings, and partial. Pages contain dimensions, method (native, ocr or failed), and blocks. Block coordinates use PDF points with a top-left origin.

Headings, reading order and simple tables are heuristic. Images and charts are not described. Text embedded inside images on otherwise text-rich pages may be omitted. Keep source references and warnings when passing results to an agent.

Endpoint reference

All document-specific routes require the bearer token from upload. The live OpenAPI specification is authoritative.

Limits and retention

• Up to 20 MB and 50 pages per document; encrypted PDFs are rejected.
• Printed English OCR. No handwriting, formula or semantic-accuracy guarantee.
• Source and results expire 24 hours after upload, including queued jobs. Delete them earlier with the endpoint below.
• Minimal audit records remain for up to 30 days after content expiry. Uncertain settlements remain until reconciled.
• Resource and rate limits apply. A 503 capacity response before payment means retry later.

curl -X DELETE \
  "https://api.micropdf.cloud/v1/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $DOCUMENT_TOKEN"

Deletion revokes access and removes retained source/results. Already-running processing can retain temporary data until it exits. Assess the beta’s retention and operational limits before uploading sensitive content.

Retries without another charge

Retry a paid quote with the same idempotency key to retrieve its existing job. Do not reuse that key for another quote on the same document.

If you see PAYMENT_UNCERTAIN or PAYMENT_PENDING, stop creating payment authorizations. Retain your quote ID and transaction details for operator reconciliation. Failed paid jobs also require operator resolution; automatic refunds are not implemented.

Other common responses: 410 for expired resources, 429 for rate limits, and 422 for unsupported or invalid PDFs. Read the JSON error.code and error.message; don’t infer settlement from an HTTP timeout.