Pydantic Data Models Reference for PDF Insight Pro API

All request and response bodies in PDF Insight Pro are validated by Pydantic v2 models defined in models/models.py. Every field is typed, and required fields will produce a 422 Unprocessable Entity response if omitted or malformed. This page documents every public model used across the REST API — from the chat and upload endpoints down to the internal document-processing structures.

Request Models

`ChatRequest`

Sent as the JSON body of POST /chat. Specifies the session to query, the user’s question, and optional controls for web-search augmentation and model selection.

session_id

string

required

The session identifier returned by POST /upload-pdf. Every chat turn must reference a valid, active session.

query

string

required

The natural-language question to ask about the uploaded document. Must be at least 3 characters after stripping leading/trailing whitespace; blank or very short queries are rejected with 400 Bad Request.

use_search

boolean

default:"false"

When true, the agent augments its answer with results from a Tavily web-search tool call in addition to the local FAISS vector index. Requires TAVILY_API_KEY to be configured on the server.

model_name

string

default:"meta-llama/llama-4-scout-17b-16e-instruct"

The Groq model ID to use for response generation. Must be one of the IDs listed by GET /models. Defaults to Llama 4 Scout 17B if omitted.

`SessionRequest`

Sent as the JSON body of /chat-history, /clear-history, and /remove-pdf. Identifies the session to act on.

session_id

string

required

The session identifier returned by POST /upload-pdf.

Response Models

`UploadResponse`

Returned by a successful POST /upload-pdf call.

status

string

Always "success" on a successful upload.

session_id

string

A UUID string that uniquely identifies the newly created session. Pass this value as session_id in all subsequent requests.

message

string

A human-readable confirmation message, e.g. "Processed report.pdf".

`ChatResponse`

Returned by a successful POST /chat call.

status

string

Always "success" on a successful response.

answer

string

The LLM-generated answer to the user’s query, grounded in the retrieved document context and (optionally) web-search results.

context_used

array of objects

The document chunks retrieved from the FAISS index and passed to the LLM as context for this turn.

Show context_used item

text

string

The raw text content of the retrieved chunk.

score

float

The FAISS L2 distance score for this chunk relative to the query embedding. Lower values indicate higher similarity — a score of 0.0 would be a perfect match.

metadata

object

Source metadata attached to the chunk at indexing time. Typically contains page (integer page number within the PDF) and source (the original filename).

`ChatHistoryResponse`

Returned by POST /chat-history.

status

string

Always "success" when the session is found.

history

array of objects

The ordered conversation history for the session. Each item represents one exchange.

Show history item

user

string

The user’s original query text for this turn.

assistant

string

The assistant’s generated answer for this turn.

`StatusResponse`

Returned by both /clear-history and /remove-pdf on success.

status

string

Always "success" when the operation completes.

message

string

A human-readable description of the outcome, for example "Chat history cleared" or "PDF file and session removed successfully".

`ModelsResponse`

Returned by GET /models.

models

array of ModelInfo

The list of Groq models available for use as model_name in ChatRequest.

Show ModelInfo

string

The model identifier string to supply as model_name in a ChatRequest, e.g. "meta-llama/llama-4-scout-17b-16e-instruct".

name

string

A short human-readable display name, e.g. "Llama 4 Scout 17B".

`ErrorResponse`

Returned whenever the API cannot fulfil a request. The status field distinguishes application-level errors from HTTP transport errors.

status

string

A short error category string such as "error".

detail

string

A human-readable description of what went wrong. Matches the detail string in FastAPI’s HTTPException format.

type

string

Optional. A machine-readable error type token for programmatic error handling. May be omitted when not applicable.

Internal Models

The following models are used internally by the application’s processing pipeline. They are not returned directly by any public endpoint but appear as nested structures in responses or are used during PDF ingestion and chunk retrieval.

`DocumentChunk`

Represents a single processed chunk of text extracted from a PDF, as it moves through the ingestion pipeline.

Field	Type	Description
`text`	`string`	The raw text content of this chunk.
`metadata`	`ChunkMetadata`	Structured metadata about the chunk’s origin.

`ChunkMetadata`

Metadata attached to each DocumentChunk at ingestion time and stored alongside the FAISS vectors.

Field	Type	Description
`source`	`string \| null`	The originating filename or file path.
`page`	`int \| null`	The zero- or one-indexed page number within the source PDF.

ChunkMetadata is configured with Config.extra = "allow", meaning the model accepts and preserves any additional metadata fields that the PDF loader or chunking pipeline may attach beyond source and page.

Example Request Payloads

The following examples show valid JSON bodies for every request model. ChatRequest — full payload with web search enabled

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "query": "What are the key findings in the executive summary?",
  "use_search": true,
  "model_name": "meta-llama/llama-4-scout-17b-16e-instruct"
}

ChatRequest — minimal payload (defaults applied for use_search and model_name)

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "query": "Summarise section 3"
}

SessionRequest — used for /chat-history, /clear-history, /remove-pdf

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Endpoints

Data Models

Pydantic Data Models Reference for PDF Insight Pro API

Request Models

`ChatRequest`

`SessionRequest`

Response Models

`UploadResponse`

`ChatResponse`

`ChatHistoryResponse`

`StatusResponse`

`ModelsResponse`

`ErrorResponse`

Internal Models

`DocumentChunk`

`ChunkMetadata`

Example Request Payloads

Build docs developers (and LLMs) love

Endpoints

Data Models

Documentation Index

​Request Models

​ChatRequest

​SessionRequest

​Response Models

​UploadResponse

​ChatResponse

​ChatHistoryResponse

​StatusResponse

​ModelsResponse

​ErrorResponse

​Internal Models

​DocumentChunk

​ChunkMetadata

​Example Request Payloads

Build docs developers (and LLMs) love

Request Models

`ChatRequest`

`SessionRequest`

Response Models

`UploadResponse`

`ChatResponse`

`ChatHistoryResponse`

`StatusResponse`

`ModelsResponse`

`ErrorResponse`

Internal Models

`DocumentChunk`

`ChunkMetadata`

Example Request Payloads