# Query API Endpoints Summary

This document provides a comprehensive summary of all REST API endpoints available in the Query Orchestration Platform.

## Quick Reference (All Endpoints)

| Path                                   | Methods                  | Service              |
|----------------------------------------|--------------------------|----------------------|
| /login                                 | GET                      | AuthService          |
| /login-callback                        | GET                      | AuthService          |
| /logout                                | GET                      | AuthService          |
| /home                                  | GET                      | AuthService          |
| /identity                              | GET                      | AuthService          |
| /client                                | POST                     | ClientService        |
| /clients                               | GET                      | ClientService        |
| /client/{id}                           | GET, PATCH               | ClientService        |
| /client/{id}/status                    | GET                      | ClientService        |
| /client/{id}/collector                 | GET, PATCH               | CollectorService     |
| /client/{id}/folders                   | GET                      | FolderService        |
| /folders                               | POST                     | FolderService        |
| /folders/{folderId}                    | PATCH                    | FolderService        |
| /folders/{folderId}/documents          | GET                      | FolderService        |
| /folders/{folderId}/metrics            | GET                      | FolderService        |
| /client/{id}/document                  | GET, POST                | DocumentsService     |
| /client/{id}/document/batch            | GET, POST                | DocumentsService     |
| /client/{id}/document/batch/{batch_id} | GET, DELETE              | DocumentsService     |
| /document/{id}                         | GET                      | DocumentsService     |
| /documents/{documentId}/labels         | GET, POST                | LabelService         |
| /labels/{labelName}/documents          | GET                      | LabelService         |
| /field-extractions                     | GET, POST                | FieldExtractionService |
| /field-extractions/version             | GET                      | FieldExtractionService |
| /field-extractions/history             | GET                      | FieldExtractionService |
| /client/{id}/export                    | POST                     | ExportService        |
| /export/{id}                           | GET                      | ExportService        |
| /admin/users                           | GET, POST                | AdminService         |
| /admin/users/{email}                   | GET, HEAD, PATCH, DELETE | AdminService         |
| /admin/users/{email}/disable           | POST                     | AdminService         |
| /admin/users/{email}/enable            | POST                     | AdminService         |
| /eula                                  | GET                      | EulaService          |
| /eula/status                           | GET                      | EulaService          |
| /eula/agree                            | POST                     | EulaService          |
| /admin/eula                            | GET, POST                | EulaService          |
| /admin/eula/{version_id}               | GET, PATCH               | EulaService          |
| /admin/eula/{version_id}/activate      | POST                     | EulaService          |
| /admin/eula/agreements                 | GET                      | EulaService          |
| /admin/eula/compliance                 | GET                      | EulaService          |

---

## Authentication Service

### OAuth2 Authentication Flow
- **GET /login** - Initiate login flow by redirecting to Cognito IDP
  - Redirects to AWS Cognito login page
  - No authentication required

- **GET /login-callback** - Handle OAuth2 callback and exchange code for tokens
  - Query Parameters:
    - `code` (required) - Authorization code from Cognito
    - `state` (required) - CSRF protection parameter
  - Sets JWT cookie and redirects to dashboard

- **GET /logout** - Logout user and invalidate session
  - Requires authentication
  - Redirects to Cognito logout page or application home

- **GET /home** - Get the home page menu for authenticated users
  - Requires authentication
  - Returns HTML content for authenticated user menu

- **GET /identity** - Get current user identity and roles
  - Requires authentication
  - Returns user's assigned roles from Permit.io with permissions
  - Returns: `{user_id, email, roles[]}`

## Client Service

### Client Management
- **POST /client** - Create a new client with provided details
  - Request Body: `{id, name}`
  - Returns: `{id}` (201 Created)

- **GET /clients** - List all clients in the system
  - Returns: `{clients[]}` where each client contains `{id, name}`

- **GET /client/{id}** - Get a specific client by its ID
  - Returns: `{id, name, can_sync}` (200 OK)

- **PATCH /client/{id}** - Update an existing client with new details
  - Request Body: `{name?, can_sync?}` (optional fields)
  - Returns: 200 OK on success

- **GET /client/{id}/status** - Retrieve the sync status for a client
  - Returns: `{status}` where status is one of: `IN_SYNC`, `NOT_SYNCED`, `NOT_SYNCING`

## Collector Service

### Collector Configuration Management
- **GET /client/{id}/collector** - Get a collector configuration by client ID
  - Returns: `{client_id, active_version, latest_version, minimum_cleaner_version, minimum_text_version, fields[]}`

- **PATCH /client/{id}/collector** - Set or update collector configuration for a client
  - Request Body: `{minimum_cleaner_version?, minimum_text_version?, active_version?, fields[]?}`
  - Returns: 204 No Content on success

## Folder Service

### Folder Management
- **GET /client/{id}/folders** - List all folders for a client
  - Query Parameters:
    - `metrics` (optional, default: false) - When true, includes processing metrics for each folder
  - Returns: `{folders[]}` where each folder contains `{id, path, parent_id, metrics?}`
  - Root-level folders have null parentId

- **POST /folders** - Create a new folder
  - Request Body: `{client_id, path, parent_id?}`
  - Returns: `{id, client_id, path, parent_id}` (201 Created)

- **PATCH /folders/{folderId}** - Rename a folder
  - Request Body: `{path}`
  - Returns: `{id, client_id, path, parent_id}` (200 OK)

- **GET /folders/{folderId}/documents** - Get documents in a folder
  - Query Parameters:
    - `textRecord` (optional, default: false) - When true, includes full text extraction record
  - Returns: `{documents[]}` with document details including filename and labels

- **GET /folders/{folderId}/metrics** - Get folder processing metrics
  - Returns: `{total_documents, processed_documents, label_counts{}}`

## Documents Service

### Document Management
- **GET /client/{id}/document** - List all documents for a specific client
  - Returns: Array of `{id, hash}` document summaries

- **POST /client/{id}/document** - Upload a single PDF file for a client
  - Content-Type: `multipart/form-data`
  - Form Data:
    - `file` (required) - PDF file to upload (binary)
    - `filename` (optional) - Custom filename (max 4096 chars)
  - Returns: 200 OK on successful upload

- **GET /document/{id}** - Get document details by its ID
  - Query Parameters:
    - `textRecord` (optional, default: false) - When true, includes full text extraction record
  - Returns: `{id, client_id, hash, folder_id, filename, labels[], fields{}, text_record?}`

### Batch Document Processing
- **POST /client/{id}/document/batch** - Upload multiple PDFs as ZIP archive for batch processing
  - Content-Type: `multipart/form-data`
  - Form Data:
    - `archive` (required) - ZIP file containing PDF documents (max 1GB)
  - Returns: `{batch_id, status, status_url}` (202 Accepted)

- **GET /client/{id}/document/batch** - List batch uploads for a client with pagination
  - Query Parameters:
    - `limit` (optional, default: 20, max: 100) - Number of items to return
    - `offset` (optional, default: 0) - Number of items to skip
  - Returns: `{batches[], total_count}`

- **GET /client/{id}/document/batch/{batch_id}** - Get detailed status of a specific batch upload
  - Returns: `{batch_id, client_id, original_filename, status, total_documents, processed_documents, failed_documents, invalid_type_documents, progress_percent, created_at, completed_at?, failed_filenames[]}`

- **DELETE /client/{id}/document/batch/{batch_id}** - Cancel a batch upload currently processing
  - Returns: 204 No Content on successful cancellation

## Label Service

### Document Label Management
- **POST /documents/{documentId}/labels** - Apply a label to a document
  - Request Body: `{label_name}`
  - Labels track document processing state/workflow
  - Returns: `{id, document_id, label_name, applied_at}` (201 Created)

- **GET /documents/{documentId}/labels** - Get all labels for a document
  - Returns: `{labels[]}` ordered by most recent first
  - Each label contains: `{id, document_id, label_name, applied_at}`

- **GET /labels/{labelName}/documents** - Get all documents with a specific label
  - Query Parameters:
    - `clientId` (required) - Filter by client ID
  - Returns: `{documents[]}` with document summaries

## Field Extraction Service

### Document Field Extraction Management
- **POST /field-extractions** - Create a new field extraction
  - Request Body: `{document_id, single_fields{}, array_fields{}}`
  - Creates versioned field extraction record
  - Returns: `{id, document_id, version, single_fields{}, array_fields{}, created_at}` (201 Created)

- **GET /field-extractions** - Get current (most recent) field extraction for a document
  - Query Parameters:
    - `documentId` (required) - The document ID
  - Returns: `{id, document_id, version, single_fields{}, array_fields{}, created_at}`

- **GET /field-extractions/version** - Get field extraction by specific version
  - Query Parameters:
    - `documentId` (required) - The document ID
    - `version` (required) - The version number to retrieve
  - Returns: `{id, document_id, version, single_fields{}, array_fields{}, created_at}`

- **GET /field-extractions/history** - Get field extraction version history
  - Query Parameters:
    - `documentId` (required) - The document ID
  - Returns: `{versions[]}` ordered by most recent first
  - Each version contains: `{version, created_at}`

## Export Service

### Export Management
- **POST /client/{id}/export** - Trigger an export process for a client
  - Request Body: `{ingestion_filters?, field_filters[]?}`
  - Ingestion Filters: `{start_date?, end_date?}`
  - Field Filters: `{field_name, condition, values[]}`
  - Conditions: `less_than`, `greater_than`, `closed_interval`, `open_interval`, `left_closed_interval`, `right_closed_interval`, `include`, `exclude`
  - Returns: `{id}` (201 Created)

- **GET /export/{id}** - Check the current state of an export
  - Returns: `{client_id, status, output_location?}`
  - Status values: `completed`, `in_progress`, `failed`

## Admin Service

### User Management

#### User Creation and Listing
- **POST /admin/users** - Create a new user
  - Request Body: `{email, first_name, last_name, roles[]}`
  - Creates user in both AWS Cognito and Permit.io
  - Roles: Must exist in Permit.io (e.g., `super_admin`, `user_admin`, `auditor`, `client_user`)
  - Returns: `{cognito_subject_id, email, first_name, last_name, status, enabled, permit_synced, roles_assigned[], created_at}` (201 Created or 200 OK if already exists)
  - **Idempotent**: Returns 200 OK if user already exists with matching attributes

- **GET /admin/users** - List users with pagination, filtering, and sorting
  - Query Parameters:
    - `page` (optional, default: 1, max: 10000) - Page number
    - `page_size` (optional, default: 50, max: 100) - Results per page
    - `search` (optional) - Search term for email/name filtering
    - `status` (optional, default: `all`) - Filter by status: `enabled`, `disabled`, `all`
    - `sort_by` (optional, default: `email`) - Sort field: `email`, `created_at`, `last_name`
    - `sort_order` (optional, default: `asc`) - Sort direction: `asc`, `desc`
  - Returns: `{users[], total, page, page_size, has_more}`

#### Individual User Operations
- **GET /admin/users/{email}** - Get user by email
  - Returns: `{cognito_subject_id, email, first_name, last_name, status, enabled, roles[], created_at, updated_at}`

- **HEAD /admin/users/{email}** - Check if user exists
  - Returns: 200 OK with headers:
    - `X-User-Exists-Cognito: boolean` - Whether user exists in Cognito
    - `X-User-Exists-PermitIO: boolean` - Whether user exists in Permit.io
  - Returns: 404 Not Found if user doesn't exist in either system

- **PATCH /admin/users/{email}** - Update user attributes and roles
  - Request Body: `{first_name?, last_name?, roles[]?}`
  - **Role Management**: Providing `roles[]` REPLACES all existing roles (not additive)
    - To add a role: Include all current roles PLUS the new role
    - To remove a role: Include only roles you want to keep
    - To remove all roles: Send empty array `[]`
    - Omit `roles` field to leave roles unchanged
  - Returns: `{cognito_subject_id, email, first_name, last_name, status, enabled, roles[], created_at, updated_at}` (200 OK)

- **DELETE /admin/users/{email}** - Delete user permanently
  - Query Parameters:
    - `confirm=true` (required) - Must be set to confirm deletion
  - Deletes from both AWS Cognito and Permit.io
  - **Irreversible operation**
  - Returns: `{success, email, cognito_subject_id, deleted_from{cognito, permit}, timestamp}` (200 OK or 207 Multi-Status for partial deletion)

#### User Account Status Management
- **POST /admin/users/{email}/disable** - Disable user
  - Disables user in AWS Cognito, preventing authentication
  - User data and roles are preserved
  - **Idempotent**: Safe to call multiple times
  - Returns: `{success, email, action, cognito_subject_id, timestamp}` (200 OK)

- **POST /admin/users/{email}/enable** - Enable user
  - Re-enables a previously disabled user in AWS Cognito
  - Restores authentication capability
  - **Idempotent**: Safe to call multiple times
  - Returns: `{success, email, action, cognito_subject_id, timestamp}` (200 OK)

## EULA Service

### Public Endpoints

- **GET /eula** - Get current EULA version (public, no authentication required)
  - Returns: `{id, version, title, content, effective_date}` (200 OK)
  - Returns 404 if no current EULA is configured

- **GET /eula/status** - Check user's agreement status
  - Requires authentication
  - Returns: `{has_agreed, current_version, current_version_id, agreed_at?, agreed_version?}`

- **POST /eula/agree** - Record user agreement to current EULA
  - Requires authentication
  - IP address automatically captured from request
  - **Idempotent**: Returns 200 if already agreed, 201 for new agreement
  - Returns: `{id, eula_version_id, eula_version, agreed_at}`

### Administrative Endpoints

- **GET /admin/eula** - List all EULA versions with pagination
  - Query Parameters: `page`, `page_size`
  - Returns: `{versions[], total, has_more}`

- **POST /admin/eula** - Create a new EULA version
  - Request Body: `{version, title, content, effective_date}`
  - Content should be in Markdown format
  - Returns: Created `EulaVersion` object (201 Created)

- **GET /admin/eula/{version_id}** - Get specific EULA version
  - Returns: Full `EulaVersion` object

- **PATCH /admin/eula/{version_id}** - Update EULA metadata
  - Request Body: `{title?, effective_date?}`
  - Note: Content cannot be modified (audit integrity)
  - Returns: Updated `EulaVersion` object

- **POST /admin/eula/{version_id}/activate** - Activate EULA version
  - Sets this version as current (atomically clears previous)
  - Returns: Activated `EulaVersion` with `is_current=true`

- **GET /admin/eula/agreements** - List EULA agreements
  - Query Parameters: `page`, `page_size`, `version_id?`, `user_id?`
  - Returns: `{agreements[], total, has_more}`

- **GET /admin/eula/compliance** - Get compliance report
  - Query Parameters: `page`, `page_size`, `version_id?`, `agreed?`
  - Defaults to current EULA version
  - Returns: `{version_id, version, total_users, agreed_count, not_agreed_count, compliance_percentage, users[], page, page_size, has_more}`

## Common Response Codes

All endpoints may return the following standard HTTP response codes:

- **200 OK** - Request succeeded
- **201 Created** - Resource created successfully
- **202 Accepted** - Request accepted for async processing
- **204 No Content** - Request succeeded with no response body
- **207 Multi-Status** - Partial success (e.g., deletion from only one system)
- **302 Found** - Redirect (for auth flows)
- **400 Bad Request** - Invalid request body or parameters
- **401 Unauthorized** - Authentication required or failed
- **403 Forbidden** - Insufficient permissions
- **404 Not Found** - Resource does not exist
- **409 Conflict** - Resource already exists or state conflict
- **429 Too Many Requests** - Rate limit exceeded (includes `Retry-After` header)
- **500 Internal Server Error** - Server-side error
- **502 Bad Gateway** - External service error (e.g., Cognito, Permit.io)

## Rate Limiting

All endpoints implement dual-layer rate limiting:
- **Global Rate Limit**: 500 requests/second across all IPs (1000 burst)
- **Per-IP Rate Limit**: 5 requests/second per IP (10 burst)

Rate limit headers included in all responses:
- `RateLimit: limit;window=time-window` (e.g., `100;window=60`)
- `Retry-After: seconds` (only on 429 responses)

## Security

- **Authentication**: JWT Bearer tokens via AWS Cognito OAuth2
- **Authorization**: Role-based access control (RBAC) via Permit.io
- **Public endpoints** (no authentication required):
  - `GET /login` - Public login initiation
  - `GET /login-callback` - OAuth2 callback handler
  - `GET /home` - Home/menu page
  - `GET /logout` - Logout redirect flow
  - `GET /health` - Health check
  - `GET /swagger/*` - Swagger UI
  - `GET /metrics` - Prometheus metrics
  - `GET /eula` - Current public EULA version

## API Versioning

- **Base URL**: `https://doczy.com/v1` (production)
- **Local Development**: `http://localhost:8080`
- **API Version**: 0.0.1
- **OpenAPI Specification**: `serviceAPIs/queryAPI.yaml`

## Documentation

- **Swagger UI**: Available at `/swagger/index.html` when running locally
- **OpenAPI Spec**: Auto-generated from `serviceAPIs/queryAPI.yaml`