How to Use the PDF.ai Upload API

What Upload is for

• You sent a reachable PDF URL or a file with your X-API-Key

• The response includes a docId string you can store

• You know which size/timeout path you used (file vs URL) so retries stay inside the documented limits

Practical rule: Upload gives you a library docId. Chat, chat-all, history, tags, and post-upload OCR all expect that id. Parse/Extract/Ask on v2 use their own parse pipeline — do not assume a v1 upload docId is interchangeable with a v2 Parse docId without checking the endpoint you call next.

URL upload vs file upload

Credits before you scale uploads

• Upload: 2 credits per file upload

• Free: $0/month for 200 credits/month, no credit card required

• Paid examples: $49 / 3,000, $99 / 10,000, $249 / 30,000, $599 / 100,000 credits per month

Practical rule: count 2 credits once per successful upload on the Dedicated credit model. Turning on ocr=true at upload time can push large scans past the 300-second timeout (Upload docs warn a 500 is likely then) — that is a reliability issue, not a free extra credit line.

How to call Upload

1. Have an API key

2. Choose URL or file

• URL upload: POST https://pdf.ai/api/v1/upload/url with required url

• File upload: POST https://pdf.ai/api/v1/upload/file with required file (FormData); use URL upload when the file is larger than 4.5 MB

• isPrivate — whether the PDF is private

• ocr — enable Optical Character Recognition so scanned text becomes searchable

• tags — array of strings (e.g. ["Tag1", "Tag2"])

3. Example: upload by URL

import requests

url = "https://pdf.ai/api/v1/upload/url"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com/your-document.pdf",
    "isPrivate": False,
    "ocr": False,
    "tags": ["invoices", "2026"]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())  # {"docId": "..."}

4. Example: upload by file

import requests

url = "https://pdf.ai/api/v1/upload/file"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}

files = {
    "file": open("your-document.pdf", "rb")
}
data = {
    "isPrivate": "false",
    "ocr": "false"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())  # {"docId": "..."}

5. Optional: OCR after upload, list, or fetch one doc

• OCR later (no extra credits per the OCR docs): If you skipped ocr=true at upload, POST https://pdf.ai/api/v1/ocr with required docId and optional ocrLang (default "eng"). Timeout 300 seconds; file size limit 50 MB (OCR an uploaded PDF).

• List library: GET https://pdf.ai/api/v1/documents returns id, name, size, isPublic, uploadedAt, url, importUrl (Get all documents).

• One document: GET https://pdf.ai/api/v1/documents/{docId} adds tags among the same core fields (Get single document).

6. Check the output before you trust it

• Confirm the JSON includes a non-empty docId

• Spot-check GET /documents/{docId} (or the list endpoint) so name/size match what you sent

• If you get Invalid API key / No API key present, fix the header before you change the file

• If file upload fails near 4.5 MB, switch to URL upload

• If OCR-on-upload returns 500, the Upload docs say the document is likely too large for the 300-second window — OCR the file yourself first, or use the post-upload OCR endpoint on a smaller/split file

Practical rule: a returned docId only means the library accepted the file. Open or chat against it before you treat the pipeline as production-ready.

When Upload is the wrong tool

• You need searchable markdown / page JSON in one call. Prefer v2 Parse (How to Use the PDF.ai Parse API), not v1 upload alone.

• You need named fields / tables as JSON. Use POST /v2/extract with a schema (How to Use the PDF.ai Extract API).

• You already have a docId and only want Q&A. Call Chat (How to Use the PDF.ai Chat API) or Ask on v2 (How to Use the PDF.ai Ask API).

• You only need one chat in a browser. Use How to Chat with a PDF. No API key required for that job.

• You wanted a generic “pdf api” category hub. Stay on https://pdf.ai/developer. This page is the Upload how-to, not a replacement hub.

A short action plan

1. Open https://pdf.ai/developer, create a key, store it once.

2. Pick URL (/v1/upload/url) or file (/v1/upload/file) from the size rules above.

3. Budget 2 credits per upload on the Dedicated credit model (API limits).

4. POST the upload, store docId, then verify with GET /documents/{docId} before you wire Chat or other v1 calls.