query-orchestration/queryapi.summary.md

Query API Endpoints Summary

This document provides a comprehensive summary of all REST API endpoints available in the Query Orchestration Platform.

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

Client Service

Client Management

• POST /client - Create a new client with provided details

  • Request Body: {id, name}
  • Returns: {id} (201 Created)

• 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

• 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

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

  • Returns: {id, client_id, hash, fields{}}

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[]}

• DELETE /client/{id}/document/batch/{batch_id} - Cancel a batch upload currently processing

  • Returns: 204 No Content on successful cancellation

Query Service

Query Definition and Execution

• GET /query - List queries based on filter criteria

  • Returns: {queries[]} where each query contains {id, type, active_version, latest_version, config?, required_queries[]?}

• POST /query - Create a new query with provided details

  • Request Body: {type, config?, required_queries[]?}
  • Supported Types: JSON_EXTRACTOR, CONTEXT_FULL
  • Returns: {id} (201 Created)

• GET /query/{id} - Get a specific query by its ID

  • Returns: {id, type, active_version, latest_version, config?, required_queries[]?}

• PATCH /query/{id} - Update an existing query with new details

  • Request Body: {config?, active_version?, required_queries[]?}
  • Returns: 200 OK on success

• POST /query/{id}/test - Execute a test run of a query with parameters

  • Request Body: {document_id, query_version}
  • Returns: {value} - Result of the query test

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)

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
• All endpoints require authentication except:
  • GET /login - Public login initiation
  • GET /login-callback - OAuth2 callback handler

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