> ## Documentation Index
> Fetch the complete documentation index at: https://docs.3ntrop1a.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Introduction to the OpenRAG REST API

# 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

```http theme={null}
POST /auth/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=admin
```

Response:

```json theme={null}
{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "username": "admin",
  "role": "admin"
}
```

### Using the token

```http theme={null}
GET /auth/users
Authorization: Bearer eyJhbGci...
```

### Auth endpoints

| Method   | Path                        | Auth  | Description          |
| -------- | --------------------------- | ----- | -------------------- |
| `POST`   | `/auth/login`               | —     | Get JWT token        |
| `GET`    | `/auth/me`                  | User  | Current user profile |
| `GET`    | `/auth/users`               | Admin | List all users       |
| `POST`   | `/auth/users`               | Admin | Create user          |
| `DELETE` | `/auth/users/{id}`          | Admin | Delete user          |
| `PATCH`  | `/auth/users/{id}/password` | Admin | Change password      |

<Info>
  The default admin account (`admin` / `admin`) is created automatically on first startup. Change this password from the Admin panel → Users tab.
</Info>

## Response Format

All API responses are in JSON format.

```json theme={null}
{
  "status": "success",
  "data": { ... }
}
```

In case of error:

```json theme={null}
{
  "detail": "Descriptive error message"
}
```

## Recommended Headers

```http theme={null}
Content-Type: application/json
Accept: application/json
```

## Rate Limiting

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

## Available Endpoints

### Queries (RAG)

<CardGroup cols={1}>
  <Card title="POST /query" icon="message-question" href="/openrag/api-reference/query/process-query">
    Process a user query and generate a response
  </Card>
</CardGroup>

### Document Management

<CardGroup cols={2}>
  <Card title="POST /documents/upload" icon="file-upload">
    Upload a new document
  </Card>

  <Card title="GET /documents" icon="list">
    List all documents
  </Card>

  <Card title="GET /documents/{id}" icon="file">
    Retrieve a specific document
  </Card>

  <Card title="DELETE /documents/{id}" icon="trash">
    Delete a document
  </Card>
</CardGroup>

### Collections

<CardGroup cols={1}>
  <Card title="GET /collections" icon="folder">
    List all collections with vector counts
  </Card>
</CardGroup>

### Statistics & History

<CardGroup cols={2}>
  <Card title="GET /stats" icon="chart-bar">
    Aggregate system stats (Postgres + Qdrant + health)
  </Card>

  <Card title="GET /history" icon="clock-rotate-left">
    Paginated query history (admin only)
  </Card>
</CardGroup>

### System

<CardGroup cols={2}>
  <Card title="GET /" icon="home">
    API information
  </Card>

  <Card title="GET /health" icon="heart-pulse">
    Health check
  </Card>
</CardGroup>

## HTTP Codes

| Code | Description        |
| ---- | ------------------ |
| 200  | Success            |
| 400  | Invalid request    |
| 404  | Resource not found |
| 500  | Server error       |
| 504  | Timeout            |

## Client Examples

### Python

```python theme={null}
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

```javascript theme={null}
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

```bash theme={null}
# 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:

* 🐛 Issues: [github.com/3ntrop1a/openrag/issues](https://github.com/3ntrop1a/openrag/issues)