Skip to main content

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

The thinking_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

Pass folders 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. Contracts covers Contracts/2026 too.
  • folders combines with file_ids: the scope is the union of both.
  • An empty list is no folder scope. "folders": [] behaves as if folders were omitted, so with no file_ids either 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, omit folders. A top-level entry, an invalid path, or folders together with file_names answers 422 request.invalid. At most 1,000 entries.
  • The response echoes folders: the folders the scope was resolved from, normalized and de-duplicated (null when the request named none). A response to a request with a non-empty folders that has no folders was 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 with reset: true or without conversation_id.
  • The scope applies to this call only. A follow-up in the same conversation_id states its own scope (send folders again 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

Set include_citation_images: true to get base64 screenshots of every cited page in the same response. Use sparingly — see Should I use include_citation_images?.
For most cases, leave the flag off and fetch screenshots on demand:

Example with Structured Output (JSON Schema)

When you pass output_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/$ref are not supported

Response

Success Response (200 OK)

Citations

Each entry in citations 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=3600 and is keyed by (file_id, page_number). Lazy-loading lets browsers and CDNs cache the bytes; inlining base64 prevents that.
A good rule of thumb: enable 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 a 200 response whose JSON body is an error instead of an answer:
Check for 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

  1. Use conversation memory — Pass conversation_id for follow-up questions to maintain context
  2. Be specific — Clear, specific questions get better answers
  3. Scope when needed — Use file_ids to focus on specific documents, or folders to cover everything in a folder
  4. Use structured output when integrating — Provide output_schema to get JSON you can reliably parse in code
  5. Reset when changing topics — Set reset: true when switching to unrelated questions
  6. 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.
  7. Parse citations, not the markup — Use the structured citations array to render references. The inline [N](file_id|pX|...) markup is hidden by default and is an implementation detail that may change.

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