Skip to main content

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

Authentication

Include your API token in the Authorization header:

Request

Headers

Body Parameters

Example Request

Example with Specific Documents (using file_ids)

Example with Specific Documents (using file_names - deprecated)

Scope by folder

Pass folders to search 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).
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.

Response

Success Response (200 OK)

Chunk Object

Each chunk in the chunks array contains:

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

Use this API to build custom features with your preferred LLM:
  1. Retrieve relevant chunks using semantic search
  2. Build context from the retrieved chunks
  3. Generate answers using any LLM (OpenAI, Anthropic, Google, etc.)
Build document search interfaces that show relevant excerpts:
  1. Query for relevant content
  2. Display chunks with file names and page numbers
  3. 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

  1. Be specific in queries — Clear, specific queries return more relevant chunks
  2. Use file_ids for focused search — Restrict to specific documents when you know the source, or use folders to search everything in a folder
  3. Check relevance scores — Higher scores indicate better matches; consider filtering low-score chunks
  4. Include source citations — Use file_name and page_number to cite sources in your responses
  5. Combine with LLM — Use retrieved chunks as context for LLM-generated answers

Comparison with Chat API

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