Skip to content
Services Technical Documentation

Complete API Surface & Endpoint Contracts

Complete API Surface & Endpoint Contracts

This page is the canonical API Reference Manual for the backend application. All business routes are versioned under /api/v1/.

1. Global Request & Response Contracts

A. Authentication Headers

All endpoints (except public infrastructure/auth endpoints) require one of the following authentication headers:

  • Bearer Token: Authorization: Bearer <jwt_access_token>
  • API Key: X-API-Key: <api_key_string>
  • Microsoft OAuth: Session-backed or token-backed SSO verification.

B. Standardized Response Formats

Success Response (200 OK / 201 Created / 202 Accepted)

{
  "success": true,
  "data": {},
  "message": "Optional operational summary"
}

Error Response (400 / 401 / 403 / 404 / 422 / 500)

{
  "success": false,
  "error_code": "ERROR_CATEGORY_CODE",
  "message": "Human-readable description of the failure",
  "details": {}
}

2. Complete API Endpoint Reference Matrix

A. Authentication & User Profile (/api/v1/auth/)

MethodEndpoint RouteView ClassAuth RequiredParameters / HeadersRequest Body SchemaSuccess ResponseError Codes
POST/api/v1/auth/login/CustomLoginAPIViewNone (Public)Header: Content-Type: application/json{"email": "string", "password": "string"}200 OK
{"access": "jwt", "refresh": "jwt", "user": {}}		INVALID_CREDENTIALS
ACCOUNT_DISABLED
POST/api/v1/auth/refresh/TokenRefreshAPIViewNone (Public)Header: Content-Type: application/json{"refresh": "jwt_refresh_token"}200 OK
{"access": "new_jwt_token"}		TOKEN_EXPIRED
INVALID_TOKEN
POST/api/v1/auth/microsoft/MicrosoftAuthViewNone (Public)Header: Content-Type: application/json{"access_token": "ms_oauth_token"}200 OK
{"access": "jwt", "user": {}, "tenants": []}		MS_AUTH_FAILED
USER_NOT_FOUND
GET/api/v1/auth/profile/UserProfileAPIViewBearer / SessionHeader: Authorization: Bearer <token>None200 OK
{"id": 1, "email": "...", "roles": []}		UNAUTHORIZED

B. Document Upload & Processing Lifecycle (/api/v1/)

MethodEndpoint RouteView ClassAuth RequiredParameters / HeadersRequest Body SchemaSuccess ResponseError Codes
POST/api/v1/process-document/upload/DocumentUploadAPIViewBearer / API KeyMultipart Form Datafile: binary (PDF/Image)
schema_id: int/str
country_id: int
model_id: int		202 Accepted
{"task_id": "uuid", "status": "PENDING", "doc_id": 123}		FILE_TOO_LARGE
INVALID_MIME_TYPE
SCHEMA_NOT_FOUND
GET/api/v1/task-status/<task_id>/TaskStatusAPIViewBearer / API KeyPath: task_id (str)None200 OK
{"task_id": "...", "status": "COMPLETED", "result": {}}		TASK_NOT_FOUND
GET/api/v1/document-status/<doc_id>/DocumentStatusAPIViewBearer / API KeyPath: doc_id (int)None200 OK
{"doc_id": 123, "status": "PROCESSED", "extraction": {}}		DOCUMENT_NOT_FOUND
GET/api/v1/metaprocessing/<file_id>/MetaprocessingAPIViewBearer / API KeyPath: file_id (int)None200 OK
{"file_id": 123, "pages": [], "confidence": 0.95}		FILE_NOT_FOUND
GET/POST/api/v1/processing-documents/ProcessingDocumentViewSetBearer / API KeyQuery: page, page_size, statusPOST: ProcessingDocument payload200 OK (list) / 201 CreatedVALIDATION_ERROR

C. Schema Management & Schema Generation (/api/v1/schema/)

MethodEndpoint RouteView ClassAuth RequiredParameters / HeadersRequest Body SchemaSuccess ResponseError Codes
GET/api/v1/schema/SchemaViewSetBearer / API KeyQuery: search, page, tenant_idNone200 OK
{"results": [{"schema_uid": "...", "name": "..."}]}		UNAUTHORIZED
POST/api/v1/schema/SchemaViewSetBearer / API KeyHeader: Content-Type: application/json{"name": "...", "fields": [], "description": "..."}201 Created
{"schema_uid": "...", "name": "..."}		DUPLICATE_SCHEMA_NAME
INVALID_FIELDS
GET/api/v1/schema/<schema_uid>/SchemaViewSetBearer / API KeyPath: schema_uid (str)None200 OK
{"schema_uid": "...", "fields": [...]}		SCHEMA_NOT_FOUND
POST/api/v1/schema/generate/SchemaViewSetBearer / API KeyMultipart Form Datauploaded_file: binary
country_id: int
model_id: int		202 Accepted
{"job_id": "uuid", "status": "PROCESSING"}		LLM_GENERATION_FAILED
UNSUPPORTED_FILE
POST/api/v1/schema/import_schemas/SchemaViewSetBearer / API KeyMultipart / JSON{"file": "schema_backup.json"}200 OK
{"imported_count": 5}		INVALID_IMPORT_FORMAT
GET/api/v1/schema/export_schemas/SchemaViewSetBearer / API KeyQuery: schema_uids (comma-separated)None200 OK (JSON file download)EXPORT_FAILED

D. Multi-Tenancy & Org Management (/api/v1/tenants/ & /api/v1/org/)

MethodEndpoint RouteView ClassAuth RequiredParameters / HeadersRequest Body SchemaSuccess ResponseError Codes
GET/POST/api/v1/tenants/TenantViewSetBearer / AdminQuery: page, search{"name": "Tenant Name", "subdomain": "abc"}200 OK / 201 CreatedSUBDOMAIN_EXISTS
GET/POST/api/v1/tenants/<tenant_id>/members/TenantMembershipViewSetBearer / TenantAdminPath: tenant_id{"user_email": "...", "role": "admin"}200 OK / 201 CreatedMEMBER_ALREADY_EXISTS
POST/api/v1/org/invite/OrgInviteViewBearer / AdminHeader: Content-Type: application/json{"email": "user@org.com", "role": "member"}200 OK
{"invite_token": "...", "status": "SENT"}		USER_ALREADY_MEMBER

E. File Management & Secure Serving (/api/v1/files/)

MethodEndpoint RouteView ClassAuth RequiredParameters / HeadersRequest Body SchemaSuccess ResponseError Codes
POST/api/v1/upload-file/FileUploadAPIViewBearer / API KeyMultipart Form Datafile: binary201 Created
{"file_id": 456, "file_name": "..."}		VIRUS_SCAN_FAILED
FILE_TOO_LARGE
GET/api/v1/files/user/<file_id>/JWTFileServeViewBearer JWTPath: file_id (int)None200 OK (Binary Stream)FILE_NOT_FOUND
PERMISSION_DENIED
GET/api/v1/files/processed/<file_id>/JWTFileServeViewBearer JWTPath: file_id (int)None200 OK (Binary Stream)FILE_NOT_FOUND
GET/api/v1/preview/processed/<file_id>/serve_processed_file_imageBearer / SessionPath: file_id (int)None200 OK (image/png / image/jpeg)IMAGE_GENERATION_FAILED

F. Billing, Activity Logs, Chatbot & Infrastructure

MethodEndpoint RouteView ClassAuth RequiredParameters / HeadersRequest Body SchemaSuccess ResponseError Codes
GET/api/v1/billing/plan/BillingPlanViewBearer / AdminQuery: tenant_idNone200 OK
{"plan_name": "Enterprise", "quota": 10000}		BILLING_RECORD_NOT_FOUND
GET/api/v1/billing/usage/BillingUsageViewBearer / AdminQuery: month, yearNone200 OK
{"used_pages": 450, "remaining": 9550}		UNAUTHORIZED
GET/api/v1/admin/activity-logs/ActivityLogListViewBearer / AdminQuery: action, user_id, start_dateNone200 OK
{"results": [{"id": "uuid", "action": "..."}]}		FORBIDDEN
POST/api/v1/chatbot/ChatbotAPIViewPublic / SessionHeader: Content-Type: application/json{"message": "Hello", "conversation_id": "..."}200 OK
{"reply": "...", "conversation_id": "..."}		LITELLM_TIMEOUT
GET/api/health/health_checkNone (Public)NoneNone200 OK
{"status": "healthy", "database": "up"}		SERVICE_UNHEALTHY (503)

3. Sequence Flow Diagram: Document Processing API Contract

sequenceDiagram
    autonumber
    actor Client as Frontend / API Client
    participant Gateway as Django API Gateway
    participant View as DocumentUploadAPIView
    participant Task as Celery Worker
    participant Storage as Cloud Storage / DB


    Client->>Gateway: POST /api/v1/process-document/upload/ (Multipart File + Headers)
    Gateway->>View: Authenticate & Validate Request
    alt Validation Failure
        View-->>Client: 400 Bad Request / 422 Unprocessable (Error JSON)
    else Validation Success
        View->>Storage: Persist uploaded file record & metadata
        View->>Task: Queue background processing task (task_id)
        View-->>Client: 202 Accepted {"task_id": "abc-123", "status": "PENDING"}
    end


    loop Poll Status
        Client->>Gateway: GET /api/v1/task-status/abc-123/
        Gateway-->>Client: 200 OK {"status": "PROCESSING" | "COMPLETED"}
    end

4. Verification Tests

  • tests/unit/api/test_api_endpoints.py — Verifies route availability and URL reversing.
  • tests/integration/test_viewsets.py — Validates DRF viewset permissions and serializations.
  • tests/unit/schema/test_schema_generator_endpoints.py — Proves schema generation API contracts.