Skip to main content

​
API Reference

Welcome to the OpenRAG API documentation. This REST API allows you to interact with the RAG system to upload documents, ask questions, and manage your collections.

​
Base URL

http://localhost:8000
In production, replace with your server’s URL.

​
Authentication

OpenRAG uses JWT Bearer tokens. Obtain a token via the login endpoint, then include it in all subsequent requests.

​
Login

POST /auth/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=admin
Response: 
{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "username": "admin",
  "role": "admin"
}

​
Using the token

GET /auth/users
Authorization: Bearer eyJhbGci...

​
Auth endpoints

MethodPathAuthDescription
POST/auth/login—Get JWT token
GET/auth/meUserCurrent user profile
GET/auth/usersAdminList all users
POST/auth/usersAdminCreate user
DELETE/auth/users/{id}AdminDelete user
PATCH/auth/users/{id}/passwordAdminChange password
The default admin account (admin / admin) is created automatically on first startup. Change this password from the Admin panel → Users tab.

​
Response Format

All API responses are in JSON format. 
{
  "status": "success",
  "data": { ... }
}
In case of error: 
{
  "detail": "Descriptive error message"
}

Content-Type: application/json
Accept: application/json

​
Rate Limiting

Currently, no rate limiting is applied. In production, a limit of 100 requests/minute per IP will be enforced.

​
Available Endpoints

​
Queries (RAG)

POST /query

Process a user query and generate a response

​
Document Management

POST /documents/upload

Upload a new document

GET /documents

List all documents

GET /documents/{id}

Retrieve a specific document

DELETE /documents/{id}

Delete a document

​
Collections

GET /collections

List all collections with vector counts

​
Statistics & History

GET /stats

Aggregate system stats (Postgres + Qdrant + health)

GET /history

Paginated query history (admin only)

​
System

GET /

API information

GET /health

Health check

​
HTTP Codes

CodeDescription
200Success
400Invalid request
404Resource not found
500Server error
504Timeout

​
Client Examples

​
Python

import requests

# Configuration
BASE_URL = "http://localhost:8000"

# Upload a document
with open("document.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/documents/upload",
        files={"file": f}
    )
    print(response.json())

# Ask a question
response = requests.post(
    f"{BASE_URL}/query",
    json={
        "query": "What is the refund policy?",
        "max_results": 5
    }
)
print(response.json())

​
JavaScript/Node.js

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const BASE_URL = 'http://localhost:8000';

// Upload a document
async function uploadDocument() {
  const form = new FormData();
  form.append('file', fs.createReadStream('document.pdf'));
  
  const response = await axios.post(
    `${BASE_URL}/documents/upload`,
    form,
    { headers: form.getHeaders() }
  );
  
  console.log(response.data);
}

// Ask a question
async function query() {
  const response = await axios.post(
    `${BASE_URL}/query`,
    {
      query: 'What is the refund policy?',
      max_results: 5
    }
  );
  
  console.log(response.data);
}

​
cURL

# Health check
curl http://localhost:8000/health

# Upload a document
curl -X POST http://localhost:8000/documents/upload \
  -F "file=@document.pdf"

# Ask a question
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the refund policy?",
    "max_results": 5
  }'

# List documents
curl http://localhost:8000/documents

​
Interactive Documentation

OpenRAG provides interactive Swagger UI documentation accessible at: 
http://localhost:8000/docs
You can directly test all endpoints there!

​
Support

For any questions about the API: