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
Passfolders 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.
ContractscoversContracts/2026too. folderscombines withfile_ids: the scope is the union of both.- An empty list is no folder scope.
"folders": []behaves as iffolderswere omitted, so with nofile_idseither 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, omitfolders. A top-level entry, an invalid path, orfolderstogether withfile_namesanswers422 request.invalid. At most 1,000 entries. - The response echoes
folders: the folders the scope was resolved from, normalized and de-duplicated (nullwhen the request named none). A response to a request with a non-emptyfoldersthat has nofolderswas 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 thechunks 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:- 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_ids for focused search — Restrict to specific documents when you know the source, or use
foldersto search everything in a folder - 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
Related
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

