query-orchestration/docs/ai.generated/queryapi.summary.md

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)

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