API Reference¶

Complete reference for all REST API endpoints exposed by the backend server. All routes are prefixed with /api/v1. For details on how the frontend calls these endpoints, see the Frontend API Integration page.

Overview¶

Authorization Levels¶

The API uses a dependency injection chain for authorization. For a detailed breakdown of how this chain works, see the Security & Auth page.

Authentication¶

POST /api/v1/auth/register¶

Register a new user account. No authentication required.

Auth: None

Request Body:

{
    "full_name": "John Doe",
    "email": "john@example.com",
    "username": "johndoe",
    "password": "20-Na$$aQ-26"
}

Response: 201 Created

{
    "user_id": 1,
    "full_name": "John Doe",
    "email": "john@example.com",
    "username": "johndoe",
    "role": null,
    "is_active": false,
    "created_at": "2026-02-26T14:30:00"
}

Error Responses:

POST /api/v1/auth/login¶

Authenticate with email and password using OAuth2 password flow.

Auth: None

Request Body: application/x-www-form-urlencoded

curl -X POST http://localhost:8000/api/v1/auth/login \
  -d "username=john@example.com&password=20-Na$$aQ-26"

Response: 200 OK

{
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer"
}

Error Responses:

POST /api/v1/auth/refresh¶

Refresh an access token using a valid refresh token.

Auth: Bearer token (refresh token)

Request: Send the refresh token as a Bearer token in the Authorization header.

curl -X POST http://localhost:8000/api/v1/auth/refresh \
  -H "Authorization: Bearer <refresh_token>"

Response: 200 OK

{
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer"
}

Error Responses:

Users¶

GET /api/v1/users/¶

List all users with pagination.

Auth: AdminUser

Query Parameters:

Response: 200 OK -- Array of UserResponse

GET /api/v1/users/pending¶

List users pending role assignment (is_active=false).

Auth: AdminUser

Query Parameters:

Response: 200 OK -- Array of UserResponse

GET /api/v1/users/me¶

Get the current authenticated user's profile.

Auth: CurrentUser

Response: 200 OK

{
    "user_id": 1,
    "full_name": "John Doe",
    "email": "john@example.com",
    "username": "johndoe",
    "role": "Admin",
    "is_active": true,
    "created_at": "2026-02-26T14:30:00"
}

PATCH /api/v1/users/me¶

Update the current user's profile (name and username only).

Auth: ActiveUser

Request Body:

{
    "full_name": "John Updated",
    "username": "johnupdated"
}

Response: 200 OK -- Updated UserResponse

Error Responses:

PATCH /api/v1/users/{user_id}¶

Update any user's profile (admin only).

Auth: AdminUser

Path Parameters:

Request Body:

{
    "full_name": "Updated Name",
    "email": "new@example.com",
    "username": "newusername",
    "role_id": 2,
    "is_active": true
}

Response: 200 OK -- Updated UserResponse

Error Responses:

PATCH /api/v1/users/{user_id}/activate¶

Activate a user (set is_active=true). No request body allowed.

Auth: AdminUser

Response: 200 OK -- Updated UserResponse

Error Responses:

DELETE /api/v1/users/{user_id}¶

Delete a user account.

Auth: AdminUser

Response: 204 No Content

Error Responses:

Documents¶

POST /api/v1/docs/upload¶

Upload a file for OCR processing.

Auth: ActiveUser

Request: multipart/form-data

curl -X POST http://localhost:8000/api/v1/docs/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@document.pdf" \
  -F "full_path=finance/reports"

Processing Flow:

sequenceDiagram
    participant Client
    participant Server
    participant Blob as Azure Blob
    participant DB as SQL Server
    participant RMQ as RabbitMQ

    Client->>Server: POST /docs/upload (file + metadata)
    Server->>Server: Validate path exists
    Server->>Server: Check file size (max 50 MB)
    Server->>Blob: Upload file
    Blob-->>Server: Blob URL
    Server->>DB: Create Documents record
    Server->>DB: Create ProcessingStatus (Queued)
    Server->>RMQ: Publish to ocr_queue
    Server->>DB: Commit transaction
    Server-->>Client: 201 Created

Response: 201 Created

{
    "filename": "document.pdf",
    "path": "https://account.blob.core.windows.net/container/finance/reports/document.pdf",
    "ctype": "application/pdf",
    "size": 1048576,
    "metadata": {
        "description": null,
        "full_path": "finance/reports"
    }
}

Error Responses:

GET /api/v1/docs/¶

List all documents with pagination and filtering (admin only).

Auth: AdminUser

Query Parameters:

Response: 200 OK

{
    "total": 42,
    "items": [
        {
            "doc_id": 1,
            "filename": "report.pdf",
            "path": "/finance",
            "uploaded_by_user_id": 7,
            "uploaded_at": "2026-02-26T14:30:00",
            "status": "Finished",
            "error_message": null
        }
    ]
}

GET /api/v1/docs/me¶

List the current user's documents with pagination and filtering.

Auth: ActiveUser

Query Parameters: Same as GET /api/v1/docs/ except user_id (automatically scoped to current user).

Response: 200 OK -- Same format as above.

GET /api/v1/docs/{doc_id}/status¶

Check the OCR processing status for a specific document. Only returns results for documents owned by the current user.

Auth: ActiveUser

Response: 200 OK

{
    "doc_id": 1,
    "filename": "report.pdf",
    "stage_name": "OCR",
    "status": "Finished",
    "start_time": "2026-02-26T14:30:05",
    "end_time": "2026-02-26T14:30:12",
    "error_message": null
}

Status Values:

DELETE /api/v1/docs/{doc_id}¶

Delete a document's database records and its blob from storage.

Auth: AdminUser

Response: 200 OK

{
    "doc_id": 1,
    "message": "Document deleted successfully."
}

Error Responses:

Virtual Paths¶

Virtual paths represent a folder hierarchy in Azure Blob Storage. They are stored in the Virtual_Paths table and used to organize uploaded documents.

GET /api/v1/paths/¶

List all virtual paths with depth filtering and prefix search.

Auth: ActiveUser

Query Parameters:

Response: 200 OK

[
    {
        "id": 1,
        "full_path": "/",
        "description": "Root directory",
        "depth": 0,
        "created_at": "2026-01-01T00:00:00"
    },
    {
        "id": 2,
        "full_path": "finance/reports",
        "description": "Financial reports",
        "depth": 2,
        "created_at": "2026-02-15T10:00:00"
    }
]

POST /api/v1/paths/¶

Create a new virtual path.

Auth: AdminUser

Request Body:

{
    "full_path": "finance/reports/2026",
    "description": "2026 financial reports"
}

Response: 201 Created -- PathResponse

The depth is calculated automatically from the number of path segments.

Error Responses:

PATCH /api/v1/paths/{path_id}¶

Update an existing path's full_path and/or description.

Auth: AdminUser

Request Body:

{
    "full_path": "finance/reports/updated",
    "description": "Updated description"
}

Response: 200 OK -- Updated PathResponse

Error Responses:

DELETE /api/v1/paths/{path_id}¶

Delete a virtual path.

Auth: AdminUser

Response: 204 No Content

Error Responses:

Common Error Format¶

All error responses follow this format:

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

Authentication errors include a WWW-Authenticate header:

WWW-Authenticate: Bearer

Schemas Reference¶

UserResponse¶

{
    "user_id": "int",
    "full_name": "string",
    "email": "string (email)",
    "username": "string",
    "role": "string | null",
    "is_active": "bool",
    "created_at": "datetime"
}

TokenLogin¶

{
    "access_token": "string (JWT)",
    "refresh_token": "string (JWT)",
    "token_type": "bearer"
}

TokenRefresh¶

{
    "access_token": "string (JWT)",
    "token_type": "bearer"
}

DocumentListItem¶

{
    "doc_id": "int",
    "filename": "string",
    "path": "string",
    "uploaded_by_user_id": "int",
    "uploaded_at": "datetime",
    "status": "string | null",
    "error_message": "string | null"
}

DocumentListResponse¶

{
    "total": "int",
    "items": "DocumentListItem[]"
}

FileUploadResponse¶

{
    "filename": "string",
    "path": "string (URL or path)",
    "ctype": "string (MIME type)",
    "size": "int (bytes)",
    "metadata": {
        "description": "string | null",
        "full_path": "string"
    }
}

PathResponse¶

{
    "id": "int",
    "full_path": "string",
    "description": "string | null",
    "depth": "int",
    "created_at": "datetime"
}