API Reference

Base URL#

http://localhost:8001/api/v1

Authentication#

All endpoints except /auth/register, /auth/login, and /health require a JWT bearer token:

Authorization: Bearer <token>

Tokens are issued on registration and login, expire after 60 minutes (configurable via JWT_EXPIRE_MINUTES), and carry the user's ID and role in the payload.

Auth#

Register#

Create a new user account and receive a JWT token.

Request:

{
  "username": "admin",
  "password": "secure-password-here",
  "role": "admin"
}

Response (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "created_at": "2026-02-15T10:30:00Z"
  }
}

Errors:

Login#

Authenticate an existing user and receive a JWT token.

Request:

{
  "username": "admin",
  "password": "secure-password-here"
}

Response (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "created_at": "2026-02-15T10:30:00Z"
  }
}

Errors:

Chat#

Send Message#

Send a message and receive a streaming SSE response. Creates a new conversation if conversation_id is not provided.

Request:

{
  "message": "What is Abu Dhabi's AI strategy?",
  "conversation_id": "abc-123",
  "knowledge_base_id": "kb-001",
  "model": "llama-3.3-70b-versatile"
}

Response (200, text/event-stream):

data: {"token": "Abu", "conversation_id": "abc-123"}

data: {"token": " Dhabi", "conversation_id": "abc-123"}

data: {"token": "'s", "conversation_id": "abc-123"}

...

data: {"done": true, "conversation_id": "abc-123"}

Auth: Bearer token required.

Errors:

List Conversations#

Retrieve the current user's conversations, ordered by most recently updated.

Query Parameters:

Response (200):

[
  {
    "id": "abc-123",
    "title": "What is Abu Dhabi's AI strategy?",
    "knowledge_base_id": "kb-001",
    "message_count": 4,
    "created_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:35:00Z"
  }
]

The title is automatically set to the first 50 characters of the initial message.

Export Conversation#

Export a conversation as JSON or Markdown with full message history and source citations.

Query Parameters:

Response (200):

Returns a downloadable file with Content-Disposition header.

JSON format includes all messages with roles, content, timestamps, and sources. Markdown format renders the conversation as a formatted document with headings, role labels, and source citations.

Errors:

List Models#

List all available models and their providers.

Response (200):

[
  {"id": "llama-3.3-70b-versatile", "provider": "groq"},
  {"id": "llama-3.1-8b-instant", "provider": "groq"},
  {"id": "allam-2-7b", "provider": "groq"},
  {"id": "qwen/qwen3-32b", "provider": "groq"},
  {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "provider": "groq"},
  {"id": "meta-llama/llama-4-maverick-17b-128e-instruct", "provider": "groq"},
  {"id": "openai/gpt-oss-120b", "provider": "groq"},
  {"id": "gpt-4o-uaenorth", "provider": "azure"},
  {"id": "gpt-4o", "provider": "core42"},
  {"id": "gpt-4.1", "provider": "core42"}
]

Knowledge Bases#

Create Knowledge Base#

Create a new knowledge base for document storage and RAG retrieval.

Auth: Requires admin or manager role.

Request:

{
  "name": "UAE AI Policy",
  "description": "National AI strategy and governance documents"
}

Response (200):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "UAE AI Policy",
  "description": "National AI strategy and governance documents",
  "document_count": 0,
  "owner_id": 1,
  "created_at": "2026-02-15T10:30:00Z"
}

List Knowledge Bases#

List knowledge bases visible to the current user. Admins see all knowledge bases; other roles see only their own.

Query Parameters:

Response (200):

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "UAE AI Policy",
    "description": "National AI strategy and governance documents",
    "document_count": 3,
    "owner_id": 1,
    "created_at": "2026-02-15T10:30:00Z"
  }
]

Documents#

Upload Document#

Upload a file to a knowledge base. Triggers the full RAG ingestion pipeline (extraction, chunking, embedding, storage).

Auth: Requires admin or manager role. Managers can only upload to knowledge bases they own.

Content-Type: multipart/form-data

Response (200):

{
  "id": "doc-001",
  "filename": "uae-ai-strategy.pdf",
  "content_type": "application/pdf",
  "knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "chunk_count": 42,
  "created_at": "2026-02-15T10:35:00Z"
}

Errors:

List Documents#

List documents, optionally filtered by knowledge base.

Query Parameters:

Response (200):

[
  {
    "id": "doc-001",
    "filename": "uae-ai-strategy.pdf",
    "content_type": "application/pdf",
    "knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chunk_count": 42,
    "created_at": "2026-02-15T10:35:00Z"
  }
]

Delete Document#

Delete a document and remove all its vector chunks from pgvector.

Auth: Requires admin or manager role.

Response (200):

{
  "status": "deleted",
  "id": "doc-001"
}

Errors:

RAG Ingest (Service-to-Service)#

Ingest Pre-Processed Chunks#

Accept pre-chunked document text from external services (e.g., Anar Docs) and store embeddings in pgvector. Skips text extraction and chunking.

Auth: Requires admin or manager role.

Request:

{
  "knowledge_base_id": "kb-001",
  "document_id": "doc-from-docs-001",
  "filename": "scanned-contract.pdf",
  "chunks": [
    {
      "text": "Article 1: Definitions and scope of this agreement...",
      "index": 0,
      "metadata": {"page": 1, "section": "definitions"}
    },
    {
      "text": "Article 2: Terms and conditions governing...",
      "index": 1,
      "metadata": {"page": 2, "section": "terms"}
    }
  ],
  "language": "ar"
}

Response (200):

{
  "document_id": "doc-from-docs-001",
  "chunks_ingested": 2
}

Errors:

System#

Health Check#

Auth: None required.

Response (200):

{
  "status": "healthy",
  "service": "anar-chat"
}

Metrics#

Auth: None required.

Response (200):

{
  "uptime_seconds": 3600.5,
  "requests_total": 1250,
  "errors_total": 3,
  "chat_completions": 890,
  "documents_uploaded": 45
}

Error Response Format#

All error responses follow a consistent structure:

{
  "detail": "Human-readable error message"
}

Rate Limiting#

Chat applies rate limiting through the anar_shared.harden() middleware. Requests exceeding the rate limit receive a 429 Too Many Requests response. Configure limits through the shared library's hardening settings.

OpenAPI Schema#

The full OpenAPI specification is available at:

http://localhost:8001/openapi.json

Interactive Swagger documentation:

http://localhost:8001/docs