query-orchestration/docs/ai.generated/03-api-documentation.md

# API Documentation

## API Overview

The DoczyAI Query Orchestration Platform exposes a comprehensive REST API following OpenAPI 3.0.3 specification. The API is automatically generated from the specification file `serviceAPIs/queryAPI.yaml` using oapi-codegen.

### Base Configuration
- **Base URL**: `https://doczy.com/v1` (production), `http://localhost:8080` (development)
- **API Version**: 0.0.1
- **Content Type**: `application/json`
- **Documentation**: Auto-generated Swagger UI at `/swagger/index.html`

### API Services

The API is organized into the following service groups:

| Service | Description |
|---------|-------------|
| ClientService | Operations related to clients |
| CollectorService | Operations related to collectors |
| DocumentsService | Operations related to documents |
| FolderService | Operations related to document folders and organization |
| LabelService | Operations related to document labels and workflow tracking |
| FieldExtractionService | Operations related to document field extractions |
| QueryService | Operations related to queries |
| ExportService | Operations related to exports |
| AuthService | Operations related to authentication |
| AdminService | Operations related to user management and administration |

## Authentication and Authorization

### Security Schemes

#### JWT Authentication
- **Type**: Bearer token authentication
- **Header**: `Authorization: Bearer <token>`
- **Token Source**: JWT cookie set via OAuth flow

#### OAuth2 Flow
- **Type**: OAuth2 Authorization Code Flow
- **Provider**: AWS Cognito
- **Scopes**: `openid`, `email`, `profile`

### Authentication Endpoints

#### `GET /login`
Initiates OAuth2 authentication flow with AWS Cognito.

**Security**: Public (no authentication required)
**Response**: `302` Redirect to Cognito login page

#### `GET /login-callback`
OAuth2 callback handler that processes authentication response.

**Security**: Public
**Parameters**:
- `code` (query, required): Authorization code from Cognito (max 2048 chars)
- `state` (query, required): CSRF protection parameter (max 1024 chars)

**Response**: `302` Sets JWT cookie and redirects to application

#### `GET /logout`
Terminates user session and clears authentication cookies.

**Security**: Requires JWT authentication
**Response**: `302` Redirect to Cognito logout page or application home

#### `GET /home`
Returns the HTML menu page for authenticated users.

**Security**: Requires JWT authentication
**Response**: `200` HTML content

## Rate Limiting

The queryAPI service implements dual-layer rate limiting to protect against DDoS attacks and ensure fair resource allocation.

### Rate Limit Architecture

**Dual-Layer Protection:**
- **Layer 1: Global/Aggregate Rate Limiting** - Protects total system capacity across all IP addresses
- **Layer 2: Per-IP Rate Limiting** - Prevents individual client abuse

Both layers must pass for a request to proceed. The global limiter checks first for faster failure paths under DDoS conditions.

### Default Rate Limits

By default, all endpoints are limited to:
- **Global**: 500 requests per second total (1000 burst)
- **Per-IP**: 5 requests per second per IP (10 burst)
- **Cleanup Interval**: 3 minutes for inactive IP limiters

**Important:** No endpoints are exempt from rate limiting. This is a security requirement to prevent DDoS attacks.

### Configuration

Rate limits are configured via environment variables:

```bash
# Global/Aggregate rate limiting (protects total system capacity)
RATE_LIMIT_GLOBAL_RATE=500         # total req/s across ALL IPs
RATE_LIMIT_GLOBAL_BURST=1000        # total burst capacity across ALL IPs

# Per-IP rate limiting (protects against individual abusers)
RATE_LIMIT_DEFAULT_RATE=5          # req/s per IP
RATE_LIMIT_DEFAULT_BURST=10         # burst per IP
RATE_LIMIT_EXPIRES_IN=180           # seconds (3 minutes)

# Per-endpoint overrides (JSON format)
RATE_LIMIT_ENDPOINT_OVERRIDES={}
```

### Rate Limit Headers

All API responses include a `RateLimit` header indicating the current limit:

```
RateLimit: 20;window=2
```

**Format:** `{burst};window={seconds}`

### Rate Limit Exceeded Response

**HTTP Status:** `429 Too Many Requests`

**Headers:**
- `Retry-After: {seconds}` - Number of seconds before retrying
- `RateLimit: {burst};window={seconds}` - Current rate limit

**Response Body:**
```json
{
  "message": "rate limit exceeded"
}
```

---

## Client Management (ClientService)

### `POST /client`
Creates a new client in the system.

**Security**: Requires JWT authentication

**Request Body** (`ClientCreate`):
```json
{
  "id": "string (max 36 chars, required)",
  "name": "string (max 256 chars, required)"
}
```

**Responses**:
- `201`: Client created successfully
  ```json
  {
    "id": "AAA"
  }
  ```
- `400`: Invalid request data
- `401`: Authentication required
- `429`: Rate limit exceeded
- `500`: Internal server error

### `GET /client/{id}`
Retrieves client details by ID.

**Security**: Requires JWT authentication

**Path Parameters**:
- `id`: Client identifier (string, max 36 chars)

**Response** (`DocClient`):
```json
{
  "id": "AAA",
  "name": "ACME Corporation",
  "can_sync": true
}
```

### `PATCH /client/{id}`
Updates client information.

**Security**: Requires JWT authentication

**Request Body** (`ClientUpdate`):
```json
{
  "name": "string (max 256 chars, optional)",
  "can_sync": "boolean (optional)"
}
```

**Response**: `200` Client updated successfully

### `GET /client/{id}/status`
Returns client synchronization status.

**Security**: Requires JWT authentication

**Response** (`ClientStatusBody`):
```json
{
  "status": "IN_SYNC"
}
```

**Status Values**: `IN_SYNC`, `NOT_SYNCED`, `NOT_SYNCING`

---

## Document Operations (DocumentsService)

### `POST /client/{id}/document`
Uploads a document for a specific client.

**Security**: Requires JWT authentication
**Content Type**: `multipart/form-data`
**Max File Size**: 100GB

**Form Parameters**:
- `file` (required): Document file (PDF)
- `filename` (optional): Custom filename (max 4096 chars)

**Response**: `200` Document uploaded

### `GET /client/{id}/document`
Lists documents for a client.

**Security**: Requires JWT authentication

**Response** (`ListDocuments`):
```json
[
  {
    "id": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
    "hash": "sha256:abc123..."
  }
]
```

### `GET /document/{id}`
Retrieves document details by ID.

**Security**: Requires JWT authentication

**Path Parameters**:
- `id`: Document UUID (max 36 chars)

**Response** (`Document`):
```json
{
  "id": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
  "client_id": "AAA",
  "hash": "sha256:abc123...",
  "fields": {
    "property1": "string value",
    "property2": 42
  }
}
```

---

## Batch Document Operations (DocumentsService)

### `POST /client/{id}/document/batch`
Uploads a ZIP archive containing multiple PDF documents for asynchronous batch processing.

**Security**: Requires JWT authentication
**Content Type**: `multipart/form-data`
**Max Archive Size**: 1GB
**Supported Archive Type**: ZIP only

**Form Parameters**:
- `archive` (required): ZIP file containing PDF documents

**Response** (`202 Accepted`):
```json
{
  "batch_id": "019580df-ef65-7676-8de9-94435a93337a",
  "status": "processing",
  "status_url": "/client/AAA/document/batch/019580df-ef65-7676-8de9-94435a93337a"
}
```

### `GET /client/{id}/document/batch`
Lists batch uploads for a client with pagination support.

**Security**: Requires JWT authentication

**Query Parameters**:
- `limit`: Maximum results (integer, 1-100, default: 20)
- `offset`: Pagination offset (integer, default: 0)

**Response** (`BatchUploadList`):
```json
{
  "batches": [
    {
      "batch_id": "019580df-ef65-7676-8de9-94435a93337a",
      "client_id": "AAA",
      "original_filename": "documents.zip",
      "status": "completed",
      "total_documents": 100,
      "processed_documents": 100,
      "failed_documents": 2,
      "invalid_type_documents": 1,
      "progress_percent": 100,
      "created_at": "2024-01-01T00:00:00Z",
      "completed_at": "2024-01-01T00:05:00Z"
    }
  ],
  "total_count": 25
}
```

**Batch Status Values**: `processing`, `completed`, `failed`, `cancelled`

### `GET /client/{id}/document/batch/{batch_id}`
Retrieves detailed status information for a specific batch upload.

**Security**: Requires JWT authentication

**Path Parameters**:
- `batch_id`: Batch upload identifier (UUID)

**Response** (`BatchUploadDetails`):
```json
{
  "batch_id": "019580df-ef65-7676-8de9-94435a93337a",
  "client_id": "AAA",
  "original_filename": "documents.zip",
  "status": "completed",
  "total_documents": 100,
  "processed_documents": 100,
  "failed_documents": 2,
  "invalid_type_documents": 1,
  "progress_percent": 100,
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:05:00Z",
  "failed_filenames": ["doc3.pdf", "doc17.pdf"]
}
```

### `DELETE /client/{id}/document/batch/{batch_id}`
Cancels a batch upload that is currently processing.

**Security**: Requires JWT authentication

**Response**:
- `204`: Batch upload cancelled successfully
- `404`: Batch not found

---

## Folder Operations (FolderService)

### Folder Path Constraints

All folder paths must comply with the following constraints when creating or renaming folders:

- **Must start with `/`**: All paths must begin with a forward slash
- **Maximum path length**: 1000 characters
- **Maximum segment length**: 255 characters per path segment
- **Maximum depth**: 20 levels of nesting
- **Valid characters only**: Alphanumeric (`a-z`, `A-Z`, `0-9`), hyphen (`-`), underscore (`_`), period (`.`), and space (` `)
- **Segment must start with alphanumeric**: Each path segment must begin with a letter or number
- **No empty segments**: Double slashes (`//`) or trailing slashes are not allowed
- **No path traversal**: Sequences like `..` or `./` are blocked
- **No hidden folders**: Segments cannot start with a period (e.g., `/.hidden`)
- **No leading/trailing whitespace**: Spaces within segment names are allowed, but not at the start or end
- **No control characters**: ASCII control characters (0x00-0x1F, 0x7F) are blocked
- **No Windows reserved names**: Names like `CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9`, `LPT1`-`LPT9` are blocked
- **Root folder restrictions**: The root path `/` can only exist once per client and cannot be renamed
- **Path uniqueness**: Each path must be unique within a client (enforced by database)
- **Unicode normalization**: Paths are normalized to NFC form

**Valid path examples**:
- `/documents`
- `/documents/2024/Q1`
- `/client-data/reports_2024`
- `/My Documents/Archive`

**Invalid path examples**:
- `documents` (missing leading `/`)
- `/documents/` (trailing slash)
- `/foo//bar` (empty segment)
- `/foo/../bar` (path traversal)
- `/.hidden` (dot prefix)
- `/foo@bar` (invalid character)
- `/CON` (Windows reserved name)

---

### `GET /clients/{clientId}/folders`
Lists all folders for a specific client, including the folder hierarchy.

**Security**: Requires JWT authentication

**Path Parameters**:
- `clientId`: Client external ID (string, max 36 chars)

**Response** (`200 OK`):
```json
{
  "folders": [
    {
      "id": "019580df-ef65-7676-8de9-94435a93337a",
      "path": "/",
      "parentId": null,
      "clientId": "AAA",
      "createdAt": "2025-10-16T14:27:15Z",
      "createdBy": "system"
    },
    {
      "id": "019580df-ef65-7676-8de9-94435a93337b",
      "path": "/documents",
      "parentId": "019580df-ef65-7676-8de9-94435a93337a",
      "clientId": "AAA",
      "createdAt": "2025-10-16T14:30:00Z",
      "createdBy": "user@example.com"
    },
    {
      "id": "019580df-ef65-7676-8de9-94435a93337c",
      "path": "/documents/2024",
      "parentId": "019580df-ef65-7676-8de9-94435a93337b",
      "clientId": "AAA",
      "createdAt": "2025-10-16T14:35:00Z",
      "createdBy": "user@example.com"
    }
  ]
}
```

**Notes**:
- Returns all folders for the client, including nested folders
- Folders are returned in a flat list; use `parentId` to reconstruct the hierarchy
- The root folder (path="/") is included if it exists

### `POST /folders`
Creates a new folder for organizing documents.

**Security**: Requires JWT authentication

**Request Body** (`FolderCreate`):
```json
{
  "path": "/documents/2024",
  "clientId": "AAA",
  "createdBy": "user@example.com",
  "parentId": "019580df-ef65-7676-8de9-94435a93337a"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| path | string | Yes | Folder path, must start with "/" (max 1000 chars) |
| clientId | string | Yes | Client external ID |
| createdBy | string | Yes | Email of user creating the folder |
| parentId | uuid | No | Parent folder ID for nested folders |

**Response** (`201 Created`):
```json
{
  "id": "019580df-ef65-7676-8de9-94435a93337a",
  "path": "/documents/2024",
  "parentId": null,
  "clientId": "AAA",
  "createdAt": "2025-10-16T14:27:15Z",
  "createdBy": "user@example.com"
}
```

### `PATCH /folders/{folderId}`
Renames an existing folder.

**Security**: Requires JWT authentication

**Path Parameters**:
- `folderId`: Folder UUID

**Request Body** (`FolderRename`):
```json
{
  "path": "/documents/2024-renamed"
}
```

**Response** (`200 OK`): Updated folder object

### `GET /folders/{folderId}/documents`
Retrieves all documents within a specific folder.

**Security**: Requires JWT authentication

**Response**:
```json
{
  "documents": [
    {
      "id": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
      "client_id": "AAA",
      "hash": "sha256:abc123...",
      "fields": {}
    }
  ]
}
```

### `GET /folders/{folderId}/metrics`
Retrieves processing progress metrics for documents in a folder.

**Security**: Requires JWT authentication

**Response** (`FolderMetrics`):
```json
{
  "folderId": "019580df-ef65-7676-8de9-94435a93337a",
  "totalDocuments": 150,
  "byLabel": {
    "Ingested": 150,
    "OCR_Processed": 120,
    "Dashboard_Ready": 100
  }
}
```

---

## Label Operations (LabelService)

### `POST /documents/{documentId}/labels`
Applies a workflow label to a document for tracking processing state.

**Security**: Requires JWT authentication

**Path Parameters**:
- `documentId`: Document UUID

**Request Body** (`LabelApplication`):
```json
{
  "label": "OCR_Processed",
  "appliedBy": "user@example.com"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| label | string | Yes | Label name (alphanumeric and underscore only, max 100 chars) |
| appliedBy | string | Yes | Email of user applying the label |

**Response** (`201 Created`):
```json
{
  "id": "019580df-ef65-7676-8de9-94435a93337a",
  "documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
  "label": "OCR_Processed",
  "appliedBy": "user@example.com",
  "appliedAt": "2025-10-16T14:27:15Z"
}
```

### `GET /documents/{documentId}/labels`
Retrieves all labels that have been applied to a document, ordered by most recent first.

**Security**: Requires JWT authentication

**Response**:
```json
{
  "labels": [
    {
      "id": "019580df-ef65-7676-8de9-94435a93337a",
      "documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
      "label": "OCR_Processed",
      "appliedBy": "user@example.com",
      "appliedAt": "2025-10-16T14:27:15Z"
    }
  ]
}
```

### `GET /labels/{labelName}/documents`
Retrieves all documents that have been tagged with a specific label.

**Security**: Requires JWT authentication

**Path Parameters**:
- `labelName`: Label name (alphanumeric and underscore only, max 100 chars)

**Query Parameters**:
- `clientId` (required): Client ID to filter documents (UUID)

**Response**:
```json
{
  "documents": [
    {
      "id": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
      "hash": "sha256:abc123..."
    }
  ]
}
```

---

## Field Extraction Operations (FieldExtractionService)

### `POST /field-extractions`
Creates a new field extraction with single-value and array fields for a document.

**Security**: Requires JWT authentication

**Request Body** (`FieldExtractionRequest`):
```json
{
  "documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
  "singleFields": {
    "fileName": "contract_2024.pdf",
    "contractTitle": "Service Agreement",
    "clientName": "ACME Corp",
    "payerName": "Insurance Co",
    "payerState": "CA",
    "providerState": "NY",
    "aareteDerivedEffectiveDt": "2024-01-01",
    "aareteDerivedTerminationDt": "2025-12-31",
    "autoRenewalInd": true
  },
  "arrayFields": [
    {
      "exhibitTitle": "Exhibit A",
      "exhibitPage": "15",
      "reimbProvTin": "123456789",
      "reimbProvNpi": "1234567890",
      "reimbProvName": "Provider Name",
      "reimbEffectiveDt": "2024-01-01",
      "aareteDerivedClaimTypeCd": "INPATIENT",
      "aareteDerivedReimbMethod": "Per Diem",
      "reimbPctRate": 85.5,
      "reimbFeeRate": 150.00
    }
  ],
  "createdBy": "user@example.com"
}
```

**Single Fields** (1:1 relationship with document):
- `fileName`, `contractTitle`, `clientName`, `payerName`
- `payerState`, `providerState` (2-letter state codes)
- `filenameTin`, `provGroupTin`, `provGroupNpi`, `provGroupNameFull`
- `provOtherTin`, `provOtherNpi`, `provOtherNameFull`
- `aareteDerivedEffectiveDt`, `aareteDerivedTerminationDt` (dates)
- `aareteDerivedAmendmentNum` (integer)
- `autoRenewalInd` (boolean), `autoRenewalTerm`

**Array Fields** (1:N relationship - multiple rows per document):
- Provider info: `reimbProvTin`, `reimbProvNpi`, `reimbProvName`
- Dates: `reimbEffectiveDt`, `reimbTerminationDt`
- Classifications: `aareteDerivedClaimTypeCd`, `aareteDerivedProduct`, `aareteDerivedLob`, `aareteDerivedProgram`, `aareteDerivedNetwork`, `aareteDerivedProvType`
- Codes: `provTaxonomyCd`, `provSpecialtyCd`, `placeOfServiceCd`, `billTypeCd`, `cpt4ProcCd`, `revenueCd`, `diagCd`, `ndcCd`
- Rates: `reimbPctRate`, `reimbFeeRate`, `reimbConversionFactor`, `grouperPctRate`, `grouperBaseRate`
- Indicators: `carveoutInd`, `lesserOfInd`, `greaterOfInd`, `defaultInd`

**Response** (`201 Created`):
```json
{
  "id": "019580df-ef65-7676-8de9-94435a93337a",
  "documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
  "version": 1,
  "singleFields": { ... },
  "arrayFields": [ ... ],
  "createdAt": "2025-10-16T14:27:15Z",
  "createdBy": "user@example.com"
}
```

### `GET /field-extractions`
Retrieves the most recent field extraction for a document.

**Security**: Requires JWT authentication

**Query Parameters**:
- `documentId` (required): Document UUID

**Response**: `FieldExtractionResponse` (same as POST response)

### `GET /field-extractions/history`
Retrieves all versions of field extractions for a document, ordered by most recent first.

**Security**: Requires JWT authentication

**Query Parameters**:
- `documentId` (required): Document UUID

**Response**:
```json
{
  "versions": [
    {
      "id": "019580df-ef65-7676-8de9-94435a93337a",
      "documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
      "version": 2,
      "createdAt": "2025-10-17T10:00:00Z",
      "createdBy": "user@example.com"
    },
    {
      "id": "019580df-ef65-7676-8de9-94435a93337b",
      "documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
      "version": 1,
      "createdAt": "2025-10-16T14:27:15Z",
      "createdBy": "user@example.com"
    }
  ]
}
```

### `GET /field-extractions/version`
Retrieves a specific version of a field extraction for a document by version number.

**Security**: Requires JWT authentication

**Query Parameters**:
- `documentId` (required): Document UUID
- `version` (required): Version number (integer, minimum 1)

**Response** (`200 OK`):
```json
{
  "id": "019580df-ef65-7676-8de9-94435a93337a",
  "documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
  "version": 1,
  "singleFields": {
    "fileName": "contract_2024.pdf",
    "contractTitle": "Service Agreement",
    "clientName": "ACME Corp"
  },
  "arrayFields": [],
  "createdAt": "2025-10-16T14:27:15Z",
  "createdBy": "user@example.com"
}
```

**Error Responses**:
- `400`: Missing required query parameters
- `404`: Version not found for the specified document

---

## Query Management (QueryService)

### `GET /query`
Lists all available queries in the system.

**Security**: Requires JWT authentication

**Response** (`ListQueries`):
```json
{
  "queries": [
    {
      "id": "019580df-ef65-7676-8de9-94435a93337a",
      "type": "JSON_EXTRACTOR",
      "active_version": 1,
      "latest_version": 2,
      "config": "{...}",
      "required_queries": ["019580df-ef65-7676-8de9-94435a93337b"]
    }
  ]
}
```

**Query Types**: `JSON_EXTRACTOR`, `CONTEXT_FULL`

### `POST /query`
Creates a new query definition.

**Security**: Requires JWT authentication

**Request Body** (`QueryCreate`):
```json
{
  "type": "JSON_EXTRACTOR",
  "config": "{\"key\": \"value\"}",
  "required_queries": ["019580df-ef65-7676-8de9-94435a93337b"]
}
```

**Response** (`201 Created`):
```json
{
  "id": "019580df-ef65-7676-8de9-94435a93337a"
}
```

### `GET /query/{id}`
Retrieves query details including configuration.

**Security**: Requires JWT authentication

**Response**: `Query` object

### `PATCH /query/{id}`
Updates query definition.

**Security**: Requires JWT authentication

**Request Body** (`QueryUpdate`):
```json
{
  "config": "{\"updated\": true}",
  "active_version": 2,
  "required_queries": []
}
```

### `POST /query/{id}/test`
Tests query execution against a document.

**Security**: Requires JWT authentication

**Request Body** (`QueryTestRequest`):
```json
{
  "document_id": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
  "query_version": 1
}
```

**Response** (`QueryTestResponse`):
```json
{
  "value": "extracted result"
}
```

---

## Collector Configuration (CollectorService)

### `GET /client/{id}/collector`
Retrieves collector configuration for a client.

**Security**: Requires JWT authentication

**Response** (`Collector`):
```json
{
  "client_id": "AAA",
  "active_version": 1,
  "latest_version": 2,
  "minimum_cleaner_version": 1,
  "minimum_text_version": 1,
  "fields": [
    {
      "name": "contract_date",
      "query_id": "019580df-ef65-7676-8de9-94435a93337a"
    }
  ]
}
```

### `PATCH /client/{id}/collector`
Updates collector configuration.

**Security**: Requires JWT authentication

**Request Body** (`CollectorSet`):
```json
{
  "minimum_cleaner_version": 2,
  "minimum_text_version": 2,
  "active_version": 1,
  "fields": [
    {
      "name": "contract_date",
      "query_id": "019580df-ef65-7676-8de9-94435a93337a"
    }
  ]
}
```

**Response**: `204` Collector set successfully

---

## Export Operations (ExportService)

### `POST /client/{id}/export`
Triggers data export for a client.

**Security**: Requires JWT authentication

**Request Body** (`ExportTrigger`):
```json
{
  "ingestion_filters": {
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z"
  },
  "field_filters": [
    {
      "field_name": "contract_type",
      "condition": "include",
      "values": ["SERVICE", "PRODUCT"]
    }
  ]
}
```

**Filter Conditions**: `less_than`, `greater_than`, `closed_interval`, `open_interval`, `left_closed_interval`, `right_closed_interval`, `include`, `exclude`

**Response** (`201 Created`):
```json
{
  "id": "019580de-4d51-713c-98ee-464e83811f13"
}
```

### `GET /export/{id}`
Checks export status and retrieves download URL.

**Security**: Requires JWT authentication

**Response** (`ExportDetails`):
```json
{
  "client_id": "AAA",
  "status": "completed",
  "output_location": "s3://bucket/AAA/export/20250213/uuid.csv"
}
```

**Export Status Values**: `completed`, `in_progress`, `failed`

---

## User Administration (AdminService)

### `POST /admin/users`
Creates a new user in both AWS Cognito and Permit.io systems with optional role assignments.

**Security**: Requires JWT authentication

**Creation Flow**:
1. User is created in AWS Cognito (primary authentication system)
2. If Cognito creation fails, operation fails with HTTP 502
3. User is created in Permit.io (authorization/role system)
4. If Permit.io creation fails, user still exists in Cognito but `permit_synced=false`
5. Roles are assigned in Permit.io (best-effort, continues on failures)

**Request Body** (`AdminUserCreate`):
```json
{
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "roles": ["user_admin", "auditor"]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User email address (max 320 chars) |
| first_name | string | Yes | User's given name (max 100 chars) |
| last_name | string | Yes | User's family name (max 100 chars) |
| roles | array | Yes | List of role keys to assign (1-50 roles) |

**Response** (`201 Created` or `200 OK` if user exists):
```json
{
  "cognito_subject_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "FORCE_CHANGE_PASSWORD",
  "enabled": true,
  "permit_synced": true,
  "roles_assigned": ["user_admin", "auditor"],
  "created_at": "2025-10-16T14:23:45Z"
}
```

**Error Responses**:
- `400`: Invalid request data
- `401`: Authentication required
- `403`: Insufficient permissions
- `409`: User already exists with different attributes
- `429`: Rate limit exceeded
- `502`: External service (Cognito) error

### `GET /admin/users`
Lists users from AWS Cognito with pagination, filtering, and sorting support.

**Security**: Requires JWT authentication

**Query Parameters**:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| page | integer | 1 | Page number (1-10000) |
| page_size | integer | 50 | Results per page (1-100) |
| search | string | - | Search term for email/name filtering |
| status | string | all | Filter by status: `enabled`, `disabled`, `all` |
| sort_by | string | email | Sort field: `email`, `created_at`, `last_name` |
| sort_order | string | asc | Sort direction: `asc`, `desc` |

**Response** (`AdminUserList`):
```json
{
  "users": [
    {
      "cognito_subject_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "status": "CONFIRMED",
      "enabled": true,
      "roles": ["admin", "viewer"],
      "created_at": "2025-10-15T09:15:30Z",
      "updated_at": "2025-10-16T14:20:10Z"
    }
  ],
  "total": 147,
  "page": 1,
  "page_size": 50,
  "has_more": true
}
```

### `GET /admin/users/{email}`
Retrieves user details from both AWS Cognito and Permit.io by email address.

**Security**: Requires JWT authentication

**Path Parameters**:
- `email`: URL-encoded user email address (max 320 chars)

**Response** (`AdminUserDetails`): Same structure as user list item

### `HEAD /admin/users/{email}`
Checks if a user exists in Cognito and/or Permit.io without returning full details.

**Security**: Requires JWT authentication

**Response Headers**:
- `X-User-Exists-Cognito`: boolean
- `X-User-Exists-PermitIO`: boolean

**Response**:
- `200`: User exists (at least in one system)
- `404`: User does not exist in either system

### `PATCH /admin/users/{email}`
Updates user attributes (first_name, last_name) in Cognito and manages role assignments in Permit.io.

**Security**: Requires JWT authentication

**Role Management (REPLACE Strategy)**:
- Providing a `roles` array REPLACES all existing roles (not additive)
- To add a role: include ALL current roles PLUS the new role
- To remove a role: include only the roles you want to keep
- To remove all roles: send an empty array `[]`
- Omitting the roles field leaves role assignments unchanged

**Request Body** (`AdminUserUpdate`):
```json
{
  "first_name": "Jonathan",
  "last_name": "Doe-Smith",
  "roles": ["user_admin", "auditor"]
}
```

**Response** (`200 OK`): Updated `AdminUserDetails`

### `DELETE /admin/users/{email}`
Permanently deletes a user from both AWS Cognito and Permit.io. This operation is irreversible.

**Security**: Requires JWT authentication

**Query Parameters**:
- `confirm` (required): Must be `true` to confirm deletion

**Response** (`200 OK` or `207 Multi-Status`):
```json
{
  "success": true,
  "email": "john.doe@example.com",
  "cognito_subject_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deleted_from": {
    "cognito": true,
    "permit": true
  },
  "timestamp": "2025-10-16T14:27:15Z"
}
```

### `POST /admin/users/{email}/disable`
Disables a user in AWS Cognito, preventing authentication. User data and roles are preserved. Idempotent.

**Security**: Requires JWT authentication

**Response** (`AdminUserActionResponse`):
```json
{
  "success": true,
  "email": "john.doe@example.com",
  "action": "disable",
  "cognito_subject_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-10-16T14:25:33Z"
}
```

### `POST /admin/users/{email}/enable`
Re-enables a previously disabled user in AWS Cognito. Restores authentication capability. Idempotent.

**Security**: Requires JWT authentication

**Response**: Same as disable endpoint with `"action": "enable"`

---

## Request/Response Schemas

### Standard Response Headers
All API responses include:
- `RateLimit`: Current rate limit status (format: `100;window=60`)
- `Content-Type`: `application/json` (except file downloads and HTML pages)

### Error Response Format
```json
{
  "message": "Error description (max 256 chars)"
}
```

### Common HTTP Status Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 201 | Created |
| 202 | Accepted (async processing) |
| 204 | No Content (success with no body) |
| 207 | Multi-Status (partial success) |
| 302 | Redirect |
| 400 | Bad Request (validation errors) |
| 401 | Unauthorized (authentication required) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not Found |
| 409 | Conflict (resource exists or state conflict) |
| 429 | Too Many Requests (rate limited) |
| 500 | Internal Server Error |
| 502 | Bad Gateway (external service error) |

---

## API Versioning

### Current Strategy
- **URL-based versioning**: `/v1` prefix
- **Backward Compatibility**: Maintained within major versions
- **OpenAPI Version**: 0.0.1 (development phase)

### Future Considerations
- Semantic versioning for production releases
- Deprecation notices for breaking changes
- Version sunset policies

---

## Authorization Reference (Permit.io Integration)

The API uses Permit.io for fine-grained authorization. This section documents what data is sent to Permit.io for each endpoint, enabling system administrators to configure the correct resources, actions, and roles in Permit.io.

### Authorization Flow

1. **Authentication**: User authenticates via AWS Cognito, receiving a JWT token
2. **User Identification**: The `sub` (subject) claim from the JWT is extracted as the user identifier
3. **Resource Mapping**: The first path segment of the URL becomes the resource (e.g., `/client/{id}/document` → `client`)
4. **Action Mapping**: The HTTP method is converted to lowercase to become the action (e.g., `GET` → `get`)
5. **Permission Check**: Permit.io checks if the user has permission to perform the action on the resource

### Permit.io Data Mapping Logic

**Resource Extraction** (from `internal/cognitoauth/mapping.go`):
- The resource is derived from the **first segment** of the URL path
- Leading slashes are removed
- Example: `/client/{id}/document/batch/{batch_id}` → resource: `client`

**Action Extraction**:
- HTTP method is converted to lowercase
- `GET` → `get`, `POST` → `post`, `PATCH` → `patch`, `DELETE` → `delete`, `HEAD` → `head`

### Endpoints Exempt from Authorization

The following endpoints skip authentication and Permit.io authorization entirely:

| Endpoint | Purpose |
|----------|---------|
| `GET /home` | Public home/menu page |
| `GET /logout` | Session termination |
| `GET /health` | Health check endpoint |
| `GET /swagger/*` | Swagger UI documentation |
| `GET /metrics` | Prometheus metrics |

### Special Authentication Endpoints

These endpoints handle authentication flows and bypass normal authorization:

| Endpoint | Purpose |
|----------|---------|
| `GET /login` | Initiates OAuth2/PKCE login flow with Cognito |
| `GET /login-callback` | Handles OAuth2 callback from Cognito |

### Authorization Reference Table

The following table shows what data is passed to Permit.io for each protected endpoint:

| HTTP Method | Endpoint | Resource | Action | Notes |
|-------------|----------|----------|--------|-------|
| **Client Management** |
| `POST` | `/client` | `client` | `post` | Create new client |
| `GET` | `/clients` | `clients` | `get` | List all clients |
| `GET` | `/client/{id}` | `client` | `get` | Get client details |
| `PATCH` | `/client/{id}` | `client` | `patch` | Update client |
| `GET` | `/client/{id}/status` | `client` | `get` | Get client sync status |
| **Document Operations** |
| `POST` | `/client/{id}/document` | `client` | `post` | Upload document |
| `GET` | `/client/{id}/document` | `client` | `get` | List client documents |
| `GET` | `/document/{id}` | `document` | `get` | Get document details |
| **Batch Document Operations** |
| `POST` | `/client/{id}/document/batch` | `client` | `post` | Upload batch (ZIP) |
| `GET` | `/client/{id}/document/batch` | `client` | `get` | List batch uploads |
| `GET` | `/client/{id}/document/batch/{batch_id}` | `client` | `get` | Get batch status |
| `DELETE` | `/client/{id}/document/batch/{batch_id}` | `client` | `delete` | Cancel batch upload |
| **Folder Operations** |
| `GET` | `/client/{id}/folders` | `client` | `get` | List client folders |
| `POST` | `/folders` | `folders` | `post` | Create folder |
| `PATCH` | `/folders/{folderId}` | `folders` | `patch` | Rename folder |
| `GET` | `/folders/{folderId}/documents` | `folders` | `get` | List folder documents |
| `GET` | `/folders/{folderId}/metrics` | `folders` | `get` | Get folder metrics |
| **Label Operations** |
| `POST` | `/documents/{documentId}/labels` | `documents` | `post` | Apply label to document |
| `GET` | `/documents/{documentId}/labels` | `documents` | `get` | Get document labels |
| `GET` | `/labels/{labelName}/documents` | `labels` | `get` | Get documents by label |
| **Field Extraction Operations** |
| `POST` | `/field-extractions` | `field-extractions` | `post` | Create field extraction |
| `GET` | `/field-extractions` | `field-extractions` | `get` | Get latest extraction |
| `GET` | `/field-extractions/version` | `field-extractions` | `get` | Get specific version |
| `GET` | `/field-extractions/history` | `field-extractions` | `get` | Get extraction history |
| **Query Management** |
| `GET` | `/query` | `query` | `get` | List queries |
| `POST` | `/query` | `query` | `post` | Create query |
| `GET` | `/query/{id}` | `query` | `get` | Get query details |
| `PATCH` | `/query/{id}` | `query` | `patch` | Update query |
| `POST` | `/query/{id}/test` | `query` | `post` | Test query execution |
| **Collector Configuration** |
| `GET` | `/client/{id}/collector` | `client` | `get` | Get collector config |
| `PATCH` | `/client/{id}/collector` | `client` | `patch` | Update collector config |
| **Export Operations** |
| `POST` | `/client/{id}/export` | `client` | `post` | Trigger export |
| `GET` | `/export/{id}` | `export` | `get` | Get export status |
| **User Administration** |
| `POST` | `/admin/users` | `admin` | `post` | Create user |
| `GET` | `/admin/users` | `admin` | `get` | List users |
| `GET` | `/admin/users/{email}` | `admin` | `get` | Get user details |
| `HEAD` | `/admin/users/{email}` | `admin` | `head` | Check user existence |
| `PATCH` | `/admin/users/{email}` | `admin` | `patch` | Update user |
| `DELETE` | `/admin/users/{email}` | `admin` | `delete` | Delete user |
| `POST` | `/admin/users/{email}/disable` | `admin` | `post` | Disable user |
| `POST` | `/admin/users/{email}/enable` | `admin` | `post` | Enable user |

### Permit.io Configuration Requirements

To configure Permit.io to work with this API, administrators must create:

#### Resources

| Resource Key | Description |
|--------------|-------------|
| `client` | Client management and client-scoped operations |
| `clients` | Client listing (plural form) |
| `document` | Individual document operations |
| `documents` | Document collection and label operations |
| `folders` | Folder management |
| `labels` | Label-based document queries |
| `field-extractions` | Field extraction operations |
| `query` | Query definition management |
| `export` | Export operations |
| `admin` | User administration |

#### Actions

| Action Key | HTTP Method | Description |
|------------|-------------|-------------|
| `get` | GET | Read/retrieve resources |
| `post` | POST | Create resources |
| `patch` | PATCH | Update resources |
| `delete` | DELETE | Delete resources |
| `head` | HEAD | Check resource existence |

#### Example Role Configuration

Typical role assignments for common personas:

| Role | Resources | Actions | Use Case |
|------|-----------|---------|----------|
| `viewer` | `client`, `clients`, `document`, `documents`, `folders`, `query`, `export` | `get` | Read-only access |
| `editor` | `client`, `document`, `documents`, `folders`, `field-extractions`, `query` | `get`, `post`, `patch` | Content management |
| `admin` | All resources | All actions | Full administrative access |
| `user_admin` | `admin` | All actions | User management only |

### Authorization Error Responses

When authorization fails, the API returns:

**HTTP 401 Unauthorized** - No valid JWT token:
```json
{
  "error": "Authorization required",
  "message": "This endpoint requires authentication. Please obtain a valid JWT token.",
  "login_url": "/login"
}
```

**HTTP 403 Forbidden** - Insufficient permissions:
```json
{
  "error": "Insufficient permissions",
  "message": "Access denied by authorization service",
  "user": "<cognito-subject-id>",
  "resource": "<resource-name>",
  "action": "<action-name>"
}
```

---

## Code Generation

### OpenAPI Integration
The API is generated from the OpenAPI specification using:
```bash
oapi-codegen -generate "types,server" -o api.gen.go serviceAPIs/queryAPI.yaml
```

### Generated Artifacts
- Type-safe Go structs for requests/responses
- Echo framework route handlers
- OpenAPI validation middleware
- Swagger documentation

### Validation
- Automatic request validation against OpenAPI schema
- Response validation in development mode
- Parameter binding with type safety