Prebuilt RAG API

Overview

The Prebuilt RAG API allows you to retrieve relevant document chunks from your ingested documents using semantic search. It returns the most relevant content for your query, making it ideal for building custom applications.

Endpoint

POST https://sources.graphorlm.com/prebuilt-rag

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
`query`	string	Yes	The search query to retrieve relevant chunks
`file_ids`	string[]	No	Restrict retrieval to specific documents by file ID (preferred)
`file_names`	string[]	No	Restrict retrieval to specific documents by file name (deprecated, use `file_ids`)

Example Request

curl -X POST "https://sources.graphorlm.com/prebuilt-rag" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the payment terms?"
  }'

Example with Specific Documents (using file_ids)

curl -X POST "https://sources.graphorlm.com/prebuilt-rag" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "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/prebuilt-rag" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the total amount due?",
    "file_names": ["invoice-2024.pdf", "invoice-2023.pdf"]
  }'

Response

Success Response (200 OK)

Field	Type	Description
`query`	string	The original search query
`chunks`	array	List of retrieved document chunks
`total`	integer	Total number of chunks retrieved

Chunk Object

Each chunk in the chunks array contains:

Field	Type	Description
`text`	string	The text content of the chunk
`file_id`	string	The unique identifier of the source file
`file_name`	string	The source file name
`page_number`	integer	The page number where the chunk was found
`score`	float	The relevance score of the chunk (higher is more relevant)
`metadata`	object	Additional metadata for the chunk

Example Response

{
  "query": "What are the payment terms?",
  "chunks": [
    {
      "text": "Payment Terms: Net 30 days from invoice date. Late payments will incur a 1.5% monthly interest charge. All payments must be made in USD via wire transfer or check.",
      "file_id": "file_abc123",
      "file_name": "contract-2024.pdf",
      "page_number": 5,
      "score": 0.95,
      "metadata": {
        "file_id": "file_abc123",
        "file_name": "contract-2024.pdf",
        "page_number": 5
      }
    },
    {
      "text": "The Client agrees to pay all invoices within thirty (30) days of receipt. Failure to pay within the specified period may result in suspension of services.",
      "file_id": "file_abc123",
      "file_name": "contract-2024.pdf",
      "page_number": 12,
      "score": 0.87,
      "metadata": {
        "file_id": "file_abc123",
        "file_name": "contract-2024.pdf",
        "page_number": 12
      }
    }
  ],
  "total": 2
}

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API token
404	Not Found - Specified file not found
500	Internal Server Error

Usage Examples

Python

import requests

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

# Basic retrieval
response = requests.post(url, headers=headers, json={
    "query": "What are the key contract terms?"
})

data = response.json()
print(f"Found {data['total']} relevant chunks")

for chunk in data["chunks"]:
    print(f"\n--- {chunk['file_name']} (page {chunk['page_number']}) ---")
    print(chunk["text"])
    print(f"Relevance: {chunk['score']:.2f}")

Python with Custom LLM Integration

import requests
from openai import OpenAI

# Step 1: Retrieve relevant chunks
def retrieve_chunks(query, file_names=None):
    url = "https://sources.graphorlm.com/prebuilt-rag"
    headers = {
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Content-Type": "application/json"
    }
    payload = {"query": query}
    if file_names:
        payload["file_names"] = file_names
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Step 2: Build context from chunks
def build_context(chunks):
    context = ""
    for chunk in chunks["chunks"]:
        context += f"\n[Source: {chunk['file_name']}, Page {chunk['page_number']}]\n"
        context += chunk["text"] + "\n"
    return context

# Step 3: Generate answer with your preferred LLM
def generate_answer(question, context):
    client = OpenAI()
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "Answer questions based on the provided context."},
            {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"}
        ]
    )
    return response.choices[0].message.content

# Usage
question = "What are the payment terms?"
chunks = retrieve_chunks(question)
context = build_context(chunks)
answer = generate_answer(question, context)
print(answer)

JavaScript

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

async function retrieveChunks(query, fileNames = null) {
  const payload = { query };
  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 retrieveChunks("What products are mentioned?");
console.log(`Found ${result.total} relevant chunks`);

result.chunks.forEach(chunk => {
  console.log(`\n--- ${chunk.file_name} (page ${chunk.page_number}) ---`);
  console.log(chunk.text);
  console.log(`Relevance: ${chunk.score}`);
});

JavaScript with Custom LLM Integration

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

async function retrieveChunks(query, fileNames = null) {
  const payload = { query };
  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();
}

function buildContext(chunks) {
  return chunks.chunks.map(chunk => 
    `[Source: ${chunk.file_name}, Page ${chunk.page_number}]\n${chunk.text}`
  ).join("\n\n");
}

async function generateAnswer(question, context) {
  // Use your preferred LLM API (OpenAI, Anthropic, etc.)
  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${OPENAI_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-4",
      messages: [
        { role: "system", content: "Answer questions based on the provided context." },
        { role: "user", content: `Context:\n${context}\n\nQuestion: ${question}` }
      ]
    })
  });
  
  const data = await response.json();
  return data.choices[0].message.content;
}

// Full RAG pipeline
async function askQuestion(question, fileNames = null) {
  const chunks = await retrieveChunks(question, fileNames);
  const context = buildContext(chunks);
  const answer = await generateAnswer(question, context);
  return { answer, sources: chunks.chunks };
}

// Usage
const result = await askQuestion("What are the payment terms?");
console.log(result.answer);
console.log("Sources:", result.sources.map(s => s.file_name));

Use Cases

Custom Applications with Your LLM

Use this API to build custom features with your preferred LLM:

Retrieve relevant chunks using semantic search
Build context from the retrieved chunks
Generate answers using any LLM (OpenAI, Anthropic, Google, etc.)

Document Search

Build document search interfaces that show relevant excerpts:

Query for relevant content
Display chunks with file names and page numbers
Allow users to navigate to source documents

Knowledge Base Q&A

Create custom Q&A systems with full control over:

Prompt engineering
Response formatting
Source citations
Multi-step reasoning

Best Practices

Be specific in queries — Clear, specific queries return more relevant chunks
Use file_names for focused search — Restrict to specific documents when you know the source
Check relevance scores — Higher scores indicate better matches; consider filtering low-score chunks
Include source citations — Use file_name and page_number to cite sources in your responses
Combine with LLM — Use retrieved chunks as context for LLM-generated answers

Comparison with Chat API

Feature	Prebuilt RAG API	Chat API
Returns	Raw document chunks	Generated answer
LLM Integration	Bring your own	Built-in
Conversation Memory	No	Yes
Customization	Full control	Limited
Use Case	Custom retrieval + generation	Quick Q&A

Chat API

Get AI-generated answers with built-in LLM

Data Ingestion

Improve parsing quality for better retrieval results

Extraction API

Extract structured data from documents

Get Started

Data API Options

Overview

Endpoint

Authentication

Request

Headers

Body Parameters

Example Request

Example with Specific Documents (using file_ids)

Example with Specific Documents (using file_names - deprecated)

Response

Success Response (200 OK)

Chunk Object

Example Response

Error Responses

Usage Examples

Python

Python with Custom LLM Integration

JavaScript

JavaScript with Custom LLM Integration

Use Cases

Custom Applications with Your LLM

Document Search

Knowledge Base Q&A

Best Practices

Comparison with Chat API

Chat API

Data Ingestion

Extraction API

​Overview

​Endpoint

​Authentication

​Request

​Headers

​Body Parameters

​Example Request

​Example with Specific Documents (using file_ids)

​Example with Specific Documents (using file_names - deprecated)

​Response

​Success Response (200 OK)

​Chunk Object

​Example Response

​Error Responses

​Usage Examples

​Python

​Python with Custom LLM Integration

​JavaScript

​JavaScript with Custom LLM Integration

​Use Cases

​Custom Applications with Your LLM

​Document Search

​Knowledge Base Q&A

​Best Practices

​Comparison with Chat API

​Related

Chat API

Data Ingestion

Extraction API

Overview

Endpoint

Authentication

Request

Headers

Body Parameters

Example Request

Example with Specific Documents (using file_ids)

Example with Specific Documents (using file_names - deprecated)

Response

Success Response (200 OK)

Chunk Object

Example Response

Error Responses

Usage Examples

Python

Python with Custom LLM Integration

JavaScript

JavaScript with Custom LLM Integration

Use Cases

Custom Applications with Your LLM

Document Search

Knowledge Base Q&A

Best Practices

Comparison with Chat API

Related