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

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

​
Authentication

Include your API token in the Authorization header: 
Authorization: Bearer YOUR_API_TOKEN

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer YOUR_API_TOKENYes
Content-Typeapplication/jsonYes

​
Body Parameters

ParameterTypeRequiredDescription
questionstringYesThe question to ask about your documents
conversation_idstringNoConversation identifier to maintain memory context across questions
resetbooleanNoWhen true, starts a new conversation and ignores previous history. Default: false
file_namesstring[]NoRestrict search to specific documents by file name

​
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

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"]
  }'

​
Response

​
Success Response (200 OK)

FieldTypeDescription
answerstringThe answer to your question, grounded in document content
conversation_idstringConversation identifier for follow-up questions

​
Example Response

{
  "answer": "The main findings in the report indicate that revenue increased by 15% year-over-year, with the strongest growth in the digital services segment. The report also highlights three key challenges: supply chain disruptions, increased competition, and regulatory changes.",
  "conversation_id": "conv_abc123"
}

​
Error Responses

Status CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API token
404Not Found - Specified file not found
500Internal 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) {
  const payload = {
    question,
    conversation_id: conversationId
  };

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

  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

  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_names to focus on specific documents
  4. Reset when changing topics — Set reset: true when switching to unrelated questions

Document Chat Guide

Learn best practices for chatting with your documents

Data Ingestion

Improve parsing quality for better chat responses