Documents API

The Documents API provides endpoints for document upload, processing, and GraphRAG-based querying.

Overview

Endpoint	Method	Description
/documents/upload	POST	Upload and process a document
/documents/query	POST	Semantic search with GraphRAG
/documents/list	GET	List documents for tenant
/documents/{id}	GET	Get document details
/documents/{id}	DELETE	Delete a document
/documents/initialize-indexes	POST	Create vector indexes

---

Upload Document

Upload a file for processing, chunking, embedding, and storage in the knowledge graph.

POST /documents/upload
Content-Type: multipart/form-data
X-JWT-Token: <jwt_token>

Parameters

Parameter	Type	Required	Description
file	File	Yes	The document to upload
project_id	string	No	Project to associate document with
tags	string	No	Comma-separated tags
extract_entities	boolean	No	Extract and link entities (default: true)
chunking_strategy	string	No	Chunking method (default: "recursive")
chunk_size	integer	No	Target chunk size in characters (default: 1000)

Supported File Types

• PDF (.pdf)
• Excel (.xlsx, .xls)
• Text (.txt)
• CSV (.csv)
• Markdown (.md)

Example Request

curl -X POST "http://localhost:3007/documents/upload" \
  -H "X-JWT-Token: $JWT_TOKEN" \
  -F "file=@report.pdf" \
  -F "project_id=proj-123" \
  -F "tags=quarterly,finance" \
  -F "chunking_strategy=recursive"

Example Response

{
  "document_id": "doc_a1b2c3d4e5f6",
  "filename": "report.pdf",
  "file_type": "pdf",
  "file_size": 245678,
  "chunk_count": 15,
  "entity_count": 8,
  "message": "Document processed successfully"
}

---

Query Documents

Perform semantic search across documents using GraphRAG.

POST /documents/query
Content-Type: application/json
X-JWT-Token: <jwt_token>

Request Body

{
  "query": "What are the key findings from the quarterly report?",
  "top_k": 5,
  "mode": "hybrid",
  "document_id": null,
  "include_context": true
}

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	-	Natural language query
top_k	integer	No	5	Number of results to return
mode	string	No	"hybrid"	Retrieval mode
document_id	string	No	null	Filter to specific document
include_context	boolean	No	true	Include formatted context

Retrieval Modes

Mode	Description
vector_only	Pure semantic similarity search
graph_only	Graph-based context retrieval
hybrid	Combined vector + graph (recommended)
graph_expanded	Vector seed with graph expansion

Example Response

{
  "query_id": "qry_x7y8z9",
  "query": "What are the key findings?",
  "results": [
    {
      "chunk_id": "chunk_abc123",
      "document_id": "doc_a1b2c3d4e5f6",
      "text": "The key findings from Q4 include a 15% increase in...",
      "score": 0.89,
      "metadata": {
        "page_number": 3,
        "filename": "report.pdf"
      }
    }
  ],
  "context": "Based on the quarterly report:\n\nThe key findings from Q4 include...",
  "total_results": 5
}

---

List Documents

Get all documents for the current tenant.

GET /documents/list?limit=20&offset=0
X-JWT-Token: <jwt_token>

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Maximum documents to return
offset	integer	0	Pagination offset
project_id	string	null	Filter by project

Example Response

{
  "documents": [
    {
      "document_id": "doc_a1b2c3d4e5f6",
      "filename": "report.pdf",
      "file_type": "pdf",
      "file_size": 245678,
      "chunk_count": 15,
      "created_at": "2026-01-12T10:30:00Z",
      "project_id": "proj-123",
      "tags": ["quarterly", "finance"]
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

---

Get Document

Get details for a specific document.

GET /documents/{document_id}
X-JWT-Token: <jwt_token>

Example Response

{
  "document_id": "doc_a1b2c3d4e5f6",
  "filename": "report.pdf",
  "file_type": "pdf",
  "file_size": 245678,
  "chunk_count": 15,
  "entity_count": 8,
  "created_at": "2026-01-12T10:30:00Z",
  "metadata": {
    "page_count": 12,
    "project_id": "proj-123",
    "tags": ["quarterly", "finance"]
  },
  "chunks": [
    {
      "chunk_id": "chunk_abc123",
      "chunk_index": 0,
      "text": "Executive Summary...",
      "page_number": 1
    }
  ]
}

---

Delete Document

Remove a document and all its chunks from the graph.

DELETE /documents/{document_id}
X-JWT-Token: <jwt_token>

Example Response

{
  "document_id": "doc_a1b2c3d4e5f6",
  "deleted": true,
  "chunks_deleted": 15,
  "message": "Document and 15 chunks deleted successfully"
}

---

Initialize Indexes

Create vector indexes for chunk embeddings. Called automatically on first upload, but can be triggered manually.

POST /documents/initialize-indexes
X-JWT-Token: <jwt_token>

Example Response

{
  "success": true,
  "indexes_created": ["chunk_embeddings"],
  "message": "Vector indexes initialized"
}

---

Error Responses

400 Bad Request

{
  "detail": "Unsupported file type: .exe"
}

401 Unauthorized

{
  "detail": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired JWT token"
  }
}

404 Not Found

{
  "detail": "Document not found: doc_xyz"
}

500 Internal Server Error

{
  "detail": "Failed to process document: <error_message>"
}

---

Related

• GraphRAG Guide - How GraphRAG works
• MCP API - Access via MCP tools
• Authentication - JWT token format