API Documentation

Complete reference for integrating HeyRAG into your applications

Quick Start
Get started with the HeyRAG API in minutes

1. Get API Key

Create an API key in the API Keys section

2. Upload Documents

POST files to /api/v1/documents

3. Query Documents

POST queries to /api/v1/query

Base URL

https://your-domain.com/api/v1

Authentication

curl https://your-domain.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY"
Document Endpoints
Upload, list, and manage documents
POST/api/v1/documentsAPI Key

Upload a new document for processing

Request

curl -X POST https://your-domain.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"

Response

{
  "success": true,
  "data": {
    "document_id": "abc123",
    "file_name": "document.pdf",
    "status": "pending"
  }
}
GET/api/v1/documentsAPI Key

List all documents with pagination

Request

curl https://your-domain.com/api/v1/documents?page=1&limit=20 \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/api/v1/documents/:idAPI Key

Get details for a specific document

DELETE/api/v1/documents/:idAPI Key

Delete a document and all associated data

SDK Examples
Quick code snippets in popular languages
// Upload a document
const formData = new FormData();
formData.append('file', file);

const uploadRes = await fetch('/api/v1/documents', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: formData,
});

// Query documents
const queryRes = await fetch('/api/v1/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'What are the main topics?',
    mode: 'mix',
    top_k: 10,
  }),
});

const result = await queryRes.json();
console.log(result.data.response);
Response Format
All API responses follow a consistent format

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "uuid",
    "usage": {
      "input_tokens": 100,
      "output_tokens": 50
    }
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Query is required",
    "details": { ... }
  },
  "meta": {
    "request_id": "uuid"
  }
}