2025-09-03 20:43:27 +00:00
# Query API Endpoints Summary
2025-11-26 19:23:42 +00:00
This document provides a comprehensive summary of all REST API endpoints available in the Query Orchestration Platform.
2026-01-07 19:35:53 +00:00
## 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 |
2026-01-22 18:17:27 +00:00
| /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 |
2026-01-07 19:35:53 +00:00
---
2025-11-26 19:23:42 +00:00
## 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
2026-01-07 19:35:53 +00:00
- **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[]}`
2025-09-03 20:43:27 +00:00
## Client Service
2025-11-26 19:23:42 +00:00
### Client Management
2025-09-03 20:43:27 +00:00
- **POST /client** - Create a new client with provided details
2025-11-26 19:23:42 +00:00
- Request Body: `{id, name}`
- Returns: `{id}` (201 Created)
2026-01-07 19:35:53 +00:00
- **GET /clients** - List all clients in the system
- Returns: `{clients[]}` where each client contains `{id, name}`
2025-09-03 20:43:27 +00:00
- **GET /client/{id}** - Get a specific client by its ID
2025-11-26 19:23:42 +00:00
- Returns: `{id, name, can_sync}` (200 OK)
2025-09-03 20:43:27 +00:00
- **PATCH /client/{id}** - Update an existing client with new details
2025-11-26 19:23:42 +00:00
- Request Body: `{name?, can_sync?}` (optional fields)
- Returns: 200 OK on success
2025-09-03 20:43:27 +00:00
- **GET /client/{id}/status** - Retrieve the sync status for a client
2025-11-26 19:23:42 +00:00
- Returns: `{status}` where status is one of: `IN_SYNC` , `NOT_SYNCED` , `NOT_SYNCING`
2025-09-03 20:43:27 +00:00
## Collector Service
2025-11-26 19:23:42 +00:00
### Collector Configuration Management
2025-09-03 20:43:27 +00:00
- **GET /client/{id}/collector** - Get a collector configuration by client ID
2025-11-26 19:23:42 +00:00
- Returns: `{client_id, active_version, latest_version, minimum_cleaner_version, minimum_text_version, fields[]}`
2025-09-03 20:43:27 +00:00
- **PATCH /client/{id}/collector** - Set or update collector configuration for a client
2025-11-26 19:23:42 +00:00
- Request Body: `{minimum_cleaner_version?, minimum_text_version?, active_version?, fields[]?}`
- Returns: 204 No Content on success
2025-09-03 20:43:27 +00:00
2026-01-07 19:35:53 +00:00
## 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{}}`
2025-09-03 20:43:27 +00:00
## Documents Service
2025-11-26 19:23:42 +00:00
### Document Management
2025-09-03 20:43:27 +00:00
- **GET /client/{id}/document** - List all documents for a specific client
2025-11-26 19:23:42 +00:00
- Returns: Array of `{id, hash}` document summaries
2025-09-03 20:43:27 +00:00
- **POST /client/{id}/document** - Upload a single PDF file for a client
2025-11-26 19:23:42 +00:00
- 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
2026-01-07 19:35:53 +00:00
- 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?}`
2025-11-26 19:23:42 +00:00
### Batch Document Processing
2025-09-03 20:43:27 +00:00
- **POST /client/{id}/document/batch** - Upload multiple PDFs as ZIP archive for batch processing
2025-11-26 19:23:42 +00:00
- Content-Type: `multipart/form-data`
- Form Data:
- `archive` (required) - ZIP file containing PDF documents (max 1GB)
- Returns: `{batch_id, status, status_url}` (202 Accepted)
2025-09-03 20:43:27 +00:00
- **GET /client/{id}/document/batch** - List batch uploads for a client with pagination
2025-11-26 19:23:42 +00:00
- 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}`
2025-09-03 20:43:27 +00:00
- **GET /client/{id}/document/batch/{batch_id}** - Get detailed status of a specific batch upload
2025-11-26 19:23:42 +00:00
- 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[]}`
2025-09-03 20:43:27 +00:00
- **DELETE /client/{id}/document/batch/{batch_id}** - Cancel a batch upload currently processing
2025-11-26 19:23:42 +00:00
- Returns: 204 No Content on successful cancellation
2025-09-03 20:43:27 +00:00
2026-01-07 19:35:53 +00:00
## 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}`
2025-09-03 20:43:27 +00:00
## Export Service
2025-11-26 19:23:42 +00:00
### Export Management
2025-09-03 20:43:27 +00:00
- **POST /client/{id}/export** - Trigger an export process for a client
2025-11-26 19:23:42 +00:00
- 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)
2025-09-03 20:43:27 +00:00
- **GET /export/{id}** - Check the current state of an export
2025-11-26 19:23:42 +00:00
- Returns: `{client_id, status, output_location?}`
- Status values: `completed` , `in_progress` , `failed`
2025-09-03 20:43:27 +00:00
2025-11-26 19:23:42 +00:00
## 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)
2026-01-22 18:17:27 +00:00
## 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}`
2025-11-26 19:23:42 +00:00
## 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
2026-02-19 20:22:59 +00:00
- **Public endpoints** (no authentication required):
2025-11-26 19:23:42 +00:00
- `GET /login` - Public login initiation
- `GET /login-callback` - OAuth2 callback handler
2026-02-19 20:22:59 +00:00
- `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
2025-11-26 19:23:42 +00:00
## 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`
