# Query API Endpoints Summary

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

## 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

## Client Service

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

- **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

## 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
  - Returns: `{id, client_id, hash, fields{}}`

### 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

## Query Service

### Query Definition and Execution
- **GET /query** - List queries based on filter criteria
  - Returns: `{queries[]}` where each query contains `{id, type, active_version, latest_version, config?, required_queries[]?}`

- **POST /query** - Create a new query with provided details
  - Request Body: `{type, config?, required_queries[]?}`
  - Supported Types: `JSON_EXTRACTOR`, `CONTEXT_FULL`
  - Returns: `{id}` (201 Created)

- **GET /query/{id}** - Get a specific query by its ID
  - Returns: `{id, type, active_version, latest_version, config?, required_queries[]?}`

- **PATCH /query/{id}** - Update an existing query with new details
  - Request Body: `{config?, active_version?, required_queries[]?}`
  - Returns: 200 OK on success

- **POST /query/{id}/test** - Execute a test run of a query with parameters
  - Request Body: `{document_id, query_version}`
  - Returns: `{value}` - Result of the query test

## 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)

## 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
- **All endpoints require authentication** except:
  - `GET /login` - Public login initiation
  - `GET /login-callback` - OAuth2 callback handler

## 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`