# 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, DELETE        | ClientService        |
| /client/{id}/status                    | GET                      | ClientService        |
| /client/{id}/collector                 | GET, PATCH               | CollectorService     |
| /client/{id}/folders                   | GET                      | FolderService        |
| /folders                               | POST                     | FolderService        |
| /folders/{folderId}                    | PATCH, DELETE            | 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                      | DocumentsService     |
| /document/{id}                         | GET, DELETE              | DocumentsService     |
| /document/{id}/download                | 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          |
| /ui-settings                           | GET, POST                | UISettingsService    |
| /ui-settings/{id}                      | GET, PATCH, DELETE        | UISettingsService    |
| /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   |

---

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

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

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

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

- **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?}`

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

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

### 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[], document_outcomes[]}`
  - `document_outcomes` provides per-file tracking through the processing pipeline (see [Batch Outcome Tracking Guide](./batch-outcome-tracking-guide.md))

## 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
  - 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
  - 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: 60) - 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`
  - 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
  - Returns: `{users[], total, page, page_size, has_more}`

#### Individual User Operations
- **GET /admin/users/{email}** - Get user by email
  - Hidden users return 404 for User Admin and Client Admin callers
  - Returns: `{cognito_subject_id, email, first_name, last_name, status, enabled, roles[], created_at, updated_at}`

- **HEAD /admin/users/{email}** - Check if user exists
  - Hidden users return 404 for User Admin and Client Admin callers
  - 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[]?}`
  - 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
  - **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
  - 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
  - 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
  - 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
  - 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
  - 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
  - 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}`

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

## 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
  - `GET /ui-settings`, `POST /ui-settings`, `GET /ui-settings/{id}`, `PATCH /ui-settings/{id}`, `DELETE /ui-settings/{id}` - UI settings (JWT required)

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

---

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