How to Use the PDF.ai Chat API

What Chat is for

• You already uploaded the PDF (URL or file) and kept its docId

• You sent that docId plus a message (question) with your X-API-Key

• The response includes an answer content string and optional references (page and line ranges)

Practical rule: Chat (v1) answers a free-form question against one uploaded docId. Ask (v2) answers against one or more parsed docIds. Use Chat when your pipeline already uses v1 upload + chat history; use Ask when you are on the v2 Parse → Ask path.

Browser chat vs Chat API vs Ask API

Credits before you scale questions

• Upload: 2 credits per file upload (Dedicated API plan credit model on API limits)

• Chat message (with GPT-4 path): gpt-4o → 2 credits per message; gpt-4-turbo (default when using that model field) → 4 credits per message

• gpt-3.5-turbo / gpt-4o-mini messages are listed on API limits as 1 credit per message when that model path applies

• 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 upload credits once per file, then message credits per Chat call. Turning on a heavier model raises the per-message cost; it does not change the upload fee.

How to call Chat

1. Have an API key

2. Upload first and keep the docId

• URL upload: POST https://pdf.ai/api/v1/upload/url with required url (timeout 300 seconds; use this path when the file is larger than the file-upload limit)

• File upload: POST https://pdf.ai/api/v1/upload/file with required file (FormData); file size limit 4.5 MB; timeout 300 seconds

3. POST docId + message

• docId — document ID from upload

• message — the question or instruction

• save_chat — save history (viewable under PDF.ai documents); the old chatId field is deprecated — use save_chat only

• use_gpt4 — use a GPT-4 model path

• model — "gpt-4o" or "gpt-4-turbo" (default when choosing that family)

• language — response language (e.g. "french")

• sys_prompt — custom system prompt

import requests

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

data = {
    "docId": "your-document-id",
    "message": "What is the main topic of this document?",
    "save_chat": True,
    "model": "gpt-4o"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

4. Optional: history and multi-doc chat

• History: If you set save_chat to true, retrieve turns with POST https://pdf.ai/api/v1/history and the same docId (Chat history). To remove saved chat with the document, use the delete path for that PDF (see How to Use the PDF.ai Delete API for v2 cleanup; v1 documents use the v1 delete path the docs describe).

• Chat across uploads: POST https://pdf.ai/api/v1/chat-all asks across your uploaded library (optional tag, topMatches; default top matches 10) — see Chat with all PDFs.

5. Check the output before you trust it

• Confirm content answers the question you asked

• Spot-check claims against the source PDF using any references page/line ranges

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

• If Chat rejects a docId, upload (or re-upload) that file first and retry with the returned id

Practical rule: a fluent content string is still a model reply. Read it against the source pages before you show it to end users as fact.

When Chat is the wrong tool

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

• You are already on v2 Parse and want multi-doc prompts. Prefer POST /v2/ask (How to Use the PDF.ai Ask API).

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

• You only need searchable markdown / contents. Prefer v2 Parse (How to Use the PDF.ai Parse API).

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

A short action plan

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

2. Upload the PDF (/v1/upload/url or /v1/upload/file) and keep the docId.

3. Check message credits for your chosen model on Chat with PDF / API limits.

4. POST https://pdf.ai/api/v1/chat with docId + message (set save_chat if you need history), then verify content against the source PDF before you wire production.