jacob-mathison/query-orchestration
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity
Files
2eff52877bf86d3e570a43a3b47d2202388c0c12
query-orchestration/docs/ai.generated/queryapi.summary.md
T
Jay Brown 2eff52877b Merged in feature/download-pdf (pull request #216) 
retrieve document by id and tests

* working

* missing files
2026-03-17 17:06:57 +00:00

22 KiB
Raw Blame History

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

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

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)

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
Reference in New Issue View Git Blame Copy Permalink