Chat API - Graphor Docs

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

POST https://sources.graphorlm.com/ask-sources

Authentication

Include your API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Request

Headers

Header	Value	Required
`Authorization`	`Bearer YOUR_API_TOKEN`	Yes
`Content-Type`	`application/json`	Yes

Body Parameters

Parameter	Type	Required	Description
`question`	string	Yes	The question to ask about your documents
`conversation_id`	string	No	Conversation identifier to maintain memory context across questions
`reset`	boolean	No	When `true`, starts a new conversation and ignores previous history. Default: `false`
`file_ids`	string[]	No	Restrict search to specific documents by file ID (preferred)
`file_names`	string[]	No	Restrict search to specific documents by file name (deprecated, use `file_ids`)
`output_schema`	object (JSON Schema)	No	Optional JSON Schema to request a structured output. When provided, the API returns validated structured data in `structured_output` and the raw JSON-text candidate in `raw_json`.
`thinking_level`	string	No	Controls model and thinking configuration. Values: `"fast"`, `"balanced"`, `"accurate"` (default). See Thinking Level for details.
`include_citation_images`	boolean	No	When `true`, populates `image_base64` (base64-encoded PNG of the cited page) inside each entry of `citations`. Default: `false`. See Citations for guidance.
`include_citation_markup`	boolean	No	When `true`, the `answer` field keeps the raw structured citation markup `[N](file_id\|pX\|sY\|eZ\|fNAME)` emitted by the agent instead of stripping it down to plain `[N]` markers. Default: `false`. The structured markup format is an implementation detail and may change — prefer parsing the `citations` array. Has no effect when `output_schema` is set.

Thinking Level

The thinking_level parameter controls the model and thinking configuration used for answering questions:

Value	Description
`"fast"`	Uses a faster model without extended thinking. Best for simple questions where speed is prioritized.
`"balanced"`	Uses a more capable model with low thinking. Good balance between quality and speed.
`"accurate"`	Default. Uses a more capable model with high thinking. Best for complex questions requiring deep reasoning.

Example Request

curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the main findings in this report?"
  }'

Example with Conversation Memory

# First question
curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What products are mentioned in the catalog?"
  }'

# Response: { "answer": "...", "conversation_id": "conv_abc123" }

# Follow-up question using conversation_id
curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which one is the most expensive?",
    "conversation_id": "conv_abc123"
  }'

Example with Specific Documents (using file_ids)

curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the total amount due?",
    "file_ids": ["file_abc123", "file_def456"]
  }'

Example with Specific Documents (using file_names - deprecated)

curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the total amount due?",
    "file_names": ["invoice-2024.pdf", "invoice-2023.pdf"]
  }'

Example with Thinking Level

curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Analyze the legal implications of the termination clause",
    "file_names": ["contract.pdf"],
    "thinking_level": "accurate"
  }'

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?.

curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What was the revenue in 2025?",
    "file_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "include_citation_images": true
  }'

For most cases, leave the flag off and fetch screenshots on demand:

# 1. Ask the question
curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "question": "What was the revenue in 2025?" }'

# 2. For each citation the user actually inspects, fetch the page image
curl "https://sources.graphorlm.com/{file_id}/pages/{page_number}/screenshot" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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

curl -X POST "https://sources.graphorlm.com/ask-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Extract the invoice number and total amount due.",
    "file_names": ["invoice-2024.pdf"],
    "output_schema": {
      "type": "object",
      "properties": {
        "invoice_number": { "type": ["string", "null"] },
        "total_amount_due": { "type": ["number", "null"] },
        "currency": { "type": ["string", "null"] }
      }
    }
  }'

Response

Success Response (200 OK)

Field	Type	Description
`answer`	string	The answer to your question, with inline `[N]` markers pointing to entries in `citations`. When `output_schema` is provided, this is a short status message and the structured data is in `structured_output` (raw JSON-text in `raw_json`).
`structured_output`	any	Optional structured output validated against the requested `output_schema`. Present only when `output_schema` is provided.
`raw_json`	string	Optional raw JSON-text produced by the model before validation/correction. Present only when `output_schema` is provided.
`conversation_id`	string	Conversation identifier for follow-up questions
`citations`	object[]	Structured citations resolving each `[N]` marker in `answer`. See Citations. May be `null`/empty when the agent did not ground its answer (e.g. small-talk follow-ups).
`usage`	object	Token usage breakdown for the request
`elapsed_s`	number	Wall-clock time in seconds

Citations

Each entry in citations corresponds to one [N] marker that appears in the answer text. Use index to map markers to citation entries.

Field	Type	Description
`index`	integer	The 1-based citation number that appears as `[N]` in `answer`
`file_id`	string	Unique identifier of the source file
`file_name`	string	Display name of the source file
`page_number`	integer	1-based page number where the cited content appears
`section_number`	integer	Optional section number within the page
`element_id`	string	Optional element identifier (e.g. specific paragraph or table)
`text_preview`	string	Short text excerpt around the cited content
`image_base64`	string	Base64-encoded PNG screenshot of the cited page. Populated only when the request used `include_citation_images=true`. May be `null` if the source is not visualizable (e.g. plain text).

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

{
  "answer": "Revenue grew 23% year-over-year, reaching $4.2B [1]. The strongest segment was digital services, which contributed 38% of total revenue [2].",
  "conversation_id": "conv_abc123",
  "citations": [
    {
      "index": 1,
      "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "file_name": "annual-report-2025.pdf",
      "page_number": 12,
      "section_number": 2,
      "element_id": "p-7",
      "text_preview": "Revenue grew by 23% year-over-year, reaching $4.2 billion…",
      "image_base64": null
    },
    {
      "index": 2,
      "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "file_name": "annual-report-2025.pdf",
      "page_number": 18,
      "section_number": null,
      "element_id": null,
      "text_preview": "Digital services contributed 38% of total revenue…",
      "image_base64": null
    }
  ]
}

Example Response (Structured Output)

{
  "answer": "Structured output generated.",
  "structured_output": {
    "invoice_number": "INV-2024-001",
    "total_amount_due": 1299.5,
    "currency": "USD"
  },
  "raw_json": "{\n  \"invoice_number\": \"INV-2024-001\",\n  \"total_amount_due\": 1299.50,\n  \"currency\": \"USD\"\n}",
  "conversation_id": "conv_abc123"
}

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API token
404	Not Found - Specified file not found
422	Unprocessable Entity - Invalid `output_schema` or structured output validation failed
500	Internal Server Error

Usage Examples

Python

import requests

url = "https://sources.graphorlm.com/ask-sources"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}

# Simple question
response = requests.post(url, headers=headers, json={
    "question": "What are the key terms in this contract?"
})

data = response.json()
print(data["answer"])

# Follow-up question
response = requests.post(url, headers=headers, json={
    "question": "When does it expire?",
    "conversation_id": data["conversation_id"]
})

print(response.json()["answer"])

JavaScript

const API_URL = "https://sources.graphorlm.com/ask-sources";
const API_TOKEN = "YOUR_API_TOKEN";

async function askQuestion(
  question,
  conversationId = null,
  fileNames = null,
  outputSchema = null
) {
  const payload = {
    question,
    conversation_id: conversationId
  };

  if (fileNames && fileNames.length) {
    payload.file_names = fileNames;
  }

  if (outputSchema) {
    payload.output_schema = outputSchema;
  }

  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  });
  
  return response.json();
}

// Usage
const result = await askQuestion("What products are available?");
console.log(result.answer);

// Follow-up
const followUp = await askQuestion(
  "Tell me more about the first one", 
  result.conversation_id
);
console.log(followUp.answer);

Best Practices

Use conversation memory — Pass conversation_id for follow-up questions to maintain context
Be specific — Clear, specific questions get better answers
Scope when needed — Use file_ids to focus on specific documents
Use structured output when integrating — Provide output_schema to get JSON you can reliably parse in code
Reset when changing topics — Set reset: true when 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 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

​Overview

​Endpoint

​Authentication

​Request

​Headers

​Body Parameters

​Thinking Level

​Example Request

​Example with Conversation Memory

​Example with Specific Documents (using file_ids)

​Example with Specific Documents (using file_names - deprecated)

​Example with Thinking Level

​Example with Citations and Inline Images

​Example with Structured Output (JSON Schema)

​Response

​Success Response (200 OK)

​Citations

​Should I use include_citation_images?

​Example Response

​Example Response (Structured Output)

​Error Responses

​Usage Examples

​Python

​JavaScript

​Best Practices

​Related