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 |
2026-03-04 18:30:13 +00:00
| /client/{id} | GET, PATCH, DELETE | ClientService |
2026-01-07 19:35:53 +00:00
| /client/{id}/status | GET | ClientService |
| /client/{id}/collector | GET, PATCH | CollectorService |
| /client/{id}/folders | GET | FolderService |
| /folders | POST | FolderService |
2026-03-04 18:30:13 +00:00
| /folders/{folderId} | PATCH, DELETE | FolderService |
2026-01-07 19:35:53 +00:00
| /folders/{folderId}/documents | GET | FolderService |
| /folders/{folderId}/metrics | GET | FolderService |
| /client/{id}/document | GET, POST | DocumentsService |
| /client/{id}/document/batch | GET, POST | DocumentsService |
2026-03-04 18:30:13 +00:00
| /client/{id}/document/batch/{batch_id} | GET | DocumentsService |
| /document/{id} | GET, DELETE | DocumentsService |
2026-03-17 17:06:57 +00:00
| /document/{id}/download | GET | DocumentsService |
2026-01-07 19:35:53 +00:00
| /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-03-04 23:00:50 +00:00
| /ui-settings | GET, POST | UISettingsService |
| /ui-settings/{id} | GET, PATCH, DELETE | UISettingsService |
2026-04-16 23:11:26 +00:00
| /super-admin/custom-schemas | POST, GET | SuperAdminSchemaService |
| /super-admin/custom-schemas/{schemaId} | GET, DELETE | SuperAdminSchemaService |
| /super-admin/custom-schemas/{schemaId}/versions | POST | SuperAdminSchemaService |
| /super-admin/documents/{id}/schema | PATCH | SuperAdminSchemaService |
| /super-admin/documents/{id}/reset-metadata | POST | SuperAdminSchemaService |
| /custom-metadata | GET, POST | CustomMetadataService |
| /custom-metadata/version | GET | CustomMetadataService |
| /custom-metadata/history | GET | CustomMetadataService |
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
2026-03-04 18:30:13 +00:00
- **DELETE /client/{id}** - Hard-delete a client and all associated data (super_admin only)
- Query Parameters:
- `confirm=true` (required) - Must be set to confirm deletion
- `verbose` (optional, default: false) - When true, returns S3 paths of orphaned source documents
- Deletes all documents, folders, collector configs, batch uploads, and clientCanSync records
- S3 source files are NOT deleted; their paths are logged
- Returns: 204 No Content (or 200 with S3 paths when verbose=true)
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)
2026-03-04 18:30:13 +00:00
- **DELETE /folders/{folderId}** - Hard-delete a folder tree (super_admin only)
- Query Parameters:
- `include_documents` (optional, default: false) - When true, also deletes all documents in the folder tree
- `verbose` (optional, default: false) - When true, returns S3 paths of orphaned source documents
- Root folder (`/` ) cannot be deleted (returns 409 Conflict)
- If folder tree contains documents and include_documents is false, returns 409 Conflict
- S3 source files are NOT deleted; their paths are logged
- Returns: 204 No Content (or 200 with S3 paths when verbose=true)
2026-01-07 19:35:53 +00:00
- **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
2026-03-17 17:06:57 +00:00
- **GET /document/{id}/download** - Download the original document file
- Streams file directly from S3 storage
- Content-Type auto-detected from stored filename extension
- Returns: Raw file bytes with `Content-Disposition: attachment` header
- Supports any file type (PDF, PNG, DOCX, CSV, etc.)
2026-03-04 18:30:13 +00:00
- **DELETE /document/{id}** - Hard-delete a document and all dependent data (super_admin only)
- Query Parameters:
- `verbose` (optional, default: false) - When true, returns S3 paths of orphaned source documents
- Deletes all dependent rows: entries, cleans, text extractions, field extractions, labels, results
- S3 source files are NOT deleted; their paths are logged
- Returns: 204 No Content (or 200 with S3 paths when verbose=true)
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
2026-03-12 18:53: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[], document_outcomes[]}`
- `document_outcomes` provides per-file tracking through the processing pipeline (see [Batch Outcome Tracking Guide ](./batch-outcome-tracking-guide.md ))
2025-11-26 19:23:42 +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
2026-05-12 16:49:12 +00:00
- Team Management: Super Admin can create any user; User Admin and Client Admin can create only non-AArete users with `client_user` /`user_admin` roles; Auditor is read-only
2025-11-26 19:23:42 +00:00
- 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
2026-05-12 16:49:12 +00:00
- `page_size` (optional, default: 50, max: 60) - Results per page
2025-11-26 19:23:42 +00:00
- `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`
2026-05-12 16:49:12 +00:00
- Team Management: User Admin and Client Admin see only non-AArete users without `auditor` /`super_admin` roles; Super Admin and Auditor see all environment-visible users
- `roles` is populated from Permit.io for each returned user
2025-11-26 19:23:42 +00:00
- Returns: `{users[], total, page, page_size, has_more}`
#### Individual User Operations
- **GET /admin/users/{email}** - Get user by email
2026-05-12 16:49:12 +00:00
- Hidden users return 404 for User Admin and Client Admin callers
2025-11-26 19:23:42 +00:00
- Returns: `{cognito_subject_id, email, first_name, last_name, status, enabled, roles[], created_at, updated_at}`
- **HEAD /admin/users/{email}** - Check if user exists
2026-05-12 16:49:12 +00:00
- Hidden users return 404 for User Admin and Client Admin callers
2025-11-26 19:23:42 +00:00
- 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[]?}`
2026-05-12 16:49:12 +00:00
- Team Management: Super Admin can update any environment-visible user; User Admin and Client Admin can update only non-AArete client-level users and assign only `client_user` /`user_admin` ; Auditor is read-only
2025-11-26 19:23:42 +00:00
- **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
2026-05-12 16:49:12 +00:00
- Team Management: Super Admin can delete any environment-visible user; User Admin and Client Admin can delete only non-AArete client-level users; Auditor is read-only
2025-11-26 19:23:42 +00:00
- 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
2026-05-12 16:49:12 +00:00
- Team Management: Super Admin can disable any environment-visible user; User Admin and Client Admin can disable only non-AArete client-level users; Auditor is read-only
2025-11-26 19:23:42 +00:00
- 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
2026-05-12 16:49:12 +00:00
- Team Management: Super Admin can enable any environment-visible user; User Admin and Client Admin can enable only non-AArete client-level users; Auditor is read-only
2025-11-26 19:23:42 +00:00
- 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}`
2026-03-04 23:00:50 +00:00
## UI Settings Service
### UI Settings Management
- **GET /ui-settings** - List UI settings (soft-deleted excluded)
- Query Parameters:
- `namespace` (optional) - Filter by namespace (e.g. demo-dashboard:{userId}, feature-flags:global)
- Returns: `{settings[], totalCount}`
- **POST /ui-settings** - Create a UI setting
- Request Body: `{namespace, key, value}` (value is a JSON object)
- Use namespace to scope data (e.g. demo-dashboard:{userId}, feature-flags:global, saved-filters:{clientId})
- Returns: Created `UISetting` (201 Created)
- **GET /ui-settings/{id}** - Get a UI setting by ID
- Returns: `{id, namespace, key, value, isDeleted, createdAt, updatedAt}` (200 OK) or 404 if not found or soft-deleted
- **PATCH /ui-settings/{id}** - Update a UI setting value
- Request Body: `{value}` (new JSON object)
- Returns: Updated `UISetting` (200 OK) or 404 if not found or soft-deleted
- **DELETE /ui-settings/{id}** - Soft-delete a UI setting
- Sets `isDeleted` to true; record is retained
- Returns: 204 No Content or 404 if not found
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
2026-03-04 23:00:50 +00:00
- `GET /ui-settings` , `POST /ui-settings` , `GET /ui-settings/{id}` , `PATCH /ui-settings/{id}` , `DELETE /ui-settings/{id}` - UI settings (JWT required)
2025-11-26 19:23:42 +00:00
2026-04-16 23:11:26 +00:00
## Custom Metadata Service
### Document Custom Metadata
Routes accessible by `super_admin` , `user_admin` , and `client_user` . `auditor` may call GET routes only. The `POST` route requires the document to have a bound custom schema (`customSchemaId` non-null); writing to a document that has legacy field extractions returns 409.
- **POST /custom-metadata** — Write a new custom metadata version for a document
- Request Body: `{documentId, metadata}` — `createdBy` is derived from JWT, not accepted in body
- `metadata` is validated against the document's bound schema (Draft 2020-12); max payload 1 MB
- Version number auto-assigned (monotonically increasing, serialized via parent-row `FOR UPDATE` lock)
- Returns: `CustomMetadataResponse` (201 Created) including `schemaId` , `schemaName` , `schemaVersion`
- 400 if document has no bound schema, or metadata fails validation
- 409 if document has legacy field extractions
- **GET /custom-metadata** — Get the current (latest) metadata version for a document
- Query Parameters:
- `documentId` (required) — UUID of the target document
- Returns: `CustomMetadataResponse` with the highest-version row, decorated with `schemaId` , `schemaName` , `schemaVersion`
- 404 if document not found or has no metadata rows
- **GET /custom-metadata/version** — Get a specific historical metadata version
- Query Parameters:
- `documentId` (required) — UUID of the target document
- `version` (required, integer >= 1) — The exact version number to retrieve
- Returns: `CustomMetadataResponse` for the requested version
- 404 if that version does not exist; 400 if `version < 1`
- **GET /custom-metadata/history** — List version summaries for a document's metadata
- Query Parameters:
- `documentId` (required) — UUID of the target document
- `limit` (optional, default: 50, max: 200) — Values above 200 are clamped to 200
- `offset` (optional, default: 0, min: 0)
- Returns: `CustomMetadataHistoryResponse` with `(version, createdAt, createdBy)` tuples in descending version order
- 400 if `limit < 1` or `offset < 0` ; 200 with empty list if document exists but has no metadata
---
## Super Admin Schema Service
### Custom Metadata Schema Management
All routes require the `super_admin` Permit.io role unless noted. `auditor` may call GET routes. `user_admin` and `client_user` have no access to the `super-admin` resource.
- **POST /super-admin/custom-schemas** — Create a new client-scoped JSON Schema (version 1)
- Request Body: `{clientId, name, description?, schema}` — `createdBy` is derived from JWT, not accepted in body
- `schema` must be Draft 2020-12, root `type=object` , `additionalProperties` explicitly declared, max 64 KB
- Returns: `CustomSchemaResponse` (201 Created)
- 409 if a schema with the same name already exists for this client
- **GET /super-admin/custom-schemas** — List schemas for a client
- Query Parameters:
- `clientId` (required) — The client whose schemas to list
- `name` (optional) — Exact-match name filter
- `status` (optional, default: `active` ) — One of `active` , `superseded` , `retired` , `any`
- `includeAllVersions` (optional, default: `false` ) — When `true` , returns all versions per lineage
- `limit` (optional, default: 50, max: 200) — Page size
- `offset` (optional, default: 0) — Pagination offset
- Returns: `CustomSchemaListResponse` (schema definitions omitted; use GET by ID to retrieve)
- **GET /super-admin/custom-schemas/{schemaId}** — Get a schema by ID
- Returns: `CustomSchemaResponse` including the full JSON Schema document
- Available to `super_admin` and `auditor`
- **POST /super-admin/custom-schemas/{schemaId}/versions** — Create a new version of an existing schema
- Path `schemaId` must be the currently `active` row for its lineage
- The parent row is marked `superseded` ; the new row becomes `active` in the same transaction
- Request Body: `{description?, schema}` — `clientId` and `name` inherited from parent
- Returns: `CustomSchemaResponse` for the new version (201 Created)
- 409 if parent is not `active` (already `superseded` or `retired` )
- **DELETE /super-admin/custom-schemas/{schemaId}** — Retire a schema
- Sets `status=retired` ; preserves the row for audit history
- Returns: 204 No Content
- 409 if any document still references this schema version (`documentCount > 0` )
### Document Schema Assignment
- **PATCH /super-admin/documents/{id}/schema** — Bind (or clear) a custom schema for a document
- Restricted to `super_admin` role
- Request Body: `{customSchemaId}` — set to a UUID to bind, or `null` to clear
- The target schema must be `active` and belong to the same client as the document
- 409 if document already has custom metadata (Trigger 1 prevents reassignment); 409 if document has legacy field extractions
- Returns: `DocumentSchemaAssignResponse` with `documentId` , `customSchemaId` , `schemaName` , `schemaVersion` (200 OK)
### Document Metadata Reset
- **POST /super-admin/documents/{id}/reset-metadata** — Wipe a document's custom metadata history and clear its schema binding
- Restricted to `super_admin` role (user_admin, client_user, auditor all receive 403)
- No request body required
- Idempotent: returns 200 with `metadataVersionsDeleted: 0` on a document that has no metadata or schema binding
- 404 if the document does not exist
- 409 if the document has legacy field extractions (mutual-exclusivity invariant)
- Returns: `DocumentMetadataResetResponse` with `documentId` , `metadataVersionsDeleted` , `previousSchemaId` , `previousSchemaName` , `previousSchemaVersion` , `resetAt` , `resetBy` (200 OK)
- Typical use case: schema version upgrade — reset metadata on v1, reassign document to v2, then POST new metadata conforming to v2
---
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`
