Overview
The Document Chat API allows you to ask questions about your ingested documents and receive answers grounded in your content. The API supports conversational memory, enabling follow-up questions that maintain context.Endpoint
Authentication
Include your API token in the Authorization header:Request
Headers
Body Parameters
Thinking Level
Thethinking_level parameter controls the model and thinking configuration used for answering questions:
Example Request
Example with Conversation Memory
Example with Specific Documents (using file_ids)
Example with Specific Documents (using file_names - deprecated)
Scope by folder
Passfolders to ask about everything in one or more folders:
- Each folder covers every source at or below it, in any processing status, read when the request arrives.
ContractscoversContracts/2026too. folderscombines withfile_ids: the scope is the union of both.- An empty list is no folder scope.
"folders": []behaves as iffolderswere omitted, so with nofile_idseither the call runs on the whole project. If you build the list in code, check for an empty list before sending. - A folder that holds no source refuses the whole request with
400 chat.folder_scope_empty, even when the other folders hold sources. - The top level (
"","/") is not a folder: to cover the whole project, omitfolders. A top-level entry, an invalid path, orfolderstogether withfile_namesanswers422 request.invalid. At most 1,000 entries. - The response echoes
folders: the folders the scope was resolved from, normalized and de-duplicated (nullwhen the request named none). A response to a request with a non-emptyfoldersthat has nofolderswas not scoped by folder: do not use it as if it were (see Checking that a folder was applied). The API has already recorded that unscoped turn in the conversation, so repeat the question withreset: trueor withoutconversation_id. - The scope applies to this call only. A follow-up in the same
conversation_idstates its own scope (sendfoldersagain to keep it).
Folders are available on the REST API today. In the SDKs they land in the next releases: Python
graphor 0.28.0, TypeScript graphor 0.25.0 and the MCP package graphor-mcp 0.25.0. The folder methods, parameters and response fields shown for the SDKs need those versions or later; the hosted remote MCP server offers the folder tools once it runs graphor-mcp 0.25.0.Example with Thinking Level
Example with Citations and Inline Images
Setinclude_citation_images: true to get base64 screenshots of every cited page in the same response. Use sparingly — see Should I use include_citation_images?.
Example with Structured Output (JSON Schema)
When you passoutput_schema, the API will attempt to return a schema-conformant JSON object/array in structured_output.
Notes/constraints:
- Supported schemas must be simplified JSON Schema
- Unions must be only with
null(e.g.["string", "null"]) - Complex constructs like
oneOf/anyOf/allOf/$refare not supported
Response
Success Response (200 OK)
Citations
Each entry incitations corresponds to one [N] marker that appears in the answer text. Use index to map markers to citation entries.
Should I use include_citation_images?
The flag is convenient for quick prototyping or one-off requests where the client wants the answer and the visual previews in a single round-trip.
For real applications — especially when answers commonly cite many pages — prefer include_citation_images=false (the default) and lazy-load the screenshots on demand via the dedicated endpoint described in Get Page Screenshot. Reasons:
- Payload size: each base64 PNG is typically 100-400 KB. Five citations can push the JSON response above a megabyte and slow down clients.
- Latency: rendering screenshots is parallel but still adds seconds to the response — every page render is I/O + image processing. With the default flag off, the answer comes back as soon as the model finishes.
- Cache locality: the screenshot endpoint sets
Cache-Control: public, max-age=3600and is keyed by(file_id, page_number). Lazy-loading lets browsers and CDNs cache the bytes; inlining base64 prevents that.
include_citation_images=true only when you control both ends and know the answer will cite at most 1-2 pages (e.g. a confirmation step in a workflow). Otherwise, ship the answer with structured citations and fetch images on hover/click.
Example Response
Example Response (Structured Output)
Error Responses
Failures after the response started
A long answer streams whitespace first to keep the connection open. A failure after that point cannot change the HTTP status, so it arrives as a200 response whose JSON body is an error instead of an answer:
status_code before reading the result: when present, treat the body as an error with that status. detail can be a string or an object, and code depends on what failed, so key your handling on status_code and retryable: retry only when retryable is true (after retry_after seconds when set). reference is present when there is one to quote to support. The SDKs raise the matching error for you.
Usage Examples
Python
JavaScript
Best Practices
- Use conversation memory — Pass
conversation_idfor follow-up questions to maintain context - Be specific — Clear, specific questions get better answers
- Scope when needed — Use
file_idsto focus on specific documents, orfoldersto cover everything in a folder - Use structured output when integrating — Provide
output_schemato get JSON you can reliably parse in code - Reset when changing topics — Set
reset: truewhen switching to unrelated questions - Lazy-load citation images — Keep
include_citation_images=false(the default) and fetch page screenshots on demand via Get Page Screenshot. Inlining base64 only makes sense for low-citation, low-frequency requests — for typical chat UIs it bloats the payload by hundreds of KB per cited page. - Parse
citations, not the markup — Use the structuredcitationsarray to render references. The inline[N](file_id|pX|...)markup is hidden by default and is an implementation detail that may change.
Related
Get Page Screenshot
Fetch base64 screenshots for citations on demand
Document Chat Guide
Learn best practices for chatting with your documents
Data Ingestion
Improve parsing quality for better chat responses

