gmakstutis/LightRAG
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
LightRAG/docs/0003-api-reference.md
Raphael MANSUY 2b292d4924
docs: Enterprise Edition & Multi-tenancy attribution (#5) 
* Remove outdated documentation files: Quick Start Guide, Apache AGE Analysis, and Scratchpad.

* Add multi-tenant testing strategy and ADR index documentation

- Introduced ADR 008 detailing the multi-tenant testing strategy for the ./starter environment, covering compatibility and multi-tenant modes, testing scenarios, and implementation details.
- Created a comprehensive ADR index (README.md) summarizing all architecture decision records related to the multi-tenant implementation, including purpose, key sections, and reading paths for different roles.

* feat(docs): Add comprehensive multi-tenancy guide and README for LightRAG Enterprise

- Introduced `0008-multi-tenancy.md` detailing multi-tenancy architecture, key concepts, roles, permissions, configuration, and API endpoints.
- Created `README.md` as the main documentation index, outlining features, quick start, system overview, and deployment options.
- Documented the LightRAG architecture, storage backends, LLM integrations, and query modes.
- Established a task log (`2025-01-21-lightrag-documentation-log.md`) summarizing documentation creation actions, decisions, and insights.
2025-12-04 18:09:15 +08:00

15 KiB
Raw Blame History

LightRAG API Reference

Complete REST API documentation for LightRAG Server

Version: 1.4.9.1 | Base URL: http://localhost:9621

Table of Contents

  1. Authentication
  2. Query Endpoints
  3. Document Endpoints
  4. Graph Endpoints
  5. Admin Endpoints
  6. Multi-Tenant Headers
  7. Error Handling

Authentication

LightRAG supports multiple authentication methods:

API Key Authentication

Authorization: Bearer <API_KEY>

Basic Authentication

Authorization: Basic <base64(username:password)>

JWT Token (Multi-Tenant)

Authorization: Bearer <JWT_TOKEN>
X-Tenant-ID: <tenant_uuid>
X-KB-ID: <knowledge_base_uuid>

Query Endpoints

POST /query

Execute a RAG query and get a response.

POST /query
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "query": "What is the capital of France?",
  "mode": "mix",
  "only_need_context": false,
  "only_need_prompt": false,
  "response_type": "Multiple Paragraphs",
  "top_k": 40,
  "chunk_top_k": 20,
  "max_entity_tokens": 6000,
  "max_relation_tokens": 8000,
  "max_total_tokens": 30000,
  "conversation_history": [
    {"role": "user", "content": "Tell me about Europe"},
    {"role": "assistant", "content": "Europe is..."}
  ],
  "user_prompt": "Focus on historical context",
  "enable_rerank": true,
  "include_references": true
}

Parameters

Field Type Required Default Description
query string ✅ - Query text (min 3 chars)
mode string ❌ mix Query mode: local, global, hybrid, naive, mix, bypass
only_need_context bool ❌ false Return only context without LLM response
only_need_prompt bool ❌ false Return only generated prompt
response_type string ❌ Multiple Paragraphs Response format
top_k int ❌ 40 Number of entities/relations to retrieve
chunk_top_k int ❌ 20 Number of text chunks to retrieve
max_entity_tokens int ❌ 6000 Max tokens for entity context
max_relation_tokens int ❌ 8000 Max tokens for relation context
max_total_tokens int ❌ 30000 Total context token budget
conversation_history array ❌ [] Previous conversation turns
user_prompt string ❌ null Additional instructions for LLM
enable_rerank bool ❌ true Enable chunk reranking
include_references bool ❌ true Include reference list

Response

{
  "response": "Paris is the capital of France...",
  "references": [
    {"id": "doc-123", "title": "France Geography"},
    {"id": "doc-456", "title": "European Capitals"}
  ]
}

POST /query/stream

Stream a RAG query response (Server-Sent Events).

POST /query/stream
Content-Type: application/json
Authorization: Bearer <token>

Request Body

Same as /query

Response (NDJSON Stream)

{"references": [{"id": "doc-123", "title": "France"}]}
{"response": "Paris "}
{"response": "is "}
{"response": "the capital..."}

POST /query/data

Get structured query data with full context information.

POST /query/data
Content-Type: application/json
Authorization: Bearer <token>

Response

{
  "status": "success",
  "message": "Query completed",
  "data": {
    "entities": [
      {
        "entity_name": "Paris",
        "entity_type": "location",
        "description": "Capital city of France...",
        "source_id": "chunk-001"
      }
    ],
    "relationships": [
      {
        "source": "France",
        "target": "Paris",
        "description": "capital of",
        "keywords": "capital, city"
      }
    ],
    "chunks": [
      {
        "id": "chunk-001",
        "content": "Paris is the capital...",
        "file_path": "france.txt"
      }
    ],
    "references": [...]
  },
  "metadata": {
    "mode": "mix",
    "high_level_keywords": ["capital", "france"],
    "low_level_keywords": ["paris", "city"]
  }
}

Document Endpoints

POST /documents/text

Insert a single text document.

POST /documents/text
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "text": "Document content to insert...",
  "file_source": "manual_input.txt",
  "external_id": "unique-doc-id-123"
}

Response

{
  "status": "accepted",
  "message": "Text document accepted for processing",
  "doc_id": "abc123...",
  "track_id": "track_20251204_123456_xyz"
}

POST /documents/texts

Insert multiple text documents in batch.

POST /documents/texts
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "texts": [
    "First document content...",
    "Second document content..."
  ],
  "file_sources": ["doc1.txt", "doc2.txt"],
  "external_ids": ["id-001", "id-002"]
}

POST /documents/file

Upload a file for processing.

POST /documents/file
Content-Type: multipart/form-data
Authorization: Bearer <token>

Form Data

Field Type Description
file file File to upload (txt, md, pdf, docx)

Response

{
  "status": "uploaded",
  "message": "File uploaded successfully",
  "filename": "document.pdf",
  "track_id": "track_20251204_123456_xyz"
}

POST /documents/files

Upload multiple files for processing.

POST /documents/files
Content-Type: multipart/form-data
Authorization: Bearer <token>

POST /documents/scan

Scan and process all files in the input directory.

POST /documents/scan
Authorization: Bearer <token>

Response

{
  "status": "scanning_started",
  "message": "Scanning process initiated",
  "track_id": "scan_20251204_123456_xyz"
}

GET /documents

List all documents with pagination.

GET /documents?page=1&page_size=20&status=processed&sort_field=created_at&sort_order=desc
Authorization: Bearer <token>

Query Parameters

Parameter Type Default Description
page int 1 Page number
page_size int 20 Items per page (max 100)
status string - Filter by status: pending, processing, processed, failed
sort_field string created_at Sort field
sort_order string desc Sort order: asc, desc

Response

{
  "documents": [
    {
      "id": "abc123",
      "file_path": "document.txt",
      "status": "processed",
      "chunks_count": 15,
      "created_at": "2025-12-04T10:30:00Z",
      "updated_at": "2025-12-04T10:35:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

GET /documents/{doc_id}

Get document details by ID.

GET /documents/{doc_id}
Authorization: Bearer <token>

DELETE /documents/{doc_id}

Delete a document and its associated data.

DELETE /documents/{doc_id}
Authorization: Bearer <token>

Response

{
  "status": "success",
  "message": "Document deleted successfully",
  "details": {
    "doc_id": "abc123",
    "chunks_deleted": 15,
    "entities_affected": 23,
    "relations_affected": 12
  }
}

DELETE /documents

Clear all documents (dangerous operation).

DELETE /documents
Authorization: Bearer <token>

GET /documents/status/{track_id}

Get processing status for a tracking ID.

GET /documents/status/{track_id}
Authorization: Bearer <token>

Response

{
  "track_id": "track_20251204_123456_xyz",
  "status": "processing",
  "progress": 0.65,
  "current_step": "entity_extraction",
  "documents_processed": 5,
  "documents_total": 8,
  "errors": [],
  "started_at": "2025-12-04T10:30:00Z",
  "updated_at": "2025-12-04T10:35:00Z"
}

Graph Endpoints

GET /graph/label/list

Get all entity labels in the knowledge graph.

GET /graph/label/list
Authorization: Bearer <token>

Response

["Person", "Organization", "Location", "Event", "Concept"]

GET /graph/label/popular

Get popular labels sorted by node degree.

GET /graph/label/popular?limit=100
Authorization: Bearer <token>

Query Parameters

Parameter Type Default Max Description
limit int 300 1000 Max labels to return

GET /graph/label/search

Search labels with fuzzy matching.

GET /graph/label/search?q=apple&limit=50
Authorization: Bearer <token>

Query Parameters

Parameter Type Default Description
q string - Search query (required)
limit int 50 Max results

GET /graphs

Get knowledge graph subgraph for a label.

GET /graphs?label=Apple&max_depth=3&max_nodes=1000
Authorization: Bearer <token>

Query Parameters

Parameter Type Default Description
label string - Starting node label (required)
max_depth int 3 Maximum traversal depth
max_nodes int 1000 Maximum nodes to return

Response

{
  "nodes": [
    {
      "id": "apple-inc",
      "labels": ["Organization"],
      "properties": {
        "description": "Technology company...",
        "entity_type": "organization"
      }
    }
  ],
  "edges": [
    {
      "id": "edge-001",
      "source": "apple-inc",
      "target": "iphone",
      "type": "produces",
      "properties": {
        "description": "Apple produces iPhone",
        "weight": 5.0
      }
    }
  ],
  "is_truncated": false
}

PUT /graph/entity

Update an entity in the knowledge graph.

PUT /graph/entity
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "entity_name": "Apple Inc.",
  "updated_data": {
    "description": "Updated description...",
    "entity_type": "technology_company"
  },
  "allow_rename": false
}

PUT /graph/relation

Update a relationship in the knowledge graph.

PUT /graph/relation
Content-Type: application/json
Authorization: Bearer <token>

Request Body

{
  "source_id": "Apple Inc.",
  "target_id": "iPhone",
  "updated_data": {
    "description": "Designs and manufactures",
    "keywords": "technology, smartphone"
  }
}

DELETE /graph/entity/{entity_name}

Delete an entity from the knowledge graph.

DELETE /graph/entity/{entity_name}
Authorization: Bearer <token>

DELETE /graph/relation

Delete a relationship from the knowledge graph.

DELETE /graph/relation?source_id=Apple&target_id=iPhone
Authorization: Bearer <token>

Admin Endpoints

GET /health

Health check endpoint.

GET /health

Response

{
  "status": "healthy",
  "version": "1.4.9.1",
  "storage_status": "initialized",
  "llm_status": "connected",
  "embedding_status": "connected"
}

GET /health/storage

Detailed storage health check.

GET /health/storage
Authorization: Bearer <token>

POST /admin/drop

Drop all data from storages (destructive).

POST /admin/drop
Authorization: Bearer <token>

POST /documents/rebuild-index

Rebuild knowledge graph from cached extractions.

POST /documents/rebuild-index
Authorization: Bearer <token>

Multi-Tenant Headers

For multi-tenant deployments, include these headers:

Header Description Required
X-Tenant-ID Tenant UUID When multi-tenant enabled
X-KB-ID Knowledge Base UUID When multi-tenant enabled
X-User-ID User identifier For audit logging

Example Multi-Tenant Request

POST /query
Content-Type: application/json
Authorization: Bearer <jwt_token>
X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000
X-KB-ID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8

{
  "query": "What are our Q3 results?",
  "mode": "mix"
}

Error Handling

Error Response Format

{
  "detail": "Error description",
  "error_code": "ERROR_CODE",
  "request_id": "req-12345"
}

HTTP Status Codes

Code Description
200 Success
201 Created
202 Accepted (async processing started)
400 Bad Request (invalid input)
401 Unauthorized (missing/invalid auth)
403 Forbidden (insufficient permissions)
404 Not Found
422 Validation Error
429 Too Many Requests
500 Internal Server Error

Common Error Codes

Error Code Description
INVALID_QUERY Query text too short or invalid
DOCUMENT_NOT_FOUND Requested document doesn't exist
TENANT_NOT_FOUND Invalid tenant ID
KB_NOT_FOUND Invalid knowledge base ID
PROCESSING_FAILED Document processing failed
STORAGE_ERROR Database connection error
LLM_ERROR LLM provider error
RATE_LIMITED Too many requests

Rate Limiting

Default rate limits (configurable via environment):

Endpoint Category Limit
Query endpoints 60/minute
Document upload 20/minute
Batch operations 10/minute
Admin endpoints 5/minute

Ollama-Compatible API

LightRAG provides Ollama-compatible endpoints for integration with Ollama clients.

POST /api/generate

Ollama-compatible generation endpoint.

POST /api/generate
Content-Type: application/json

Request Body

{
  "model": "lightrag",
  "prompt": "What is the capital of France?",
  "stream": false
}

POST /api/chat

Ollama-compatible chat endpoint.

POST /api/chat
Content-Type: application/json

Request Body

{
  "model": "lightrag",
  "messages": [
    {"role": "user", "content": "Tell me about Paris"}
  ],
  "stream": true
}

GET /api/tags

List available models.

GET /api/tags

WebUI

Access the built-in web interface at:

http://localhost:9621/webui

Features:

  • Document management
  • Knowledge graph visualization
  • Query interface
  • System configuration

OpenAPI Documentation

Interactive API documentation available at:

  • Swagger UI: http://localhost:9621/docs
  • ReDoc: http://localhost:9621/redoc
  • OpenAPI JSON: http://localhost:9621/openapi.json

Version: 1.4.9.1 | License: MIT