Official API Reference

Complete guide to integrating ChatPDF's RAG (Retrieval Augmented Generation) pipeline. Build powerful PDF analysis tools with Gemini-powered context retrieval.

Production Base URL

https://api.chatpdf.ai/api/v1

Content Type

application/json

Authorization Header

ChatPDF uses JWT-based authentication. All endpoints (except Auth) require a valid Authorization header.

Authorization:Bearer <YOUR_ACCESS_TOKEN>

User & Auth Endpoints

POST/auth/register

Create a new developer/user account.

{ "email": "dev@example.com", "username": "dev01", "password": "...", "full_name": "..." }

POST/auth/login

Exchange credentials for JWT tokens.

{ "email": "dev@example.com", "password": "..." }

Document Lifecycle

POST/upload— Multi-part Form

Uploads a PDF and enqueues it for background parsing.

curl -X POST https://api.chatpdf.ai/api/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/contract.pdf"

GET/upload/status/{document_id}

Possible Statuses

uploadingprocessingembeddingreadyfailed

Document Management

GET/documents

List All

Returns metadata for all documents owned by the authenticated user.

DELETE/documents/{id}

Irreversible

Permanently deletes document file, embeddings, and chat history.

Conversational Engine

POST/chat

Standard JSON interaction. Performs relative search using top-k retrieval and generates an answer with citations.

Request Schema (JSON)

{
  "document_id": "8f2e9...",
  "question": "Summary?",
  "top_k": 5,     // range 1-10
  "stream": false // set true for SSE
}

Response Object

{
  "answer": "...",
  "sources": [{ "page": "1", ... }],
  "conversation_id": "uuid",
  "confidence": 0.92
}

Streaming Strategy (SSE)

Set stream: true to receive real-time token events. Our SSE implementation uses typed events: token, sources, and done.

View implementation details →

Persistence

All conversational state is persisted in PostgreSQL. Use these endpoints to reconstruct chat UI or clear session data.

GET/chat/history/{conv_id}

Last 20 msgs

DELETE/chat/history/{conv_id}

Clear Session

Status Registry

HTTP Code	Error Detail	Internal Cause
400	Bad Request	Document not ready or malformed query schema.
401	Unauthorized	JWT is expired or owner verification failed.
413	Payload Too Large	PDF binary exceeds `settings.MAX_FILE_SIZE_MB`.
429	Too Many Requests	Redis-enforced rate limiting / concurrency cap hit.