MAC System Workflow and Architecture Documentation

1) Scope and Goals

MAC is a self-hosted AI platform designed to expose OpenAI-compatible APIs from local or clustered GPU infrastructure. It combines authentication, safety guardrails, model routing, usage tracking, RAG, search grounding, and campus workflows like attendance and doubt resolution.

Primary Goal

Serve LLM, STT, TTS, embeddings, and vision features through one FastAPI control plane.

Operational Goal

Run in single-node mode or distributed control-node plus worker-node mode.

Governance Goal

Enforce auth, quotas, guardrails, and audit logs for campus-safe usage.

2) Tech Stack

Layer	Technology	How It Is Used
Backend API	FastAPI, Uvicorn	Router-based API under /api/v1, async services, docs at /docs and /redoc.
Data Access	SQLAlchemy Async, asyncpg	All relational entities for users, usage, quotas, RAG docs, nodes, attendance, doubts.
Database	PostgreSQL	Persistent store for auth state, usage logs, quota overrides, audit, and domain records.
Vector Store	Qdrant	Stores embeddings and chunk payloads for RAG similarity search.
Cache and Limits	Redis (plus DB counters)	Infrastructure cache service is present; request and token checks are computed from usage logs.
Model Serving	vLLM OpenAI-compatible API	Inference endpoints for chat/completions/embeddings and optionally vision models.
Speech	Faster-Whisper server, OpenAI-style TTS endpoint	Audio transcription and text-to-speech through /query/speech-to-text and /query/text-to-speech.
Web Search	SearXNG + Wikipedia APIs	Grounded search pipeline combines web retrieval with generated answers.
Frontend	PWA static frontend via Nginx	Nginx serves assets and proxies /api requests to FastAPI.
Security	JWT, bcrypt, hashed refresh/scoped tokens	Supports JWT, legacy API keys, and scoped API keys with endpoint/model restrictions.
Tests	pytest, pytest-asyncio	Repository includes tests for core API domains.

Tech Stack Diagram

flowchart TD
  Client[Students Faculty Apps SDK Clients] --> Nginx[Nginx Reverse Proxy + Static PWA]
  Nginx --> API[FastAPI MAC Control Plane]

  API --> Auth[Auth Middleware JWT and API Keys]
  API --> RL[Rate Limit and Usage Checks]
  API --> Guardrails[Guardrail Engine]
  API --> Routing[Model Routing and LLM Service]

  Routing --> VLLM[vLLM Endpoints]
  API --> Whisper[Whisper STT Endpoint]
  API --> TTS[TTS Endpoint]

  API --> PG[(PostgreSQL)]
  API --> Redis[(Redis)]
  API --> Qdrant[(Qdrant Vector DB)]
  API --> Searx[(SearXNG)]

  API --> Workers[Worker Nodes Optional Cluster]
  Workers --> VLLM

3) Runtime Architecture

The project supports multiple deployment patterns. The same API codebase can run in a monolithic local setup or in a control-node plus worker-node topology.

A. Single Machine Mode

A single docker-compose file runs FastAPI, Nginx, PostgreSQL, Redis, Qdrant, SearXNG, one vLLM service, and optional Whisper/TTS services.

B. Split Two-PC Mode

PC1 hosts vLLM GPU service, while PC2 hosts API and infrastructure. API environment variables point all model URLs to PC1 over LAN.

C. Control Node + Worker Cluster Mode

Control node stores cluster metadata and worker heartbeats. Worker nodes enroll with one-time tokens, register model deployments, and keep metrics updated. The LLM service resolves model endpoints by checking ready deployments and probing node health.

flowchart LR
  subgraph Campus Network
    Browser[Browser / SDK / Scripts]
  end

  subgraph Control Node
    N[Nginx 80/443]
    A[FastAPI MAC API 8000]
    DB[(PostgreSQL)]
    R[(Redis)]
    Q[(Qdrant)]
    S[(SearXNG)]
  end

  subgraph Worker Node 1
    W1A[Worker Agent]
    W1M[vLLM Model Service]
  end

  subgraph Worker Node 2
    W2A[Worker Agent]
    W2M[vLLM Model Service]
  end

  Browser --> N --> A
  A --> DB
  A --> R
  A --> Q
  A --> S

  W1A -->|enroll heartbeat register model| A
  W2A -->|enroll heartbeat register model| A

  A -->|route inference| W1M
  A -->|route inference| W2M

Control Plane: FastAPI + DB + Node Metadata Data Plane: vLLM Endpoints On Local or Worker GPUs Ingress: Nginx For Static UI and API Proxy

4) API Layer and Responsibilities

Routers are mounted under /api/v1. Each router generally maps to a dedicated service module and schemas.

Router	Focus	Main Behavior
/auth	Identity and session	Roll and DOB verify flow, login, token refresh, profile updates, admin user controls.
/query	Inference APIs	Chat, completion, embeddings, rerank, vision, STT, TTS with usage logging and guardrails.
/guardrails	Safety policies	Input/output checks, rule listing and replacement by admins.
/usage and /quota	Governance	Per-user usage analytics, quota readouts, and admin override management.
/rag	Knowledge ingestion and retrieval	Document ingest, chunking, embeddings, collection management, answer generation with citations.
/search	External grounding	SearXNG and Wikipedia retrieval, then optional grounded answer synthesis.
/nodes	Cluster operations	Enrollment token issuing, worker enrollment, heartbeats, deployment state lifecycle.
/attendance	Campus attendance workflow	Face registration, session create/list/close, attendance marking and reports.
/doubts and /notifications	Student-faculty interaction	Doubt posting/replying, notifications, audit trails, push subscriptions.
/keys and /scoped-keys	Credential management	Legacy API key rotation and scoped keys with endpoint and model restrictions.
/models and /explore	Discovery and model state	Model metadata, health checks, warm-up behavior, endpoint cataloging.
/agent	Plan and execute mode	Creates in-memory agent sessions, streams progress via SSE, runs tool-like actions.

5) Core Request Workflow

For most protected endpoints, processing follows the same high-level chain: auth check, rate checks, route handler logic, downstream service calls, and persistence updates.

sequenceDiagram
  autonumber
  participant C as Client
  participant N as Nginx
  participant API as FastAPI Router
  participant AUTH as Auth Middleware
  participant RL as Rate Limit Dependency
  participant G as Guardrail Service
  participant L as LLM Service
  participant DB as PostgreSQL

  C->>N: HTTP Request
  N->>API: Forward /api/v1/*
  API->>AUTH: Resolve user from Authorization header
  AUTH-->>API: User context (JWT or API key)
  API->>RL: Check hourly requests and daily token usage
  RL->>DB: Read usage logs counters
  RL-->>API: Allow or reject 429
  API->>G: Validate input text patterns
  G-->>API: Safe or blocked
  API->>L: Perform inference or related operation
  L-->>API: Result payload and usage
  API->>G: Output safety pass and redaction
  API->>DB: Persist usage log and any domain records
  API-->>N: Structured response
  N-->>C: Final response

Important Processing Details

Auth middleware supports three credential forms: JWT, legacy API key, and scoped API key.
Rate limiting currently derives counters from usage logs in PostgreSQL.
Guardrails include built-in rules and optional DB-managed rules.
LLM service injects a fixed MAC identity system prompt before inference.
Model route selection can be automatic using keyword heuristics when model is set to auto.

6) Database Model and ER Diagram

The schema is generated from SQLAlchemy models at startup in development mode. Alembic exists in the repository, but versioned migrations are currently absent.

Domain Groups

Identity and Access

student_registry, users, refresh_tokens, scoped_api_keys.

Governance

usage_logs, quota_overrides, guardrail_rules, audit_logs.

RAG and Retrieval

rag_collections, rag_documents plus vector payloads in Qdrant.

Cluster and Deployment

worker_nodes, node_model_deployments, enrollment_tokens.

Campus Workflows

face_templates, attendance_sessions, attendance_records, doubts, doubt_replies.

Engagement

notifications, push_subscriptions.

ER Diagram

erDiagram
  STUDENT_REGISTRY {
    string id PK
    string roll_number UK
    string name
    string department
    date dob
    int batch_year
  }

  USERS {
    string id PK
    string roll_number UK
    string name
    string email
    string department
    string role
    string password_hash
    bool must_change_password
    bool is_active
    string api_key UK
    int failed_login_attempts
    datetime locked_until
    datetime created_at
    datetime updated_at
  }

  REFRESH_TOKENS {
    string id PK
    string user_id FK
    string token_hash UK
    datetime expires_at
    bool revoked
    datetime created_at
  }

  USAGE_LOGS {
    string id PK
    string user_id FK
    string model
    string endpoint
    int tokens_in
    int tokens_out
    int latency_ms
    int status_code
    string request_id
    datetime created_at
  }

  QUOTA_OVERRIDES {
    string id PK
    string user_id FK
    int daily_tokens
    int requests_per_hour
    int max_tokens_per_request
    string reason
    string created_by
    datetime created_at
    datetime updated_at
  }

  GUARDRAIL_RULES {
    string id PK
    string category
    string action
    string pattern
    string description
    bool enabled
    int priority
    datetime created_at
    datetime updated_at
  }

  RAG_COLLECTIONS {
    string id PK
    string name UK
    string description
    int document_count
    string created_by
    datetime created_at
  }

  RAG_DOCUMENTS {
    string id PK
    string collection_id FK
    string title
    string filename
    string content_type
    int file_size
    int chunk_count
    int page_count
    string status
    string error_message
    string uploaded_by
    datetime created_at
  }

  WORKER_NODES {
    string id PK
    string name
    string hostname
    string ip_address
    int port
    string token_hash
    string status
    string gpu_name
    int gpu_vram_mb
    int ram_total_mb
    int cpu_cores
    float gpu_util_pct
    int gpu_vram_used_mb
    int ram_used_mb
    float cpu_util_pct
    datetime last_heartbeat
    int max_resource_pct
    string enrolled_by
    datetime created_at
    datetime updated_at
  }

  NODE_MODEL_DEPLOYMENTS {
    string id PK
    string node_id FK
    string model_id
    string model_name
    string served_name
    int vllm_port
    string status
    float gpu_memory_util
    int max_model_len
    string error_message
    string deployed_by
    datetime created_at
    datetime updated_at
  }

  ENROLLMENT_TOKENS {
    string id PK
    string token_hash UK
    string label
    bool used
    string used_by_node_id
    datetime expires_at
    string created_by
    datetime created_at
  }

  FACE_TEMPLATES {
    string id PK
    string user_id FK
    bytes face_encoding
    string photo_hash
    datetime captured_at
    datetime updated_at
  }

  ATTENDANCE_SESSIONS {
    string id PK
    string title
    string department
    string subject
    date session_date
    string opened_by FK
    bool is_open
    datetime opened_at
    datetime closed_at
  }

  ATTENDANCE_RECORDS {
    string id PK
    string session_id FK
    string user_id FK
    float face_match_confidence
    bool face_verified
    string photo_hash
    string ip_address
    datetime marked_at
  }

  DOUBTS {
    string id PK
    string title
    string body
    string department
    string subject
    string target_faculty_id FK
    string student_id FK
    string status
    string attachment_url
    string attachment_name
    bool is_anonymous
    datetime created_at
    datetime updated_at
  }

  DOUBT_REPLIES {
    string id PK
    string doubt_id FK
    string author_id FK
    string body
    string attachment_url
    string attachment_name
    datetime created_at
  }

  NOTIFICATIONS {
    string id PK
    string user_id FK
    string title
    string body
    string category
    string link
    bool is_read
    datetime created_at
  }

  PUSH_SUBSCRIPTIONS {
    string id PK
    string user_id FK
    string endpoint
    string p256dh_key
    string auth_key
    datetime created_at
  }

  AUDIT_LOGS {
    string id PK
    string actor_id
    string actor_role
    string action
    string resource_type
    string resource_id
    string details
    string ip_address
    datetime created_at
  }

  SCOPED_API_KEYS {
    string id PK
    string user_id FK
    string name
    string key_prefix
    string key_hash UK
    string allowed_models
    string allowed_endpoints
    int requests_per_hour
    int tokens_per_day
    int max_tokens_per_request
    bool is_active
    datetime expires_at
    datetime last_used_at
    int total_requests
    int total_tokens
    datetime created_at
    datetime revoked_at
    string revoked_by
  }

  USERS ||--o{ REFRESH_TOKENS : has
  USERS ||--o{ USAGE_LOGS : has
  USERS ||--o| QUOTA_OVERRIDES : can_have
  RAG_COLLECTIONS ||--o{ RAG_DOCUMENTS : contains
  WORKER_NODES ||--o{ NODE_MODEL_DEPLOYMENTS : hosts
  USERS ||--o| FACE_TEMPLATES : registers
  ATTENDANCE_SESSIONS ||--o{ ATTENDANCE_RECORDS : includes
  USERS ||--o{ ATTENDANCE_RECORDS : marks
  USERS ||--o{ DOUBTS : creates
  DOUBTS ||--o{ DOUBT_REPLIES : has
  USERS ||--o{ DOUBT_REPLIES : writes
  USERS ||--o{ NOTIFICATIONS : receives
  USERS ||--o{ PUSH_SUBSCRIPTIONS : owns
  USERS ||--o{ SCOPED_API_KEYS : owns

7) Feature Workflows

7.1 Authentication (Verify Flow)

The /auth/verify endpoint validates roll number plus DOB against student_registry. If user does not exist, it creates one with temporary password policy and returns access plus refresh tokens.

sequenceDiagram
  participant U as User
  participant API as Auth Router
  participant S as Auth Service
  participant DB as PostgreSQL

  U->>API: POST /auth/verify {roll_number dob}
  API->>S: parse and validate DOB
  S->>DB: fetch student_registry by roll_number
  DB-->>S: entry found or null
  S->>S: compare DOB
  alt first login
    S->>DB: create users row (must_change_password = true)
  end
  S->>DB: create refresh_tokens row
  S-->>API: access_token refresh_token
  API-->>U: LoginResponse with user profile

7.2 Chat and Inference

Chat flow adds safety checks before and after generation. Usage is persisted for limits and analytics.

flowchart TD
  A[Request POST /query/chat] --> B[Auth and Rate Limit]
  B --> C[Input Guardrail Scan]
  C -->|blocked| Z[Return 400 content_blocked]
  C --> D[Model Resolve auto or explicit]
  D --> E[Cluster aware endpoint resolve]
  E --> F[vLLM /v1/chat/completions]
  F --> G[Output Guardrail Redaction]
  G --> H[Insert usage_logs row]
  H --> I[Return ChatResponse]

7.3 RAG Ingest and Query

flowchart LR
  Upload[Upload Document] --> Parse[Read content bytes]
  Parse --> Chunk[Chunk text]
  Chunk --> Emb[Generate embeddings]
  Emb --> Qdrant[Upsert vectors into Qdrant]
  Parse --> DBDoc[Insert rag_documents metadata]
  DBDoc --> Ready[Set status ready]

  Question[User Question] --> QEmb[Question embedding]
  QEmb --> Similarity[Qdrant similarity search]
  Similarity --> Ctx[Build context with source chunks]
  Ctx --> Answer[LLM answer generation]
  Answer --> Return[Return answer plus sources]

7.4 Search Grounding

Grounded search uses SearXNG retrieval with a TTL in-memory cache and then synthesizes an answer from retrieved snippets.

7.5 Attendance and Doubts

Attendance

Users register face templates, faculty opens sessions, students mark attendance with live image, and records are saved with confidence and timestamps.

Doubt Handling

Students create doubts, faculty replies, status transitions from open to answered/closed, and notifications are sent to affected users.

8) Cluster and Worker Node Lifecycle

Worker nodes are not blindly trusted. They enroll through short-lived one-time tokens and then send heartbeat metrics continuously.

sequenceDiagram
  autonumber
  participant Admin as Admin
  participant Control as Control Node API
  participant Agent as Worker Agent
  participant VLLM as Worker vLLM
  participant DB as PostgreSQL

  Admin->>Control: Create enrollment token
  Control->>DB: Insert enrollment_tokens
  Agent->>VLLM: Wait until local /health ready
  Agent->>Control: POST /nodes/enroll with token and hardware metadata
  Control->>DB: Validate token and insert worker_nodes row
  Agent->>Control: POST /nodes/register-model
  Control->>DB: Insert node_model_deployments and mark ready
  loop every heartbeat interval
    Agent->>Control: POST /nodes/heartbeat/{node_id}
    Control->>DB: update live resource metrics
  end
  Control->>Control: route model requests to least-loaded ready node

Routing Strategy Notes

Model resolution first tries ready cluster deployments for requested model_id.
If selected worker endpoint fails health probe, fallback route uses local configured vLLM URL.
Node deployment status tracks pending, downloading, loading, ready, error, and unloaded states.

9) Endpoint Playbook

This section groups high-impact API operations by function and gives practical implementation notes, including authentication mode, typical payload shape, and side effects.

Auth and Identity

Endpoint	Auth Required	Purpose	State Changes
POST /api/v1/auth/verify	No	Login bootstrap using roll_number and DOB verification.	Creates users row if first login, inserts refresh token row.
POST /api/v1/auth/login	No	Password login for existing account.	Updates lockout counters, inserts refresh token row on success.
POST /api/v1/auth/set-password	JWT/API Key	First-time password set when must_change_password is true.	Updates password_hash and clears must_change_password.
POST /api/v1/auth/refresh	No	Exchanges refresh token for access token.	Validates refresh token hash and expiration.
POST /api/v1/auth/logout	JWT/API Key	Logs out user session family.	Revokes all refresh_tokens entries for user.

Inference and Model Usage

Endpoint	Auth Required	Purpose	State Changes
POST /api/v1/query/chat	JWT/API Key	Primary multi-turn chat API compatible with OpenAI chat format.	Reads guardrails, writes usage_logs, applies redaction rules.
POST /api/v1/query/completions	JWT/API Key	Text completion interface.	Writes usage_logs.
POST /api/v1/query/embeddings	JWT/API Key	Embedding vector generation.	Writes usage_logs.
POST /api/v1/query/vision	JWT/API Key	Vision prompt with image upload via multipart form.	Writes usage_logs.
POST /api/v1/query/speech-to-text	JWT/API Key	Audio transcription through Whisper service.	Writes usage_logs.
POST /api/v1/query/text-to-speech	JWT/API Key	Speech synthesis from plain text.	Writes usage_logs.

Knowledge and Retrieval

Endpoint	Auth Required	Purpose	State Changes
POST /api/v1/rag/ingest	JWT/API Key	Uploads and ingests documents into RAG pipeline.	Creates rag_documents, updates rag_collections count, upserts vectors.
POST /api/v1/rag/query	JWT/API Key	Retrieves top chunks and generates contextual answer.	Read-heavy flow, optionally consumes model tokens.
POST /api/v1/search/web	JWT/API Key	General web search through SearXNG.	Uses in-memory cache with TTL; no DB write by default.
POST /api/v1/search/grounded	JWT/API Key	Search first, then synthesized answer with source citations.	In-memory cache use plus model call.

Governance and Admin

Endpoint	Auth Required	Purpose	State Changes
GET /api/v1/usage/admin/all	Admin	Cross-user usage summary for monitoring.	Read-only.
PUT /api/v1/quota/admin/user/{roll}	Admin	Set per-user quota overrides.	Creates or updates quota_overrides row.
PUT /api/v1/guardrails/rules	Admin	Replace guardrail rule set.	Deletes and recreates guardrail_rules rows.
POST /api/v1/nodes/enrollment-token	Admin	Issue one-time worker enrollment secret.	Creates enrollment_tokens row and audit log.
POST /api/v1/nodes/deploy	Admin	Request model deployment on specific worker node.	Creates node_model_deployments row and audit log.

OpenAI Compatibility Quick Mapping

Chat Completions

Compatible route: /api/v1/query/chat with role/content message format.

Embeddings

Compatible route: /api/v1/query/embeddings with list or single input payload.

Streaming

Server-sent events output for stream=true in chat endpoint.

10) Deployment Playbooks

The repository provides multiple compose files for different infrastructure constraints. Choose one model depending on hardware and network topology.

Mode	Compose File	When To Use	Command
All-in-one local	docker-compose.yml	Single machine with full stack and one primary GPU model.	docker compose up -d
Control plane only	docker-compose.control-node.yml	Central coordinator when inference runs on remote workers.	docker compose -f docker-compose.control-node.yml up -d
PC1 GPU endpoint	docker-compose.pc1-gpu.yml	Dedicated inference machine serving vLLM over LAN.	docker compose -f docker-compose.pc1-gpu.yml up -d
PC2 app stack	docker-compose.pc2-app.yml	App machine consuming remote GPU service from PC1.	docker compose -f docker-compose.pc2-app.yml up -d
Worker node package	docker-compose.worker-node.yml	Reusable worker for enrollment and heartbeat-based participation.	docker compose -f docker-compose.worker-node.yml up -d

Deployment Decision Diagram

flowchart TD
  Q1{Do you have only one machine?}
  Q1 -->|Yes| M1[Use docker-compose.yml]
  Q1 -->|No| Q2{Need centralized API and DB?}
  Q2 -->|Yes| M2[Use docker-compose.control-node.yml on control node]
  Q2 -->|No| M3[Use pc2-app and pc1-gpu split mode]

  M2 --> Q3{Add additional GPU workers?}
  Q3 -->|Yes| M4[Run docker-compose.worker-node.yml on workers]
  Q3 -->|No| M5[Operate control node with local GPU only]

Startup Verification Checklist

Check Nginx responds on port 80 and optionally 443.
Open /api/v1 for endpoint map and /docs for interactive OpenAPI.
Confirm database and redis health in compose status.
Confirm vLLM /v1/models returns loaded model list.
Run a test /query/chat request with auth token and verify usage log appears.

Failure Isolation Matrix

Symptom	Likely Layer	First Check	Second Check
502 at gateway	Nginx to API upstream	mac container is up and reachable	nginx upstream target and port mapping
Model unavailable errors	LLM service routing	vLLM endpoint /v1/models health	worker deployment status ready and not offline
Cannot login by verify flow	Auth and student registry	student_registry contains roll number	DOB format and value match
RAG returns empty sources	Qdrant and embeddings	qdrant reachable and collection exists	embedding model endpoint is healthy
Worker not receiving traffic	Cluster routing metadata	worker_nodes heartbeat freshness	node_model_deployments status and served_name

11) Environment Variable Matrix

Core runtime behavior is environment-driven. The table below highlights high-impact settings and practical tuning notes.

Variable	Default	Used By	Impact
DATABASE_URL	postgresql+asyncpg://...	database.py	Main relational persistence path for all domains.
REDIS_URL	redis://localhost:6379/0	settings, infra compose	Cache/rate-limit infra endpoint; app rate logic is DB-based currently.
VLLM_BASE_URL	http://localhost:8001	llm_service.py	Fallback inference endpoint for unknown models.
VLLM_SPEED_URL, VLLM_CODE_URL, ...	localhost ports 8001-8004	llm_service.py	Model-category to endpoint slot mapping.
MAC_ENABLED_MODELS	empty = all built-ins	llm_service.py	Filters active model registry by model ID allow-list.
MAC_MODELS_JSON	empty	llm_service.py	Replaces built-in registry with fully custom model list.
MAC_AUTO_FALLBACK	first code/speed model	llm_service.py	Auto route fallback target when heuristics do not strongly match.
QDRANT_URL	http://localhost:6333	rag_service.py	Vector storage and retrieval endpoint for RAG.
QDRANT_COLLECTION	mac_documents	rag_service.py	Logical vector namespace for document chunks.
SEARXNG_URL	http://localhost:8888	search_service.py	Search backend endpoint for web retrieval.
JWT_SECRET_KEY	change-me-jwt-secret	security utils/auth	Access token signing and verification root secret.
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	1440	auth service	Controls access token lifetime.
JWT_REFRESH_TOKEN_EXPIRE_DAYS	30	auth service	Controls refresh token validity window.
RATE_LIMIT_REQUESTS_PER_HOUR	100	rate_limit.py	Per-user hourly gate based on usage logs.
RATE_LIMIT_TOKENS_PER_DAY	50000	rate_limit.py	Per-user daily token gate based on usage logs.
WHISPER_URL / TTS_URL	localhost services	llm_service.py	Speech pipeline availability toggles.

Profile Examples

Low-Memory GPU Profile

Enable only qwen2.5:7b plus optional whisper-small. Keep one vLLM endpoint and route all categories to same model URL.

Cluster Performance Profile

Keep control node API lightweight; assign model specialties to dedicated workers and rely on deployment-aware endpoint resolution.

12) Role-Based End-to-End Journeys

These journeys map user-facing actions to internal components and data changes.

Student Journey: First Login to AI Query

sequenceDiagram
  autonumber
  participant Student
  participant API
  participant AuthSvc
  participant DB
  participant LLM

  Student->>API: POST /auth/verify
  API->>AuthSvc: verify roll and dob
  AuthSvc->>DB: student_registry lookup
  AuthSvc->>DB: create user if first login
  API-->>Student: access and refresh tokens

  Student->>API: POST /query/chat
  API->>DB: usage counters read for rate check
  API->>LLM: chat inference
  API->>DB: usage log insert
  API-->>Student: answer payload

Faculty Journey: Attendance Session and Reporting

flowchart TD
  F1[Faculty login] --> F2[POST /attendance/sessions]
  F2 --> F3[attendance_sessions row created]
  F3 --> F4[Students mark attendance]
  F4 --> F5[attendance_records rows inserted]
  F5 --> F6[Faculty closes session]
  F6 --> F7[Faculty pulls session report]

Admin Journey: Worker Enrollment and Model Deployment

flowchart LR
  A1[Admin creates enrollment token] --> A2[Worker enrolls]
  A2 --> A3[worker_nodes row active]
  A3 --> A4[Worker registers model]
  A4 --> A5[node_model_deployments row ready]
  A5 --> A6[Traffic routed to worker model endpoint]

Governance Journey: Scoped Key and Audit Trail

User creates scoped key with model and endpoint restrictions.
Scoped key hash is stored; plain key is shown once.
On each request, auth middleware resolves key owner and scope metadata.
Relevant admin and key lifecycle actions are logged into audit_logs.
Notifications and audit views provide operational visibility to admins.

13) API Contract Appendix - Detailed Request and Response Templates

This appendix is an implementation-oriented companion to earlier workflow diagrams. Each endpoint card includes route semantics, authentication expectation, template payloads, success example, and error example. Templates are intentionally verbose so backend, frontend, and QA teams can align quickly.

Appendix Usage Notes

Replace placeholder identifiers such as user_id, node_id, and request_id with real values.
Where multipart form upload is required, use equivalent SDK abstractions instead of raw JSON body.
Error shapes are normalized but actual details may include route-specific codes and messages.
These templates favor clarity for integration and testing over minimal payload size.

Endpoint Cards

1. POST /api/v1/auth/verify - Authenticate using roll number and DOB against student registry.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/auth/verify",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/verify",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

2. POST /api/v1/auth/login - Authenticate existing account with password.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/auth/login",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/login",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

3. POST /api/v1/auth/set-password - Set first password when must_change_password is true.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/auth/set-password",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/set-password",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

4. POST /api/v1/auth/logout - Revoke all refresh tokens for current user.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/auth/logout",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/logout",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

5. POST /api/v1/auth/refresh - Exchange refresh token for new access token.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/auth/refresh",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/refresh",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

6. GET /api/v1/auth/me - Return profile and quota view for current user.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/auth/me",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/me",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

7. PUT /api/v1/auth/me/profile - Update basic profile fields.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "PUT",
  "path": "/api/v1/auth/me/profile",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/me/profile",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

8. POST /api/v1/auth/change-password - Change password with old password validation.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/auth/change-password",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/change-password",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

9. GET /api/v1/auth/admin/users - List all users for administration.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/auth/admin/users",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/admin/users",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

10. POST /api/v1/auth/admin/users - Create user account from admin panel.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/auth/admin/users",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/admin/users",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

11. PUT /api/v1/auth/admin/users/{user_id}/role - Change role among student faculty admin.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "PUT",
  "path": "/api/v1/auth/admin/users/{user_id}/role",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/admin/users/{user_id}/role",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

12. PUT /api/v1/auth/admin/users/{user_id} - Edit user metadata including active state.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "PUT",
  "path": "/api/v1/auth/admin/users/{user_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/auth/admin/users/{user_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

13. GET /api/v1/explore/models - Browse model registry with filters and paging.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/explore/models",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/explore/models",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

14. GET /api/v1/explore/models/search - Search model registry by capability tag.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/explore/models/search",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/explore/models/search",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

15. GET /api/v1/explore/models/{model_id} - Get detailed model card.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/explore/models/{model_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/explore/models/{model_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

16. GET /api/v1/explore/endpoints - List public endpoint catalog metadata.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/explore/endpoints",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/explore/endpoints",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

17. GET /api/v1/explore/health - System health and model summary.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/explore/health",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/explore/health",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

18. POST /api/v1/query/chat - Main chat completions endpoint with optional streaming.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/query/chat",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/query/chat",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

19. POST /api/v1/query/completions - Text completion endpoint.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/query/completions",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/query/completions",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

20. POST /api/v1/query/embeddings - Generate embeddings for one or many inputs.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/query/embeddings",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/query/embeddings",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

21. POST /api/v1/query/rerank - Cosine-based reranking utility endpoint.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/query/rerank",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/query/rerank",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

22. POST /api/v1/query/vision - Image + prompt multimodal inference endpoint.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/query/vision",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/query/vision",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

23. POST /api/v1/query/speech-to-text - Audio transcription endpoint.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/query/speech-to-text",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/query/speech-to-text",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

24. POST /api/v1/query/text-to-speech - Generate speech audio from text.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/query/text-to-speech",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/query/text-to-speech",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

25. GET /api/v1/usage/me - My usage aggregates for day week month.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/usage/me",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/usage/me",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

26. GET /api/v1/usage/me/history - Paginated request history with filters.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/usage/me/history",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/usage/me/history",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

27. GET /api/v1/usage/me/quota - Current quota and reset times.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/usage/me/quota",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/usage/me/quota",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

28. GET /api/v1/usage/admin/all - All users usage summary page.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/usage/admin/all",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/usage/admin/all",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

29. GET /api/v1/usage/admin/user/{roll_number} - Specific user usage details.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/usage/admin/user/{roll_number}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/usage/admin/user/{roll_number}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

30. GET /api/v1/usage/admin/models - Per-model usage metrics.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/usage/admin/models",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/usage/admin/models",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

31. GET /api/v1/models - List model statuses from registry and health checks.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/models",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/models",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

32. GET /api/v1/models/{model_id} - Get model details and status.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/models/{model_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/models/{model_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

33. POST /api/v1/models/{model_id}/load - Warm-load model on serving backend.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/models/{model_id}/load",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/models/{model_id}/load",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

34. POST /api/v1/models/{model_id}/unload - Unload model or mark unload intent.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/models/{model_id}/unload",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/models/{model_id}/unload",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

35. GET /api/v1/models/{model_id}/health - Health endpoint for model availability.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/models/{model_id}/health",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/models/{model_id}/health",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

36. POST /api/v1/models/download - Track model download task metadata.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/models/download",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/models/download",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

37. GET /api/v1/models/download/{task_id} - Fetch model download task status.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/models/download/{task_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/models/download/{task_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

38. GET /api/v1/integration/routing-rules - Read in-memory task routing rules.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/integration/routing-rules",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/integration/routing-rules",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

39. PUT /api/v1/integration/routing-rules - Update in-memory routing rules.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "PUT",
  "path": "/api/v1/integration/routing-rules",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/integration/routing-rules",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

40. GET /api/v1/integration/workers - List worker summary for integration router.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/integration/workers",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/integration/workers",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

41. GET /api/v1/integration/workers/{node_id} - Get one worker details for integration router.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/integration/workers/{node_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/integration/workers/{node_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

42. POST /api/v1/integration/workers/{node_id}/drain - Mark worker as draining in integration router.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/integration/workers/{node_id}/drain",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/integration/workers/{node_id}/drain",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

43. GET /api/v1/integration/queue - Read queue status payload.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/integration/queue",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/integration/queue",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

44. GET /api/v1/keys/my-key - Read masked key metadata for legacy key.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/keys/my-key",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/keys/my-key",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

45. POST /api/v1/keys/generate - Rotate and return new legacy key.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/keys/generate",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/keys/generate",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

46. GET /api/v1/keys/my-key/stats - Read key usage stats.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/keys/my-key/stats",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/keys/my-key/stats",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

47. DELETE /api/v1/keys/my-key - Revoke current legacy key.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "DELETE",
  "path": "/api/v1/keys/my-key",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/keys/my-key",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

48. GET /api/v1/keys/admin/all - List all users key status.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/keys/admin/all",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/keys/admin/all",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

49. POST /api/v1/keys/admin/revoke - Force revoke one user key.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/keys/admin/revoke",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/keys/admin/revoke",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

50. GET /api/v1/quota/limits - Read role-based default limits.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/quota/limits",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/quota/limits",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

51. GET /api/v1/quota/me - Read personal quota with overrides if present.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/quota/me",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/quota/me",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

52. PUT /api/v1/quota/admin/user/{roll_number} - Create or update user quota override.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "PUT",
  "path": "/api/v1/quota/admin/user/{roll_number}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/quota/admin/user/{roll_number}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

53. GET /api/v1/quota/admin/exceeded - List users exceeding daily limits.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/quota/admin/exceeded",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/quota/admin/exceeded",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

54. POST /api/v1/guardrails/check-input - Evaluate text against input guardrails.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/guardrails/check-input",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/guardrails/check-input",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

55. POST /api/v1/guardrails/check-output - Evaluate and redact output content.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/guardrails/check-output",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/guardrails/check-output",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

56. GET /api/v1/guardrails/rules - List guardrail rules from database.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/guardrails/rules",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/guardrails/rules",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

57. PUT /api/v1/guardrails/rules - Replace full guardrail ruleset.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "PUT",
  "path": "/api/v1/guardrails/rules",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/guardrails/rules",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

58. POST /api/v1/rag/ingest - Upload and ingest document into RAG.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/rag/ingest",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/rag/ingest",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

59. GET /api/v1/rag/documents - List ingested documents.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/rag/documents",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/rag/documents",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

60. GET /api/v1/rag/documents/{doc_id} - Read one ingested document metadata.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/rag/documents/{doc_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/rag/documents/{doc_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

61. DELETE /api/v1/rag/documents/{doc_id} - Delete document and associated vectors.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "DELETE",
  "path": "/api/v1/rag/documents/{doc_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/rag/documents/{doc_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

62. POST /api/v1/rag/query - Retrieve chunks and generate answer.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/rag/query",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/rag/query",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

63. GET /api/v1/rag/query/{query_id}/sources - Compatibility endpoint for source retrieval.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/rag/query/{query_id}/sources",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/rag/query/{query_id}/sources",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

64. POST /api/v1/rag/collections - Create named collection.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/rag/collections",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/rag/collections",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

65. GET /api/v1/rag/collections - List all collections.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/rag/collections",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/rag/collections",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

66. POST /api/v1/search/web - Web search via SearXNG.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/search/web",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/search/web",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

67. POST /api/v1/search/wikipedia - Wikipedia-focused query.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/search/wikipedia",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/search/wikipedia",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

68. POST /api/v1/search/grounded - Search plus grounded generated answer.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/search/grounded",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/search/grounded",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

69. GET /api/v1/search/cache - Inspect in-memory search cache.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/search/cache",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/search/cache",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

70. POST /api/v1/nodes/enrollment-token - Create one-time enrollment token.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/nodes/enrollment-token",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/enrollment-token",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

71. POST /api/v1/nodes/enroll - Enroll worker node using enrollment token.

Authentication: Token

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/nodes/enroll",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/enroll",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

72. POST /api/v1/nodes/heartbeat/{node_id} - Push worker resource heartbeat.

Authentication: Node

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/nodes/heartbeat/{node_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/heartbeat/{node_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

73. POST /api/v1/nodes/register-model/{node_id} - Register worker model deployment.

Authentication: Node

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/nodes/register-model/{node_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/register-model/{node_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

74. GET /api/v1/nodes - List worker nodes with deployments.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/nodes",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

75. GET /api/v1/nodes/cluster-status - Cluster totals and health summary.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/nodes/cluster-status",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/cluster-status",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

76. GET /api/v1/nodes/{node_id} - Node details with deployment list.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/nodes/{node_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/{node_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

77. POST /api/v1/nodes/{node_id}/drain - Set node draining status.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/nodes/{node_id}/drain",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/{node_id}/drain",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

78. POST /api/v1/nodes/{node_id}/activate - Set node active status.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/nodes/{node_id}/activate",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/{node_id}/activate",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

79. DELETE /api/v1/nodes/{node_id} - Remove node and cascading deployments.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "DELETE",
  "path": "/api/v1/nodes/{node_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/{node_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

80. POST /api/v1/nodes/{node_id}/health-check - Probe worker vLLM health endpoint.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/nodes/{node_id}/health-check",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/{node_id}/health-check",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

81. POST /api/v1/nodes/deploy - Create deployment record on node.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/nodes/deploy",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/deploy",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

82. PUT /api/v1/nodes/deployments/{deployment_id}/status - Update deployment status lifecycle.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "PUT",
  "path": "/api/v1/nodes/deployments/{deployment_id}/status",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/deployments/{deployment_id}/status",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

83. GET /api/v1/nodes/deployments/all - List all deployment records.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/nodes/deployments/all",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/nodes/deployments/all",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

84. GET /api/v1/attendance/subjects - List allowed attendance subjects.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/attendance/subjects",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/subjects",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

85. POST /api/v1/attendance/register-face - Register or update face template.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/attendance/register-face",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/register-face",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

86. GET /api/v1/attendance/face-status - Check if face template is present.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/attendance/face-status",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/face-status",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

87. POST /api/v1/attendance/sessions - Create attendance session.

Authentication: Faculty/Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/attendance/sessions",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/sessions",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

88. POST /api/v1/attendance/sessions/{session_id}/close - Close attendance session.

Authentication: Faculty/Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/attendance/sessions/{session_id}/close",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/sessions/{session_id}/close",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

89. GET /api/v1/attendance/sessions - List attendance sessions with filters.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/attendance/sessions",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/sessions",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

90. POST /api/v1/attendance/mark - Mark attendance for current student.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/attendance/mark",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/mark",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

91. GET /api/v1/attendance/sessions/{session_id}/report - Detailed session report.

Authentication: Faculty/Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/attendance/sessions/{session_id}/report",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/sessions/{session_id}/report",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

92. GET /api/v1/attendance/summary - Cross-session attendance summary.

Authentication: Faculty/Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/attendance/summary",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/attendance/summary",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

93. POST /api/v1/doubts - Create student doubt ticket.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/doubts",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/doubts",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

94. GET /api/v1/doubts/my - List own or assigned doubts depending role.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/doubts/my",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/doubts/my",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

95. GET /api/v1/doubts/all - List all doubts with filters.

Authentication: Faculty/Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/doubts/all",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/doubts/all",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

96. GET /api/v1/doubts/{doubt_id} - Doubt detail with reply thread.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/doubts/{doubt_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/doubts/{doubt_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

97. POST /api/v1/doubts/{doubt_id}/reply - Reply to doubt and notify student.

Authentication: Faculty/Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/doubts/{doubt_id}/reply",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/doubts/{doubt_id}/reply",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

98. POST /api/v1/doubts/{doubt_id}/close - Close doubt ticket.

Authentication: Faculty/Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/doubts/{doubt_id}/close",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/doubts/{doubt_id}/close",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

99. GET /api/v1/notifications - Read paginated in-app notifications.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/notifications",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/notifications",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

100. POST /api/v1/notifications/{notification_id}/read - Mark one notification as read.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/notifications/{notification_id}/read",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/notifications/{notification_id}/read",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

101. POST /api/v1/notifications/read-all - Mark all notifications as read.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/notifications/read-all",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/notifications/read-all",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

102. POST /api/v1/notifications/push/subscribe - Save push subscription keys.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/notifications/push/subscribe",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/notifications/push/subscribe",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

103. GET /api/v1/notifications/vapid-key - Return VAPID key if configured.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/notifications/vapid-key",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/notifications/vapid-key",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

104. GET /api/v1/notifications/audit-logs - List audit logs with filters.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/notifications/audit-logs",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/notifications/audit-logs",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

105. POST /api/v1/scoped-keys - Create scoped API key with limits.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/scoped-keys",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/scoped-keys",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

106. GET /api/v1/scoped-keys/my - List my scoped keys.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/scoped-keys/my",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/scoped-keys/my",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

107. DELETE /api/v1/scoped-keys/{key_id} - Revoke own scoped key.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "DELETE",
  "path": "/api/v1/scoped-keys/{key_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/scoped-keys/{key_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

108. GET /api/v1/scoped-keys/admin/all - List all scoped keys.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/scoped-keys/admin/all",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/scoped-keys/admin/all",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

109. DELETE /api/v1/scoped-keys/admin/{key_id} - Admin revoke scoped key.

Authentication: Admin

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "DELETE",
  "path": "/api/v1/scoped-keys/admin/{key_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/scoped-keys/admin/{key_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

110. POST /api/v1/agent/run - Start agent plan-execute session with SSE output.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "POST",
  "path": "/api/v1/agent/run",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/agent/run",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

111. GET /api/v1/agent/sessions - List user agent sessions.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/agent/sessions",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/agent/sessions",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

112. GET /api/v1/agent/sessions/{session_id} - Get one session details.

Authentication: JWT/API Key

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/agent/sessions/{session_id}",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/agent/sessions/{session_id}",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

113. GET /api/v1/agent/tools - List declared agent tools.

Authentication: No

Integration Notes: Use this route through Nginx /api path in production. Include content-type headers based on body format. For protected routes, pass bearer token as Authorization header.

Request Template:

{
  "request_id": "template-request-id",
  "timestamp": "2026-04-16T00:00:00Z",
  "method": "GET",
  "path": "/api/v1/agent/tools",
  "body": {
    "example_field": "replace-with-route-specific-value",
    "example_flag": true,
    "example_limit": 10
  }
}

Success Response Template:

{
  "status": "ok",
  "endpoint": "/api/v1/agent/tools",
  "data": {
    "result": "example-success-payload",
    "meta": {
      "server_time": "2026-04-16T00:00:00Z",
      "trace_id": "template-trace-id"
    }
  }
}

Error Response Template:

{
  "error": {
    "code": "validation_error",
    "message": "Example failure for documentation template",
    "status": 400
  }
}

14) Extended Data Dictionary Appendix

The following data dictionary expands key tables with practical semantics used by API and service layers. It is designed for backend maintainers, BI consumers, and QA writing DB assertions.

Table: users

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
roll_number	Describes roll_number in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
name	Describes name in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
email	Describes email in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
department	Describes department in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
role	Describes role in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
password_hash	Describes password_hash in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
must_change_password	Describes must_change_password in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
is_active	Describes is_active in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
api_key	Describes api_key in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
failed_login_attempts	Describes failed_login_attempts in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
locked_until	Describes locked_until in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
updated_at	Describes updated_at in the users domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: refresh_tokens

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the refresh_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
user_id	Describes user_id in the refresh_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
token_hash	Describes token_hash in the refresh_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
expires_at	Describes expires_at in the refresh_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
revoked	Describes revoked in the refresh_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the refresh_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: usage_logs

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
user_id	Describes user_id in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
model	Describes model in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
endpoint	Describes endpoint in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
tokens_in	Describes tokens_in in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
tokens_out	Describes tokens_out in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
latency_ms	Describes latency_ms in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
status_code	Describes status_code in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
request_id	Describes request_id in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the usage_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: quota_overrides

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
user_id	Describes user_id in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
daily_tokens	Describes daily_tokens in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
requests_per_hour	Describes requests_per_hour in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
max_tokens_per_request	Describes max_tokens_per_request in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
reason	Describes reason in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_by	Describes created_by in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
updated_at	Describes updated_at in the quota_overrides domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: guardrail_rules

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
category	Describes category in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
action	Describes action in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
pattern	Describes pattern in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
description	Describes description in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
enabled	Describes enabled in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
priority	Describes priority in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
updated_at	Describes updated_at in the guardrail_rules domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: rag_collections

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the rag_collections domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
name	Describes name in the rag_collections domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
description	Describes description in the rag_collections domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
document_count	Describes document_count in the rag_collections domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_by	Describes created_by in the rag_collections domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the rag_collections domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: rag_documents

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
collection_id	Describes collection_id in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
title	Describes title in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
filename	Describes filename in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
content_type	Describes content_type in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
file_size	Describes file_size in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
chunk_count	Describes chunk_count in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
page_count	Describes page_count in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
status	Describes status in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
error_message	Describes error_message in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
uploaded_by	Describes uploaded_by in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the rag_documents domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: worker_nodes

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
name	Describes name in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
hostname	Describes hostname in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
ip_address	Describes ip_address in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
port	Describes port in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
token_hash	Describes token_hash in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
status	Describes status in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
gpu_name	Describes gpu_name in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
gpu_vram_mb	Describes gpu_vram_mb in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
ram_total_mb	Describes ram_total_mb in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
cpu_cores	Describes cpu_cores in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
gpu_util_pct	Describes gpu_util_pct in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
gpu_vram_used_mb	Describes gpu_vram_used_mb in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
ram_used_mb	Describes ram_used_mb in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
cpu_util_pct	Describes cpu_util_pct in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
last_heartbeat	Describes last_heartbeat in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
max_resource_pct	Describes max_resource_pct in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
enrolled_by	Describes enrolled_by in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
updated_at	Describes updated_at in the worker_nodes domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: node_model_deployments

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
node_id	Describes node_id in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
model_id	Describes model_id in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
model_name	Describes model_name in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
served_name	Describes served_name in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
vllm_port	Describes vllm_port in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
status	Describes status in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
gpu_memory_util	Describes gpu_memory_util in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
max_model_len	Describes max_model_len in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
error_message	Describes error_message in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
deployed_by	Describes deployed_by in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
updated_at	Describes updated_at in the node_model_deployments domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: enrollment_tokens

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the enrollment_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
token_hash	Describes token_hash in the enrollment_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
label	Describes label in the enrollment_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
used	Describes used in the enrollment_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
used_by_node_id	Describes used_by_node_id in the enrollment_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
expires_at	Describes expires_at in the enrollment_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_by	Describes created_by in the enrollment_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the enrollment_tokens domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: face_templates

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the face_templates domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
user_id	Describes user_id in the face_templates domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
face_encoding	Describes face_encoding in the face_templates domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
photo_hash	Describes photo_hash in the face_templates domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
captured_at	Describes captured_at in the face_templates domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
updated_at	Describes updated_at in the face_templates domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: attendance_sessions

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
title	Describes title in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
department	Describes department in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
subject	Describes subject in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
session_date	Describes session_date in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
opened_by	Describes opened_by in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
is_open	Describes is_open in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
opened_at	Describes opened_at in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
closed_at	Describes closed_at in the attendance_sessions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: attendance_records

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the attendance_records domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
session_id	Describes session_id in the attendance_records domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
user_id	Describes user_id in the attendance_records domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
face_match_confidence	Describes face_match_confidence in the attendance_records domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
face_verified	Describes face_verified in the attendance_records domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
photo_hash	Describes photo_hash in the attendance_records domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
ip_address	Describes ip_address in the attendance_records domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
marked_at	Describes marked_at in the attendance_records domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: doubts

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
title	Describes title in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
body	Describes body in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
department	Describes department in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
subject	Describes subject in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
target_faculty_id	Describes target_faculty_id in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
student_id	Describes student_id in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
status	Describes status in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
attachment_url	Describes attachment_url in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
attachment_name	Describes attachment_name in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
is_anonymous	Describes is_anonymous in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
updated_at	Describes updated_at in the doubts domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: doubt_replies

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the doubt_replies domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
doubt_id	Describes doubt_id in the doubt_replies domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
author_id	Describes author_id in the doubt_replies domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
body	Describes body in the doubt_replies domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
attachment_url	Describes attachment_url in the doubt_replies domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
attachment_name	Describes attachment_name in the doubt_replies domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the doubt_replies domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: notifications

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the notifications domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
user_id	Describes user_id in the notifications domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
title	Describes title in the notifications domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
body	Describes body in the notifications domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
category	Describes category in the notifications domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
link	Describes link in the notifications domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
is_read	Describes is_read in the notifications domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the notifications domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: push_subscriptions

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the push_subscriptions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
user_id	Describes user_id in the push_subscriptions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
endpoint	Describes endpoint in the push_subscriptions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
p256dh_key	Describes p256dh_key in the push_subscriptions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
auth_key	Describes auth_key in the push_subscriptions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the push_subscriptions domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: audit_logs

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
actor_id	Describes actor_id in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
actor_role	Describes actor_role in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
action	Describes action in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
resource_type	Describes resource_type in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
resource_id	Describes resource_id in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
details	Describes details in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
ip_address	Describes ip_address in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the audit_logs domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

Table: scoped_api_keys

Column	Semantic Meaning	Validation/Usage Note
id	Describes id in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
user_id	Describes user_id in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
name	Describes name in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
key_prefix	Describes key_prefix in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
key_hash	Describes key_hash in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
allowed_models	Describes allowed_models in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
allowed_endpoints	Describes allowed_endpoints in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
requests_per_hour	Describes requests_per_hour in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
tokens_per_day	Describes tokens_per_day in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
max_tokens_per_request	Describes max_tokens_per_request in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
is_active	Describes is_active in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
expires_at	Describes expires_at in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
last_used_at	Describes last_used_at in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
total_requests	Describes total_requests in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
total_tokens	Describes total_tokens in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
created_at	Describes created_at in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
revoked_at	Describes revoked_at in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.
revoked_by	Describes revoked_by in the scoped_api_keys domain lifecycle.	Check nullability, uniqueness, and cross-table FK assumptions during integration tests.

15) Operational Notes and Gaps

The codebase is functionally rich and production-minded, but several areas are important to track while hardening deployment.

Migrations: Alembic folder exists but no version files are present.
Rate limiting: Counters are read from usage_logs, so request spikes can increase DB read load.
Attendance verification: current service uses placeholder hash-based encoding and force-verifies in code.
Integration router naming still references legacy ollama labels in some responses.
Cluster fallback is resilient: local routing remains available if worker health checks fail.
Audit logging is integrated in key admin and security-sensitive actions.

Recommended Hardening Sequence

Create and commit initial Alembic migration from current SQLAlchemy metadata.
Move rate limit counters to Redis primitives for lower DB pressure and clearer window semantics.
Replace attendance placeholder verification with true face embedding workflow and threshold calibration.
Add role-based and scoped-key checks directly into sensitive endpoints where missing.
Add tracing IDs through Nginx, API middleware, and worker agent logs for better observability.

16) Reference Sources

This documentation was compiled from these repository sources:

Category	Representative Files	Used For
App entry and wiring	mac/main.py, mac/config.py, mac/database.py	Router mount points, startup lifecycle, middleware chain, environment contracts.
API behavior	mac/routers/*.py	Endpoint inventory and request-level flow definitions.
Service logic	mac/services/*.py	Model routing, guardrails, RAG logic, search, cluster control, auth internals.
Data model	mac/models/*.py	ER relationships, FK dependencies, domain grouping.
Deployment	docker-compose*.yml, worker-agent.py, nginx/nginx.conf	Single-node and distributed runtime architecture.
Project docs	README.md, docs/CLUSTER-SETUP.md	Operational context and intended deployment patterns.