Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HugoX2003/nisira-assistant/llms.txt

Use this file to discover all available pages before exploring further.

The NISIRA Assistant REST API is a Django REST Framework backend that powers a full-stack Retrieval-Augmented Generation (RAG) chat application. Every endpoint lives under the /api/ prefix, all responses are JSON, and all protected routes require a JWT Bearer token in the Authorization header. The sections below describe the available resource groups, the welcome and utility endpoints, and the error conventions you should expect across the entire API surface.

​
Base URL

/api/
The base URL is relative. The full URL depends on your deployment target:
EnvironmentExample base URL
Local developmenthttp://localhost:8000/api/
Railway (production)https://nisira-assistant-production-6a02.up.railway.app/api/
Set REACT_APP_API_URL (or REACT_APP_API_BASE) in your frontend environment to point the client at the correct host. The frontend axios client uses a default of http://localhost:8000 when neither variable is set.

​
Authentication

All endpoints that handle user data require a JSON Web Token. Obtain a token via the Authentication endpoints, then attach it to every subsequent request: 
Authorization: Bearer <access_token>
Token lifetimes: access token — 24 hours, refresh token — 7 days. The refresh token is rotated on every successful refresh. See the Authentication page for the full flow.

​
Response Format

All responses — success and error alike — are JSON objects. HTTP status codes follow REST conventions:
CodeMeaning
200 OKRequest succeeded
201 CreatedResource created successfully
400 Bad RequestValidation error or missing required field
401 UnauthorizedMissing or invalid JWT token
403 ForbiddenAuthenticated but not permitted (e.g. non-staff access to admin routes)
404 Not FoundResource does not exist or does not belong to the authenticated user
500 Internal Server ErrorUnexpected server-side failure
Error bodies use one of two shapes: 
{ "error": "Descriptive message" }

{ "detail": "Descriptive message" }

​
Client Timeout

RAG queries involve embedding lookups and LLM generation — these operations can take up to 2 minutes. The official frontend client is configured with a 120-second timeout for standard requests and 180 seconds for RAG-enhanced chat. Set your HTTP client timeout accordingly before calling /api/rag/query/ or /api/rag/chat/.

​
Welcome & Utility Endpoints

These endpoints require no authentication and are useful for health checks, deployment verification, and service discovery.
MethodPathDescription
GET/api/Returns API version, status "operational", and a map of key endpoint paths
GET/api/health/Lightweight health check — returns {"status": "healthy"} and a timestamp
GET/api/info/Returns API name, version, description, and an endpoint directory
GET/api/status/Aggregated service status with component health checks and build metadata
curl http://localhost:8000/api/health/

{
  "status": "healthy",
  "timestamp": "2024-11-15T10:23:01.456789",
  "message": "API funcionando correctamente"
}

​
API Groups

Authentication

Register new users, log in, obtain JWT token pairs, and refresh access tokens. All authentication endpoints allow unauthenticated access.

Chat

Send messages to a conversation and receive an assistant reply. The primary endpoint is POST /api/chat/, with a RAG-powered variant at POST /api/rag/chat/.

Conversations

Create, list, retrieve messages from, and delete conversation threads. Conversations are identified by a public slug or a legacy numeric ID.

RAG

Initialize the RAG pipeline, sync documents from Google Drive, run direct retrieval queries, trigger enhanced chat, and inspect pipeline health.

Ratings

Submit thumbs-up / thumbs-down ratings on assistant messages, retrieve aggregated summaries, and export rating data as JSON or CSV.

Admin Endpoints

Admin-only routes covering Google Drive file management, embedding generation and verification, system metrics, query logs, and pipeline status.

​
Auth

The auth group (/api/auth/) handles user identity. All four routes accept unauthenticated requests.
MethodPathDescription
POST/api/auth/register/Create a new user account
POST/api/auth/login/Log in and receive JWT tokens plus user info
POST/api/auth/token/Standard JWT obtain-pair endpoint (username + password → access + refresh)
POST/api/auth/refresh/Exchange a refresh token for a new access token

​
Chat

MethodPathDescription
POST/api/chat/Send a message to an existing conversation; returns a basic assistant reply

​
Conversations

MethodPathDescription
GET/api/conversations/List the authenticated user’s conversations (paginated)
POST/api/conversations/create/Create a new conversation thread
GET/api/conversations/<conversation_id>/messages/Retrieve paginated messages for a conversation
DELETE/api/conversations/<conversation_id>/delete/Permanently delete a conversation and all its messages
<conversation_id> accepts either a short alphanumeric slug (preferred) or a legacy numeric ID.

​
RAG

MethodPathAuthDescription
GET/api/rag/status/RequiredRAG pipeline readiness and component check
POST/api/rag/initialize/RequiredInitialize (or re-initialize) the RAG pipeline
POST/api/rag/sync/RequiredSync documents from Google Drive and build embeddings
POST/api/rag/query/OptionalDirect retrieval query with adaptive top-k document selection
POST/api/rag/chat/RequiredRAG-enhanced chat — retrieves context then generates a response
GET/api/rag/system-status/OptionalDetailed system status from the pipeline
POST /api/rag/query/ and GET /api/rag/system-status/ are decorated with AllowAny — a JWT token is not enforced at the Django permission layer for these two endpoints. All other RAG endpoints require a valid Bearer token.

​
Documents

MethodPathDescription
GET/api/documents/<filename>/Serve a stored document (PDF, etc.) inline — accepts JWT via Authorization header or ?token= query parameter

​
Ratings

MethodPathAuthDescription
POST/api/ratings/RequiredSubmit or update a rating for an assistant message
GET/api/ratings/summary/Staff onlyAggregated rating statistics and recent feedback
GET/api/ratings/export/Staff onlyExport ratings as JSON or CSV (?export_format=csv|json)

​
Experiments & Guardrails

MethodPathAuthDescription
GET/api/experiments/Staff onlyList all A/B experiment runs
GET/api/experiments/latest/Staff onlyRetrieve the most recent experiment run
POST/api/experiments/create/Staff onlyRecord a new experiment run with baseline vs. variant metrics
GET/api/guardrails/status/Staff onlyEvaluate guardrail thresholds across satisfaction rate and feedback queue

​
Admin

All /api/admin/* routes require is_staff = True on the authenticated user.
GroupPaths
Driveadmin/drive/files/, admin/drive/upload/, admin/drive/delete/<file_id>/, admin/drive/sync/, admin/drive/sync/progress/
Embeddingsadmin/embeddings/status/, admin/embeddings/generate/, admin/embeddings/verify/, admin/embeddings/clear/, admin/embeddings/progress/, admin/embeddings/processed/, admin/embeddings/delete/<file_name>/
Metricsadmin/metrics/, admin/metrics/queries/, admin/metrics/queries/<query_id>/, admin/metrics/ratings/
Pipelineadmin/pipeline/status/

Build docs developers (and LLMs) love

Get started for freeTalk to us