openapi.yaml

openapi: 3.0.3
info:
  title: Pangolin Catalog API
  description: Multi-tenant Apache Iceberg REST Catalog with advanced features including federated catalogs, credential vending, and fine-grained permissions
  contact:
    name: Pangolin API Support
    email: support@pangolin.dev
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
paths:
  /api/v1/access-requests:
    get:
      tags:
      - Business Metadata
      operationId: list_access_requests
      responses:
        '200':
          description: List of access requests
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/access-requests/{request_id}:
    get:
      tags:
      - Business Metadata
      operationId: get_access_request
      parameters:
      - name: request_id
        in: path
        description: Request ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request details
        '403':
          description: Forbidden
        '404':
          description: Request not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    put:
      tags:
      - Business Metadata
      operationId: update_access_request
      parameters:
      - name: request_id
        in: path
        description: Request ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequestStatus'
        required: true
      responses:
        '200':
          description: Request updated
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '404':
          description: Request not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/app/config:
    get:
      tags:
      - System Config
      summary: Get public application configuration
      operationId: get_app_config
      responses:
        '200':
          description: App config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppConfig'
  /api/v1/assets/search:
    get:
      tags:
      - Business Metadata
      operationId: search_assets
      responses:
        '200':
          description: Search results
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/assets/{asset_id}:
    get:
      tags:
      - Business Metadata
      operationId: get_asset_details
      parameters:
      - name: asset_id
        in: path
        description: Asset ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Asset details with metadata
        '403':
          description: Forbidden
        '404':
          description: Asset not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/assets/{asset_id}/access-requests:
    post:
      tags:
      - Business Metadata
      operationId: request_access
      parameters:
      - name: asset_id
        in: path
        description: Asset ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccessRequestPayload'
        required: true
      responses:
        '201':
          description: Access request created
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/assets/{asset_id}/metadata:
    get:
      tags:
      - Business Metadata
      operationId: get_business_metadata
      parameters:
      - name: asset_id
        in: path
        description: Asset ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Metadata retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
        '404':
          description: Metadata not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Business Metadata
      operationId: delete_business_metadata
      parameters:
      - name: asset_id
        in: path
        description: Asset ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Metadata deleted
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/audit:
    get:
      tags:
      - Audit Logging
      summary: List audit events with optional filtering
      description: |-
        Returns a list of audit events with support for powerful filtering and pagination.
        All filters are optional and can be combined.
      operationId: list_audit_events
      parameters:
      - name: user_id
        in: query
        description: Filter by user UUID
        required: false
        schema:
          type: string
          format: uuid
          nullable: true
      - name: action
        in: query
        description: Filter by action (e.g., 'create_table')
        required: false
        schema:
          type: string
          nullable: true
      - name: resource_type
        in: query
        description: Filter by resource type (e.g., 'table')
        required: false
        schema:
          type: string
          nullable: true
      - name: resource_id
        in: query
        description: Filter by resource UUID
        required: false
        schema:
          type: string
          format: uuid
          nullable: true
      - name: start_time
        in: query
        description: Filter by start time (ISO 8601)
        required: false
        schema:
          type: string
          nullable: true
      - name: end_time
        in: query
        description: Filter by end time (ISO 8601)
        required: false
        schema:
          type: string
          nullable: true
      - name: result
        in: query
        description: Filter by result ('success' or 'failure')
        required: false
        schema:
          type: string
          nullable: true
      - name: limit
        in: query
        description: 'Maximum results (default: 100, max: 1000)'
        required: false
        schema:
          type: integer
          nullable: true
          minimum: 0
      - name: offset
        in: query
        description: Skip N results for pagination
        required: false
        schema:
          type: integer
          nullable: true
          minimum: 0
      responses:
        '200':
          description: List of audit events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuditLogEntry'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/audit/count:
    get:
      tags:
      - Audit Logging
      summary: Count audit events with optional filtering
      description: |-
        Returns the total count of audit events matching the specified filters.
        Accepts the same query parameters as list_audit_events.
      operationId: count_audit_events
      parameters:
      - name: user_id
        in: query
        description: Filter by user UUID
        required: false
        schema:
          type: string
          format: uuid
          nullable: true
      - name: action
        in: query
        description: Filter by action (e.g., 'create_table')
        required: false
        schema:
          type: string
          nullable: true
      - name: resource_type
        in: query
        description: Filter by resource type (e.g., 'table')
        required: false
        schema:
          type: string
          nullable: true
      - name: resource_id
        in: query
        description: Filter by resource UUID
        required: false
        schema:
          type: string
          format: uuid
          nullable: true
      - name: start_time
        in: query
        description: Filter by start time (ISO 8601)
        required: false
        schema:
          type: string
          nullable: true
      - name: end_time
        in: query
        description: Filter by end time (ISO 8601)
        required: false
        schema:
          type: string
          nullable: true
      - name: result
        in: query
        description: Filter by result ('success' or 'failure')
        required: false
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: Count of audit events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditCountResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/audit/{event_id}:
    get:
      tags:
      - Audit Logging
      summary: Get a specific audit event by ID
      description: Retrieves a single audit event by its unique identifier.
      operationId: get_audit_event
      parameters:
      - name: event_id
        in: path
        description: Audit event ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Audit event details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogEntry'
        '404':
          description: Audit event not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/auth/revoke:
    post:
      tags:
      - Tokens
      summary: Revoke the current user's token (logout)
      operationId: revoke_current_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeTokenRequest'
        required: true
      responses:
        '200':
          description: Token revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeTokenResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/auth/revoke/{token_id}:
    post:
      tags:
      - Tokens
      summary: Admin endpoint to revoke any token by ID
      operationId: revoke_token_by_id
      parameters:
      - name: token_id
        in: path
        description: Token ID to revoke
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeTokenRequest'
        required: true
      responses:
        '200':
          description: Token revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeTokenResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/auth/tokens/cleanup:
    post:
      tags:
      - Tokens
      summary: Admin endpoint to clean up expired tokens
      description: Admin endpoint to clean up expired tokens
      operationId: cleanup_expired_tokens
      responses:
        '200':
          description: Cleaned up expired tokens
          content:
            application/json:
              schema: {}
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/branches:
    get:
      tags:
      - Branches
      operationId: list_branches
      responses:
        '200':
          description: List of branches
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BranchResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Branches
      operationId: create_branch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBranchRequest'
        required: true
      responses:
        '201':
          description: Branch created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchResponse'
        '403':
          description: Forbidden
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/branches/merge:
    post:
      tags:
      - Branches
      operationId: merge_branch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeBranchRequest'
        required: true
      responses:
        '200':
          description: Branches merged successfully
        '400':
          description: Cannot merge experimental branch
        '404':
          description: Branch not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/branches/{name}:
    get:
      tags:
      - Branches
      operationId: get_branch
      parameters:
      - name: name
        in: path
        description: Branch name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Branch details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchResponse'
        '404':
          description: Branch not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/branches/{name}/rebase:
    post:
      tags:
      - Branches
      summary: Rebase a branch onto main (merge main into branch)
      operationId: rebase_branch
      parameters:
      - name: name
        in: path
        description: Branch name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBranchRequest'
        required: true
      responses:
        '200':
          description: Rebase successful
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/bulk/assets/delete:
    post:
      tags:
      - Bulk Operations
      summary: Bulk delete multiple assets
      description: |-
        Deletes up to 100 assets in a single request.
        Returns detailed results including any errors.
      operationId: bulk_delete_assets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteAssetsRequest'
        required: true
      responses:
        '200':
          description: Bulk delete results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResponse'
        '400':
          description: Bad request (e.g., too many assets)
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/catalogs:
    get:
      tags:
      - Catalogs
      operationId: list_catalogs
      responses:
        '200':
          description: List of catalogs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CatalogResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Catalogs
      operationId: create_catalog
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCatalogRequest'
        required: true
      responses:
        '201':
          description: Catalog created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
        '400':
          description: Bad request
        '403':
          description: Forbidden for root user
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/catalogs/{catalog_name}/merge-operations:
    get:
      tags:
      - Merge Operations
      summary: List all merge operations for a catalog
      operationId: list_merge_operations
      parameters:
      - name: catalog_name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of merge operations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MergeOperationResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/catalogs/{catalog_name}/namespaces/{namespace}/assets:
    get:
      tags:
      - Assets
      summary: List all assets in a namespace (Iceberg tables + Generic assets)
      operationId: list_assets
      parameters:
      - name: catalog_name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of assets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetSummary'
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Assets
      summary: Register a generic (non-Iceberg) asset for discovery and metadata management
      operationId: register_asset
      parameters:
      - name: catalog_name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAssetRequest'
        required: true
      responses:
        '201':
          description: Asset registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterAssetResponse'
        '403':
          description: Forbidden
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/catalogs/{name}:
    get:
      tags:
      - Catalogs
      operationId: get_catalog
      parameters:
      - name: name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Catalog details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    put:
      tags:
      - Catalogs
      operationId: update_catalog
      parameters:
      - name: name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCatalogRequest'
        required: true
      responses:
        '200':
          description: Catalog updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Catalogs
      operationId: delete_catalog
      parameters:
      - name: name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Catalog deleted
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/catalogs/{name}/summary:
    get:
      tags:
      - Catalogs
      summary: Get summary statistics for a specific catalog
      operationId: get_catalog_summary
      parameters:
      - name: name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Catalog summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogSummary'
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/catalogs/{prefix}/namespaces/tree:
    get:
      tags:
      - Data Explorer
      summary: List namespace tree structure for a catalog
      operationId: list_namespaces_tree
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Namespace tree structure
        '403':
          description: Forbidden
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/catalogs/{prefix}/namespaces/{namespace}/tables/{table}/maintenance:
    post:
      tags:
      - Data Explorer
      summary: Perform maintenance on a table
      operationId: perform_maintenance
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: Table
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintenanceRequest'
        required: true
      responses:
        '200':
          description: Maintenance accepted
          content:
            application/json:
              schema: {}
        '400':
          description: Bad request
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/config/settings:
    get:
      tags:
      - System Config
      summary: Get system settings
      operationId: get_system_settings
      responses:
        '200':
          description: System settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemSettings'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    put:
      tags:
      - System Config
      summary: Update system settings
      operationId: update_system_settings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemSettings'
        required: true
      responses:
        '200':
          description: Settings updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemSettings'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/conflicts/{conflict_id}/resolve:
    post:
      tags:
      - Merge Operations
      summary: Resolve a specific conflict
      operationId: resolve_conflict
      parameters:
      - name: conflict_id
        in: path
        description: Conflict ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveConflictRequest'
        required: true
      responses:
        '200':
          description: Conflict resolved
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/dashboard/stats:
    get:
      tags:
      - Dashboard
      summary: Get dashboard statistics based on user role
      description: |-
        Returns different scopes based on user role:
        - Root: system-wide statistics
        - Tenant Admin: tenant-wide statistics
        - Tenant User: statistics for accessible resources
      operationId: get_dashboard_stats
      responses:
        '200':
          description: Dashboard statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardStats'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/federated-catalogs:
    get:
      tags:
      - Federated Catalogs
      summary: List all federated catalogs
      operationId: list_federated_catalogs
      responses:
        '200':
          description: List of federated catalogs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FederatedCatalogResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Federated Catalogs
      summary: Create a new federated catalog
      operationId: create_federated_catalog
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFederatedCatalogRequest'
        required: true
      responses:
        '201':
          description: Federated catalog created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederatedCatalogResponse'
        '403':
          description: Forbidden
        '409':
          description: Catalog name conflict
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/federated-catalogs/{catalog_name}:
    get:
      tags:
      - Federated Catalogs
      summary: Get a specific federated catalog
      operationId: get_federated_catalog
      parameters:
      - name: catalog_name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Federated catalog details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederatedCatalogResponse'
        '400':
          description: Not a federated catalog
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Federated Catalogs
      summary: Delete a federated catalog
      operationId: delete_federated_catalog
      parameters:
      - name: catalog_name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Federated catalog deleted
        '400':
          description: Not a federated catalog
        '403':
          description: Forbidden
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/federated-catalogs/{catalog_name}/stats:
    get:
      tags:
      - Federated Catalogs
      summary: Get sync stats for a federated catalog
      operationId: get_federated_catalog_stats
      parameters:
      - name: catalog_name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Sync stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncStats'
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/federated-catalogs/{catalog_name}/sync:
    post:
      tags:
      - Federated Catalogs
      summary: Trigger a sync for a federated catalog
      operationId: sync_federated_catalog
      parameters:
      - name: catalog_name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Sync triggered
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/federated-catalogs/{catalog_name}/test:
    post:
      tags:
      - Federated Catalogs
      summary: Test connection to a federated catalog
      operationId: test_federated_connection
      parameters:
      - name: catalog_name
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Connection successful
        '400':
          description: Not a federated catalog
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
        '503':
          description: Connection failed
      security:
      - bearer_auth: []
  /api/v1/merge-operations/{operation_id}:
    get:
      tags:
      - Merge Operations
      summary: Get a specific merge operation
      operationId: get_merge_operation
      parameters:
      - name: operation_id
        in: path
        description: Merge operation ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Merge operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeOperation'
        '404':
          description: Merge operation not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/merge-operations/{operation_id}/abort:
    post:
      tags:
      - Merge Operations
      summary: Abort a merge operation
      operationId: abort_merge
      parameters:
      - name: operation_id
        in: path
        description: Merge operation ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Merge aborted
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/merge-operations/{operation_id}/complete:
    post:
      tags:
      - Merge Operations
      summary: Complete a merge operation (after all conflicts resolved)
      operationId: complete_merge
      parameters:
      - name: operation_id
        in: path
        description: Merge operation ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Merge completed
        '400':
          description: Cannot complete merge
        '404':
          description: Merge operation not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/merge-operations/{operation_id}/conflicts:
    get:
      tags:
      - Merge Operations
      summary: List conflicts for a merge operation
      operationId: list_merge_conflicts
      parameters:
      - name: operation_id
        in: path
        description: Merge operation ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of merge conflicts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MergeConflict'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/oauth/{provider}/authorize:
    get:
      tags:
      - OAuth
      summary: Initiate OAuth flow
      operationId: oauth_authorize
      parameters:
      - name: provider
        in: path
        description: OAuth provider (google, microsoft, github, okta)
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Redirect to OAuth provider
        '400':
          description: Invalid provider
  /api/v1/oauth/{provider}/callback:
    get:
      tags:
      - OAuth
      summary: OAuth callback handler
      operationId: oauth_callback
      parameters:
      - name: provider
        in: path
        description: OAuth provider (google, microsoft, github, okta)
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Redirect to frontend with token
        '400':
          description: Invalid provider or callback failed
        '500':
          description: Internal server error
  /api/v1/permissions:
    get:
      tags:
      - Roles & Permissions
      operationId: list_permissions
      responses:
        '200':
          description: List of permissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Permission'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Roles & Permissions
      summary: Grant permission to user
      operationId: grant_permission
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantPermissionRequest'
        required: true
      responses:
        '201':
          description: Permission granted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permission'
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/permissions/{id}:
    delete:
      tags:
      - Roles & Permissions
      summary: Revoke permission
      operationId: revoke_permission
      parameters:
      - name: id
        in: path
        description: Permission ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Permission revoked
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/roles:
    get:
      tags:
      - Roles & Permissions
      summary: List roles
      operationId: list_roles
      responses:
        '200':
          description: List of roles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Roles & Permissions
      summary: Create a new role
      operationId: create_role
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleRequest'
        required: true
      responses:
        '201':
          description: Role created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/roles/{id}:
    get:
      tags:
      - Roles & Permissions
      summary: Get role details
      operationId: get_role
      parameters:
      - name: id
        in: path
        description: Role ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Role details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '404':
          description: Role not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    put:
      tags:
      - Roles & Permissions
      summary: Update role
      operationId: update_role
      parameters:
      - name: id
        in: path
        description: Role ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
        required: true
      responses:
        '200':
          description: Role updated
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Roles & Permissions
      summary: Delete role
      operationId: delete_role
      parameters:
      - name: id
        in: path
        description: Role ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Role deleted
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/search:
    get:
      tags:
      - Search
      summary: Unified search across all resources
      description: Searches Assets, Catalogs, Namespaces, and Branches.
      operationId: unified_search
      parameters:
      - name: q
        in: query
        description: Search query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Max results (default 20)
        required: false
        schema:
          type: integer
          nullable: true
          minimum: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedSearchResponse'
        '400':
          description: Bad request
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/search/assets:
    get:
      tags:
      - Search
      summary: Search for assets across catalogs
      description: |-
        Performs a case-insensitive search across asset names.
        Supports filtering by catalog and pagination.
      operationId: search_assets_by_name
      parameters:
      - name: q
        in: query
        description: Search query
        required: true
        schema:
          type: string
      - name: catalog
        in: query
        description: Filter by catalog name
        required: false
        schema:
          type: string
          nullable: true
      - name: limit
        in: query
        description: 'Maximum results (default: 50)'
        required: false
        schema:
          type: integer
          nullable: true
          minimum: 0
      - name: offset
        in: query
        description: 'Pagination offset (default: 0)'
        required: false
        schema:
          type: integer
          nullable: true
          minimum: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/service-users:
    get:
      tags:
      - Service Users
      summary: List service users for the tenant
      description: GET /api/v1/service-users
      operationId: list_service_users
      responses:
        '200':
          description: List of service users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceUser'
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Service Users
      summary: Create a new service user
      description: POST /api/v1/service-users
      operationId: create_service_user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceUserRequest'
        required: true
      responses:
        '201':
          description: Service user created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/service-users/{id}:
    get:
      tags:
      - Service Users
      summary: Get a specific service user
      description: GET /api/v1/service-users/{id}
      operationId: get_service_user
      parameters:
      - name: id
        in: path
        description: Service user ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Service user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUser'
        '403':
          description: Forbidden
        '404':
          description: Service user not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    put:
      tags:
      - Service Users
      summary: Update a service user
      description: PUT /api/v1/service-users/{id}
      operationId: update_service_user
      parameters:
      - name: id
        in: path
        description: Service user ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceUserRequest'
        required: true
      responses:
        '200':
          description: Service user updated
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Service Users
      summary: Delete a service user
      description: DELETE /api/v1/service-users/{id}
      operationId: delete_service_user
      parameters:
      - name: id
        in: path
        description: Service user ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Service user deleted
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/service-users/{id}/rotate:
    post:
      tags:
      - Service Users
      summary: Rotate API key for a service user
      description: POST /api/v1/service-users/{id}/rotate
      operationId: rotate_api_key
      parameters:
      - name: id
        in: path
        description: Service user ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: API key rotated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        '403':
          description: Forbidden
        '404':
          description: Service user not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/storage/presigned-url:
    get:
      tags:
      - Data Explorer
      summary: Get a presigned URL for a specific file location
      description: Get a presigned URL for a specific file location
      operationId: get_presigned_url
      parameters:
      - name: location
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Presigned URL generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresignResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/tags:
    get:
      tags:
      - Tags
      operationId: list_tags
      responses:
        '200':
          description: List of tags
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Tags
      operationId: create_tag
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTagRequest'
        required: true
      responses:
        '201':
          description: Tag created
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/tags/{name}:
    delete:
      tags:
      - Tags
      operationId: delete_tag
      parameters:
      - name: name
        in: path
        description: Tag name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Tag deleted
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/tenants:
    get:
      tags:
      - Tenants
      operationId: list_tenants
      responses:
        '200':
          description: List of tenants
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TenantResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Tenants
      operationId: create_tenant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTenantRequest'
        required: true
      responses:
        '201':
          description: Tenant created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantResponse'
        '403':
          description: Forbidden in NO_AUTH mode
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/tenants/{id}:
    get:
      tags:
      - Tenants
      operationId: get_tenant
      parameters:
      - name: id
        in: path
        description: Tenant ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Tenant details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantResponse'
        '404':
          description: Tenant not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    put:
      tags:
      - Tenants
      operationId: update_tenant
      parameters:
      - name: id
        in: path
        description: Tenant ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTenantRequest'
        required: true
      responses:
        '200':
          description: Tenant updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantResponse'
        '404':
          description: Tenant not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Tenants
      operationId: delete_tenant
      parameters:
      - name: id
        in: path
        description: Tenant ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Tenant deleted
        '404':
          description: Tenant not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/tokens:
    post:
      tags:
      - Tokens
      summary: Generate a JWT token for a tenant
      description: This endpoint allows generating tokens for testing and development
      operationId: generate_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateTokenRequest'
        required: true
      responses:
        '200':
          description: Token generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateTokenResponse'
        '400':
          description: Bad request
        '500':
          description: Internal server error
  /api/v1/tokens/rotate:
    post:
      tags:
      - Tokens
      summary: Rotate current token
      operationId: rotate_token
      responses:
        '200':
          description: Token rotated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateTokenResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/tokens/{token_id}:
    delete:
      tags:
      - Tokens
      summary: Delete (Revoke) a token by ID
      operationId: delete_token
      parameters:
      - name: token_id
        in: path
        description: Token ID to revoke
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Token revoked
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/users:
    get:
      tags:
      - Users
      summary: List all users (filtered by permissions)
      operationId: list_users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserInfo'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Users
      summary: Create a new user
      operationId: create_user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
        required: true
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/users/login:
    post:
      tags:
      - Users
      summary: User login
      operationId: login
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
        '500':
          description: Internal server error
  /api/v1/users/logout:
    post:
      tags:
      - Users
      summary: Logout (invalidate token)
      description: Logout current user (client-side primarily)
      operationId: logout
      responses:
        '204':
          description: Logged out successfully
      security:
      - bearer_auth: []
  /api/v1/users/me:
    get:
      tags:
      - Users
      summary: Get current user
      description: Get current logged-in user details
      operationId: get_current_user
      responses:
        '200':
          description: Current user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Unauthorized
      security:
      - bearer_auth: []
  /api/v1/users/me/tokens:
    get:
      tags:
      - Tokens
      summary: List tokens for current user
      operationId: list_my_tokens
      responses:
        '200':
          description: List of active tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenInfo'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/users/{user_id}:
    get:
      tags:
      - Users
      summary: Get user by ID
      operationId: get_user
      parameters:
      - name: user_id
        in: path
        description: User ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '403':
          description: Forbidden
        '404':
          description: User not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    put:
      tags:
      - Users
      summary: Update user
      operationId: update_user
      parameters:
      - name: user_id
        in: path
        description: User ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
        required: true
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '403':
          description: Forbidden
        '404':
          description: User not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Users
      summary: Delete user
      operationId: delete_user
      parameters:
      - name: user_id
        in: path
        description: User ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: User deleted
        '400':
          description: Cannot delete yourself
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/users/{user_id}/roles:
    get:
      tags:
      - Roles & Permissions
      summary: Get user roles
      description: Get roles assigned to a user
      operationId: get_user_roles
      parameters:
      - name: user_id
        in: path
        description: User ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of user roles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Roles & Permissions
      summary: Assign role to user
      description: Assign a role to a user
      operationId: assign_role
      parameters:
      - name: user_id
        in: path
        description: User ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignRoleRequest'
        required: true
      responses:
        '201':
          description: Role assigned
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/users/{user_id}/roles/{role_id}:
    delete:
      tags:
      - Roles & Permissions
      summary: Revoke role from user
      description: Revoke a role from a user
      operationId: revoke_role
      parameters:
      - name: user_id
        in: path
        description: User ID
        required: true
        schema:
          type: string
          format: uuid
      - name: role_id
        in: path
        description: Role ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Role revoked
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/users/{user_id}/tokens:
    get:
      tags:
      - Tokens
      summary: List tokens for a specific user (Admin only)
      operationId: list_user_tokens
      parameters:
      - name: user_id
        in: path
        description: User ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of active tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenInfo'
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/validate/names:
    post:
      tags:
      - Validation
      summary: Validate resource name availability
      description: |-
        Checks if catalog or warehouse names are available.
        Supports batch validation of multiple names.
      operationId: validate_names
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateNamesRequest'
        required: true
      responses:
        '200':
          description: Validation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateNamesResponse'
        '400':
          description: Bad request
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/warehouses:
    get:
      tags:
      - Warehouses
      operationId: list_warehouses
      responses:
        '200':
          description: List of warehouses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WarehouseResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Warehouses
      operationId: create_warehouse
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWarehouseRequest'
        required: true
      responses:
        '201':
          description: Warehouse created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseResponse'
        '403':
          description: Forbidden for root user
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /api/v1/warehouses/{name}:
    get:
      tags:
      - Warehouses
      operationId: get_warehouse
      parameters:
      - name: name
        in: path
        description: Warehouse name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Warehouse details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseResponse'
        '404':
          description: Warehouse not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    put:
      tags:
      - Warehouses
      operationId: update_warehouse
      parameters:
      - name: name
        in: path
        description: Warehouse name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWarehouseRequest'
        required: true
      responses:
        '200':
          description: Warehouse updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseResponse'
        '404':
          description: Warehouse not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Warehouses
      operationId: delete_warehouse
      parameters:
      - name: name
        in: path
        description: Warehouse name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Warehouse deleted
        '404':
          description: Warehouse not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /v1/config:
    get:
      tags:
      - Iceberg REST
      operationId: get_iceberg_catalog_config_handler
      responses:
        '200':
          description: Catalog configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogConfig'
  /v1/{prefix}/namespaces:
    get:
      tags:
      - Iceberg REST
      summary: List namespaces in a catalog
      operationId: list_namespaces
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: parent
        in: query
        required: false
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: List of namespaces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNamespacesResponse'
        '403':
          description: Forbidden
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Iceberg REST
      summary: Create a namespace
      operationId: create_namespace
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNamespaceRequest'
        required: true
      responses:
        '200':
          description: Namespace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateNamespaceResponse'
        '403':
          description: Forbidden
        '404':
          description: Catalog not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /v1/{prefix}/namespaces/{namespace}:
    delete:
      tags:
      - Iceberg REST
      summary: Delete a namespace
      operationId: delete_namespace
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Namespace deleted
        '403':
          description: Forbidden
        '404':
          description: Namespace not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /v1/{prefix}/namespaces/{namespace}/properties:
    post:
      tags:
      - Iceberg REST
      summary: Update namespace properties
      operationId: update_namespace_properties
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
        required: true
      responses:
        '200':
          description: Properties updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateNamespacePropertiesResponse'
        '403':
          description: Forbidden
        '404':
          description: Namespace not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /v1/{prefix}/namespaces/{namespace}/tables:
    get:
      tags:
      - Iceberg REST
      summary: List tables in a namespace
      operationId: list_tables
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace (optionally with @branch)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of tables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTablesResponse'
        '403':
          description: Forbidden
        '404':
          description: Catalog or namespace not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Iceberg REST
      summary: Create a table
      operationId: create_table
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace (optionally with @branch)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableRequest'
        required: true
      responses:
        '200':
          description: Table created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '403':
          description: Forbidden
        '404':
          description: Catalog or namespace not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /v1/{prefix}/namespaces/{namespace}/tables/{table}:
    get:
      tags:
      - Iceberg REST
      summary: Load a table
      operationId: load_table
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace (optionally with @branch)
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: Table name (optionally with @branch)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Table metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '403':
          description: Forbidden
        '404':
          description: Table not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    post:
      tags:
      - Iceberg REST
      summary: Update a table (Commit)
      operationId: update_table
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace (optionally with @branch)
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: Table name (optionally with @branch)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitTableRequest'
        required: true
      responses:
        '200':
          description: Table updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '403':
          description: Forbidden
        '404':
          description: Table not found
        '409':
          description: Conflict (OCC failed)
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    delete:
      tags:
      - Iceberg REST
      summary: Delete a table
      operationId: delete_table
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace (optionally with @branch)
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: Table name (optionally with @branch)
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Table deleted
        '403':
          description: Forbidden
        '404':
          description: Table not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
    head:
      tags:
      - Iceberg REST
      summary: Check if a table exists
      operationId: table_exists
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: Table
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Table exists
        '404':
          description: Table not found
      security:
      - bearer_auth: []
  /v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials:
    get:
      tags:
      - Iceberg REST
      summary: Get credentials for accessing a table
      description: This endpoint vends credentials based on the catalog's warehouse configuration
      operationId: get_table_credentials
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: Table
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Credentials vended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadCredentialsResponse'
        '403':
          description: Forbidden
        '404':
          description: Catalog or Warehouse not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics:
    post:
      tags:
      - Iceberg REST
      summary: Report metrics for a table
      operationId: report_metrics
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: Table
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Metrics reported
  /v1/{prefix}/namespaces/{namespace}/views:
    post:
      tags:
      - Iceberg REST
      summary: Create a database view
      operationId: create_view
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateViewRequest'
        required: true
      responses:
        '201':
          description: View created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewResponse'
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /v1/{prefix}/namespaces/{namespace}/views/{view}:
    get:
      tags:
      - Iceberg REST
      summary: Get a database view
      operationId: get_view
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      - name: namespace
        in: path
        description: Namespace
        required: true
        schema:
          type: string
      - name: view
        in: path
        description: View name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: View details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewResponse'
        '404':
          description: View not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
  /v1/{prefix}/tables/rename:
    post:
      tags:
      - Iceberg REST
      summary: Rename a table
      operationId: rename_table
      parameters:
      - name: prefix
        in: path
        description: Catalog name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameTableRequest'
        required: true
      responses:
        '204':
          description: Table renamed
        '404':
          description: Source table not found
        '500':
          description: Internal server error
      security:
      - bearer_auth: []
components:
  schemas:
    AccessRequest:
      type: object
      description: Access request for discoverable assets
      required:
      - id
      - tenant-id
      - user-id
      - asset-id
      - requested-at
      - status
      properties:
        asset-id:
          type: string
          format: uuid
        id:
          type: string
          format: uuid
        reason:
          type: string
          nullable: true
        requested-at:
          type: string
          format: date-time
        review-comment:
          type: string
          nullable: true
        reviewed-at:
          type: string
          format: date-time
          nullable: true
        reviewed-by:
          type: string
          format: uuid
          nullable: true
        status:
          $ref: '#/components/schemas/RequestStatus'
        tenant-id:
          type: string
          format: uuid
        user-id:
          type: string
          format: uuid
    Action:
      type: string
      description: Actions that can be performed
      enum:
      - read
      - write
      - delete
      - create
      - update
      - list
      - all
      - ingest-branching
      - experimental-branching
      - manage-discovery
    AddMetadataRequest:
      type: object
      required:
      - tags
      - properties
      - discoverable
      properties:
        description:
          type: string
          nullable: true
        discoverable:
          type: boolean
        properties: {}
        tags:
          type: array
          items:
            type: string
    ApiKeyResponse:
      type: object
      description: API Key response (only shown once on creation)
      required:
      - service_user_id
      - name
      - api_key
      properties:
        api_key:
          type: string
        expires_at:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
        service_user_id:
          type: string
          format: uuid
    AppConfig:
      type: object
      description: App configuration (public)
      required:
      - auth_enabled
      properties:
        auth_enabled:
          type: boolean
    AssetSearchResult:
      type: object
      required:
      - id
      - name
      - namespace
      - catalog
      - asset_type
      properties:
        asset_type:
          type: string
        catalog:
          type: string
        id:
          type: string
        name:
          type: string
        namespace:
          type: array
          items:
            type: string
    AssetSummary:
      type: object
      required:
      - id
      - name
      - namespace
      - kind
      - identifier
      properties:
        id:
          type: string
          format: uuid
        identifier:
          $ref: '#/components/schemas/crate.iceberg_handlers.TableIdentifier'
        kind:
          $ref: '#/components/schemas/AssetType'
        name:
          type: string
        namespace:
          type: array
          items:
            type: string
    AssignRoleRequest:
      type: object
      description: Request to assign a role to a user
      required:
      - role-id
      properties:
        role-id:
          type: string
          format: uuid
    AuditAction:
      type: string
      description: Types of actions that can be audited
      enum:
      - create_catalog
      - update_catalog
      - delete_catalog
      - create_namespace
      - update_namespace
      - delete_namespace
      - create_table
      - update_table
      - drop_table
      - rename_table
      - commit_table
      - load_table
      - create_view
      - update_view
      - drop_view
      - rename_view
      - load_view
      - create_branch
      - delete_branch
      - merge_branch
      - create_user
      - update_user
      - delete_user
      - login
      - logout
      - create_service_user
      - update_service_user
      - delete_service_user
      - rotate_api_key
      - grant_permission
      - revoke_permission
      - create_federated_catalog
      - update_federated_catalog
      - delete_federated_catalog
      - test_federated_connection
      - create_warehouse
      - update_warehouse
      - delete_warehouse
      - create_tenant
      - update_tenant
      - delete_tenant
      - create_tag
      - delete_tag
      - initiate_merge
      - complete_merge
      - abort_merge
      - resolve_conflict
      - list_conflicts
      - add_metadata
      - update_metadata
      - delete_metadata
      - search_assets
      - request_access
      - approve_access
      - deny_access
      - update_access_request
      - generate_token
      - revoke_token
      - create_commit
      - list_commits
    AuditCountResponse:
      type: object
      description: Response for audit event count
      required:
      - count
      properties:
        count:
          type: integer
          description: Total number of audit events matching the filter
          example: 42
          minimum: 0
    AuditListQuery:
      type: object
      description: Query parameters for listing audit events
      properties:
        action:
          type: string
          description: Filter by action (e.g., "create_table", "update_catalog")
          example: create_table
          nullable: true
        end_time:
          type: string
          description: Filter by end time (ISO 8601 format)
          example: 2025-12-31T23:59:59Z
          nullable: true
        limit:
          type: integer
          description: 'Maximum number of results to return (default: 100, max: 1000)'
          example: 50
          nullable: true
          minimum: 0
        offset:
          type: integer
          description: Number of results to skip for pagination
          example: 0
          nullable: true
          minimum: 0
        resource_id:
          type: string
          format: uuid
          description: Filter by resource ID
          example: 660e8400-e29b-41d4-a716-446655440000
          nullable: true
        resource_type:
          type: string
          description: Filter by resource type (e.g., "table", "catalog", "user")
          example: table
          nullable: true
        result:
          type: string
          description: Filter by result ("success" or "failure")
          example: success
          nullable: true
        start_time:
          type: string
          description: Filter by start time (ISO 8601 format)
          example: 2025-12-01T00:00:00Z
          nullable: true
        user_id:
          type: string
          format: uuid
          description: Filter by user ID
          example: 550e8400-e29b-41d4-a716-446655440000
          nullable: true
    AuditLogEntry:
      type: object
      description: Comprehensive audit log entry for tracking all catalog operations
      required:
      - id
      - tenant_id
      - username
      - action
      - resource_type
      - resource_name
      - timestamp
      - result
      properties:
        action:
          $ref: '#/components/schemas/AuditAction'
        error_message:
          type: string
          description: Error message if the operation failed
          nullable: true
        id:
          type: string
          format: uuid
          description: Unique identifier for this audit log entry
        ip_address:
          type: string
          description: Client IP address (if available)
          nullable: true
        metadata:
          description: Additional structured metadata about the operation
          nullable: true
        resource_id:
          type: string
          format: uuid
          description: UUID of the specific resource (if applicable)
          nullable: true
        resource_name:
          type: string
          description: Human-readable resource name/path
        resource_type:
          $ref: '#/components/schemas/ResourceType'
        result:
          $ref: '#/components/schemas/AuditResult'
        tenant_id:
          type: string
          format: uuid
          description: Tenant that owns the resource being operated on
        timestamp:
          type: string
          format: date-time
          description: When the action occurred (UTC)
        user_agent:
          type: string
          description: Client user agent (if available)
          nullable: true
        user_id:
          type: string
          format: uuid
          description: User who performed the action (None for system operations)
          nullable: true
        username:
          type: string
          description: Username for readability (actor field for backward compatibility)
    AuditResult:
      type: string
      description: Result of an audited operation
      enum:
      - success
      - failure
    AuthorizeParams:
      type: object
      properties:
        redirect_uri:
          type: string
          nullable: true
    BranchResponse:
      type: object
      required:
      - name
      - branch_type
      - assets
      properties:
        assets:
          type: array
          items:
            type: string
        branch_type:
          type: string
        head_commit_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
    BulkDeleteAssetsRequest:
      type: object
      required:
      - asset_ids
      properties:
        asset_ids:
          type: array
          items:
            type: string
          description: List of asset UUIDs to delete (maximum 100)
    BulkOperationResponse:
      type: object
      required:
      - succeeded
      - failed
      - errors
      properties:
        errors:
          type: array
          items:
            type: string
        failed:
          type: integer
          minimum: 0
        succeeded:
          type: integer
          minimum: 0
    BusinessMetadata:
      type: object
      description: Business metadata attached to assets
      required:
      - id
      - asset-id
      - tags
      - properties
      - discoverable
      - created-by
      - created-at
      - updated-by
      - updated-at
      properties:
        asset-id:
          type: string
          format: uuid
        created-at:
          type: string
          format: date-time
        created-by:
          type: string
          format: uuid
        description:
          type: string
          description: Markdown description
          nullable: true
        discoverable:
          type: boolean
          description: Whether this asset appears in search for users without access
        id:
          type: string
          format: uuid
        properties:
          description: Custom key-value properties
        tags:
          type: array
          items:
            type: string
          description: Tags/labels for categorization
        updated-at:
          type: string
          format: date-time
        updated-by:
          type: string
          format: uuid
    Catalog:
      type: object
      required:
      - id
      - name
      - catalog_type
      - properties
      properties:
        catalog_type:
          $ref: '#/components/schemas/CatalogType'
        federated_config:
          allOf:
          - $ref: '#/components/schemas/FederatedCatalogConfig'
          nullable: true
        id:
          type: string
          format: uuid
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
        storage_location:
          type: string
          nullable: true
        warehouse_name:
          type: string
          nullable: true
    CatalogResponse:
      type: object
      required:
      - id
      - name
      - catalog_type
      - properties
      properties:
        catalog_type:
          $ref: '#/components/schemas/pangolin_core.model.CatalogType'
        federated_config:
          allOf:
          - $ref: '#/components/schemas/pangolin_core.model.FederatedCatalogConfig'
          nullable: true
        id:
          type: string
          format: uuid
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
        storage_location:
          type: string
          nullable: true
        warehouse_name:
          type: string
          nullable: true
    CatalogSummary:
      type: object
      required:
      - name
      - table_count
      - namespace_count
      - branch_count
      properties:
        branch_count:
          type: integer
          minimum: 0
        name:
          type: string
        namespace_count:
          type: integer
          minimum: 0
        storage_location:
          type: string
          nullable: true
        table_count:
          type: integer
          minimum: 0
    CatalogType:
      type: string
      enum:
      - Local
      - Federated
    CatalogUpdate:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
        storage_location:
          type: string
          nullable: true
        warehouse_name:
          type: string
          nullable: true
    CommitRequirement:
      oneOf:
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - assert-create
      - type: object
        required:
        - uuid
        - type
        properties:
          type:
            type: string
            enum:
            - assert-table-uuid
          uuid:
            type: string
      - type: object
        required:
        - ref
        - type
        properties:
          ref:
            type: string
          snapshot-id:
            type: integer
            format: int64
            nullable: true
          type:
            type: string
            enum:
            - assert-ref-snapshot-id
      - type: object
        required:
        - type
        properties:
          current-schema-id:
            type: integer
            format: int32
            nullable: true
          type:
            type: string
            enum:
            - assert-current-schema-id
      discriminator:
        propertyName: type
    CommitTableRequest:
      type: object
      required:
      - requirements
      - updates
      properties:
        identifier:
          allOf:
          - $ref: '#/components/schemas/TableIdentifier'
          nullable: true
        requirements:
          type: array
          items:
            $ref: '#/components/schemas/CommitRequirement'
        updates:
          type: array
          items:
            $ref: '#/components/schemas/CommitUpdate'
    CommitUpdate:
      oneOf:
      - type: object
        required:
        - uuid
        - action
        properties:
          action:
            type: string
            enum:
            - assign-uuid
          uuid:
            type: string
      - type: object
        required:
        - format-version
        - action
        properties:
          action:
            type: string
            enum:
            - upgrade-format-version
          format-version:
            type: integer
            format: int32
      - type: object
        required:
        - schema
        - action
        properties:
          action:
            type: string
            enum:
            - add-schema
          schema: {}
      - type: object
        required:
        - schema-id
        - action
        properties:
          action:
            type: string
            enum:
            - set-current-schema
          schema-id:
            type: integer
            format: int32
      - type: object
        required:
        - snapshot
        - action
        properties:
          action:
            type: string
            enum:
            - add-snapshot
          snapshot: {}
      - type: object
        required:
        - ref-name
        - snapshot-id
        - type
        - action
        properties:
          action:
            type: string
            enum:
            - set-snapshot-ref
          ref-name:
            type: string
          snapshot-id:
            type: integer
            format: int64
          type:
            type: string
      - type: object
        required:
        - updates
        - action
        properties:
          action:
            type: string
            enum:
            - set-properties
          updates:
            type: object
            additionalProperties:
              type: string
      discriminator:
        propertyName: action
    ConflictResolution:
      type: object
      required:
      - conflict_id
      - strategy
      - resolved_by
      - resolved_at
      properties:
        conflict_id:
          type: string
          format: uuid
        resolved_at:
          type: string
          format: date-time
        resolved_by:
          type: string
          format: uuid
        resolved_value:
          nullable: true
        strategy:
          $ref: '#/components/schemas/ResolutionStrategy'
    ConflictType:
      oneOf:
      - type: object
        required:
        - SchemaChange
        properties:
          SchemaChange:
            type: object
            required:
            - asset_name
            - source_schema
            - target_schema
            properties:
              asset_name:
                type: string
              source_schema: {}
              target_schema: {}
      - type: object
        required:
        - DataOverlap
        properties:
          DataOverlap:
            type: object
            required:
            - asset_name
            - overlapping_partitions
            properties:
              asset_name:
                type: string
              overlapping_partitions:
                type: array
                items:
                  type: string
      - type: object
        required:
        - MetadataConflict
        properties:
          MetadataConflict:
            type: object
            required:
            - asset_name
            - conflicting_properties
            properties:
              asset_name:
                type: string
              conflicting_properties:
                type: array
                items:
                  type: string
      - type: object
        required:
        - DeletionConflict
        properties:
          DeletionConflict:
            type: object
            required:
            - asset_name
            - deleted_in
            - modified_in
            properties:
              asset_name:
                type: string
              deleted_in:
                type: string
              modified_in:
                type: string
    CreateAccessRequestPayload:
      type: object
      properties:
        reason:
          type: string
          nullable: true
    CreateBranchRequest:
      type: object
      required:
      - name
      - catalog
      properties:
        assets:
          type: array
          items:
            type: string
          nullable: true
        branch_type:
          type: string
          nullable: true
        catalog:
          type: string
          description: Catalog name (required)
        from_branch:
          type: string
          nullable: true
        name:
          type: string
    CreateCatalogRequest:
      type: object
      required:
      - name
      properties:
        catalog_type:
          allOf:
          - $ref: '#/components/schemas/pangolin_core.model.CatalogType'
          nullable: true
        federated_config:
          allOf:
          - $ref: '#/components/schemas/pangolin_core.model.FederatedCatalogConfig'
          nullable: true
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
        storage_location:
          type: string
          nullable: true
        warehouse_name:
          type: string
          nullable: true
    CreateFederatedCatalogRequest:
      type: object
      required:
      - name
      - config
      properties:
        config:
          $ref: '#/components/schemas/FederatedCatalogConfig'
        name:
          type: string
    CreateNamespaceRequest:
      type: object
      required:
      - namespace
      properties:
        namespace:
          type: array
          items:
            type: string
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
    CreateNamespaceResponse:
      type: object
      required:
      - namespace
      - properties
      properties:
        namespace:
          type: array
          items:
            type: string
        properties:
          type: object
          additionalProperties:
            type: string
    CreateRoleRequest:
      type: object
      description: Request to create a new role
      required:
      - name
      - tenant-id
      properties:
        description:
          type: string
          nullable: true
        name:
          type: string
        tenant-id:
          type: string
          format: uuid
    CreateServiceUserRequest:
      type: object
      required:
      - name
      - role
      properties:
        description:
          type: string
          nullable: true
        expires_in_days:
          type: integer
          format: int64
          nullable: true
        name:
          type: string
        role:
          $ref: '#/components/schemas/UserRole'
    CreateTableRequest:
      type: object
      required:
      - name
      properties:
        location:
          type: string
          nullable: true
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
        schema:
          nullable: true
    CreateTenantRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
    CreateUserRequest:
      type: object
      description: Request to create a new user
      required:
      - username
      - email
      - role
      properties:
        email:
          type: string
        password:
          type: string
          nullable: true
        role:
          $ref: '#/components/schemas/UserRole'
        tenant_id:
          type: string
          format: uuid
          nullable: true
        username:
          type: string
    CreateViewRequest:
      type: object
      required:
      - name
      - sql
      properties:
        dialect:
          type: string
          nullable: true
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
        sql:
          type: string
    CreateWarehouseRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        storage_config:
          type: object
          additionalProperties:
            type: string
          nullable: true
        use_sts:
          type: boolean
          nullable: true
        vending_strategy:
          allOf:
          - $ref: '#/components/schemas/VendingStrategy'
          nullable: true
    DashboardStats:
      type: object
      required:
      - catalogs_count
      - tables_count
      - namespaces_count
      - users_count
      - warehouses_count
      - branches_count
      - tenants_count
      - scope
      properties:
        branches_count:
          type: integer
          minimum: 0
        catalogs_count:
          type: integer
          minimum: 0
        namespaces_count:
          type: integer
          minimum: 0
        scope:
          type: string
          description: 'Scope of statistics: "system", "tenant", or "user"'
        tables_count:
          type: integer
          minimum: 0
        tenants_count:
          type: integer
          minimum: 0
        users_count:
          type: integer
          minimum: 0
        warehouses_count:
          type: integer
          minimum: 0
    FederatedCatalogConfig:
      type: object
      required:
      - properties
      properties:
        properties:
          type: object
          additionalProperties:
            type: string
    FederatedCatalogResponse:
      type: object
      required:
      - id
      - name
      - properties
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
    GenerateTokenRequest:
      type: object
      required:
      - tenant_id
      properties:
        expires_in_hours:
          type: integer
          format: int64
          nullable: true
          minimum: 0
        roles:
          type: array
          items:
            type: string
          nullable: true
        tenant_id:
          type: string
        username:
          type: string
          nullable: true
    GenerateTokenResponse:
      type: object
      required:
      - token
      - expires_at
      - tenant_id
      properties:
        expires_at:
          type: string
        tenant_id:
          type: string
        token:
          type: string
    GrantPermissionRequest:
      type: object
      description: Request to grant a permission
      required:
      - user-id
      - scope
      - actions
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          uniqueItems: true
        scope:
          $ref: '#/components/schemas/PermissionScope'
        user-id:
          type: string
          format: uuid
    ListBranchParams:
      type: object
      required:
      - catalog
      properties:
        catalog:
          type: string
          description: Catalog name (required)
        name:
          type: string
          nullable: true
    ListNamespacesResponse:
      type: object
      required:
      - namespaces
      properties:
        namespaces:
          type: array
          items:
            type: array
            items:
              type: string
    ListNamespacesTreeResponse:
      type: object
      required:
      - root
      properties:
        root:
          type: array
          items:
            $ref: '#/components/schemas/NamespaceNode'
    ListTablesResponse:
      type: object
      required:
      - identifiers
      properties:
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/TableIdentifier'
    LoadCredentialsResponse:
      type: object
      required:
      - storage-credentials
      properties:
        storage-credentials:
          type: array
          items:
            $ref: '#/components/schemas/StorageCredential'
    LoginRequest:
      type: object
      description: User login request
      required:
      - username
      - password
      properties:
        password:
          type: string
        tenant-id:
          type: string
          format: uuid
          description: Optional tenant ID for tenant-scoped login. If null/omitted, authenticates as Root user.
          nullable: true
        username:
          type: string
    LoginResponse:
      type: object
      description: Login response with JWT token
      required:
      - token
      - user
      - expires-at
      properties:
        expires-at:
          type: string
        token:
          type: string
        user:
          $ref: '#/components/schemas/UserInfo'
    MaintenanceRequest:
      type: object
      required:
      - job_type
      properties:
        job_type:
          type: string
        older_than_ms:
          type: integer
          format: int64
          nullable: true
        retention_ms:
          type: integer
          format: int64
          nullable: true
    MergeBranchRequest:
      type: object
      required:
      - source_branch
      - target_branch
      - catalog
      properties:
        catalog:
          type: string
          description: Catalog name (required)
        source_branch:
          type: string
        target_branch:
          type: string
    MergeConflict:
      type: object
      required:
      - id
      - merge_operation_id
      - conflict_type
      - description
      - created_at
      properties:
        asset_id:
          type: string
          format: uuid
          nullable: true
        conflict_type:
          $ref: '#/components/schemas/ConflictType'
        created_at:
          type: string
          format: date-time
        description:
          type: string
        id:
          type: string
          format: uuid
        merge_operation_id:
          type: string
          format: uuid
        resolution:
          allOf:
          - $ref: '#/components/schemas/ConflictResolution'
          nullable: true
    MergeOperation:
      type: object
      required:
      - id
      - tenant_id
      - catalog_name
      - source_branch
      - target_branch
      - status
      - conflicts
      - initiated_by
      - initiated_at
      properties:
        base_commit_id:
          type: string
          format: uuid
          nullable: true
        catalog_name:
          type: string
        completed_at:
          type: string
          format: date-time
          nullable: true
        conflicts:
          type: array
          items:
            type: string
            format: uuid
        id:
          type: string
          format: uuid
        initiated_at:
          type: string
          format: date-time
        initiated_by:
          type: string
          format: uuid
        result_commit_id:
          type: string
          format: uuid
          nullable: true
        source_branch:
          type: string
        status:
          $ref: '#/components/schemas/MergeStatus'
        target_branch:
          type: string
        tenant_id:
          type: string
          format: uuid
    MergeOperationResponse:
      type: object
      required:
      - id
      - status
      - source_branch
      - target_branch
      - conflicts_count
      - initiated_at
      properties:
        completed_at:
          type: string
          nullable: true
        conflicts_count:
          type: integer
          minimum: 0
        id:
          type: string
          format: uuid
        initiated_at:
          type: string
        source_branch:
          type: string
        status:
          type: string
        target_branch:
          type: string
    MergeStatus:
      type: string
      enum:
      - Pending
      - Conflicted
      - Resolving
      - Ready
      - Completed
      - Aborted
    MetadataLogEntry:
      type: object
      required:
      - timestamp-ms
      - metadata-file
      properties:
        metadata-file:
          type: string
        timestamp-ms:
          type: integer
          format: int64
    MetadataResponse:
      type: object
      required:
      - metadata
      properties:
        metadata:
          $ref: '#/components/schemas/BusinessMetadata'
    NameValidationResult:
      type: object
      required:
      - name
      - available
      properties:
        available:
          type: boolean
        name:
          type: string
        reason:
          type: string
          nullable: true
    NamespaceNode:
      type: object
      required:
      - name
      - full_path
      - children
      properties:
        children:
          type: array
          items:
            $ref: '#/components/schemas/NamespaceNode'
        full_path:
          type: array
          items:
            type: string
        name:
          type: string
    NestedField:
      type: object
      required:
      - id
      - name
      - required
      - type
      properties:
        doc:
          type: string
          nullable: true
        id:
          type: integer
          format: int32
        name:
          type: string
        required:
          type: boolean
        type:
          $ref: '#/components/schemas/Type'
    OAuthCallback:
      type: object
      description: OAuth callback query parameters
      required:
      - code
      properties:
        code:
          type: string
        state:
          type: string
          nullable: true
    OAuthProvider:
      type: string
      description: OAuth provider
      enum:
      - google
      - microsoft
      - github
      - okta
    PartitionField:
      type: object
      required:
      - source-id
      - field-id
      - name
      - transform
      properties:
        field-id:
          type: integer
          format: int32
        name:
          type: string
        source-id:
          type: integer
          format: int32
        transform:
          type: string
    PartitionSpec:
      type: object
      required:
      - spec-id
      - fields
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/PartitionField'
        spec-id:
          type: integer
          format: int32
    Permission:
      type: object
      description: A single permission grant
      required:
      - id
      - user-id
      - scope
      - actions
      - granted-by
      - granted-at
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          uniqueItems: true
        granted-at:
          type: string
          format: date-time
        granted-by:
          type: string
          format: uuid
        id:
          type: string
          format: uuid
        scope:
          $ref: '#/components/schemas/PermissionScope'
        user-id:
          type: string
          format: uuid
    PermissionGrant:
      type: object
      description: Permission grant within a role
      required:
      - scope
      - actions
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          uniqueItems: true
        scope:
          $ref: '#/components/schemas/PermissionScope'
    PermissionScope:
      oneOf:
      - type: object
        description: Applies to entire catalog
        required:
        - catalog_id
        - type
        properties:
          catalog_id:
            type: string
            format: uuid
          type:
            type: string
            enum:
            - catalog
      - type: object
        description: Applies to namespace and all assets within
        required:
        - catalog_id
        - namespace
        - type
        properties:
          catalog_id:
            type: string
            format: uuid
          namespace:
            type: string
          type:
            type: string
            enum:
            - namespace
      - type: object
        description: Applies to specific asset
        required:
        - catalog_id
        - namespace
        - asset_id
        - type
        properties:
          asset_id:
            type: string
            format: uuid
          catalog_id:
            type: string
            format: uuid
          namespace:
            type: string
          type:
            type: string
            enum:
            - asset
      - type: object
        description: Applies to all assets with specific tag
        required:
        - tag_name
        - type
        properties:
          tag_name:
            type: string
          type:
            type: string
            enum:
            - tag
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - tenant
      description: Permission scope - where the permission applies
      discriminator:
        propertyName: type
    PresignParams:
      type: object
      required:
      - location
      properties:
        location:
          type: string
    PresignResponse:
      type: object
      required:
      - url
      properties:
        url:
          type: string
    RegisterAssetRequest:
      type: object
      required:
      - name
      - kind
      - location
      properties:
        kind:
          $ref: '#/components/schemas/AssetType'
        location:
          type: string
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
    RegisterAssetResponse:
      type: object
      required:
      - id
      - name
      - kind
      - location
      properties:
        id:
          type: string
        kind:
          $ref: '#/components/schemas/AssetType'
        location:
          type: string
        name:
          type: string
    RenameTableRequest:
      type: object
      required:
      - source
      - destination
      properties:
        destination:
          $ref: '#/components/schemas/TableIdentifier'
        source:
          $ref: '#/components/schemas/TableIdentifier'
    RequestStatus:
      type: string
      description: Status of an access request
      enum:
      - pending
      - approved
      - rejected
    ResolutionStrategy:
      type: string
      enum:
      - AutoMerge
      - TakeSource
      - TakeTarget
      - Manual
      - ThreeWayMerge
    ResolveConflictRequest:
      type: object
      required:
      - strategy
      properties:
        resolved_value:
          nullable: true
        strategy:
          $ref: '#/components/schemas/ResolutionStrategy'
    ResourceType:
      type: string
      description: Types of resources that can be operated on
      enum:
      - catalog
      - namespace
      - table
      - view
      - branch
      - tag
      - user
      - service_user
      - permission
      - role
      - federated_catalog
      - warehouse
      - tenant
      - merge_operation
      - conflict
      - access_request
      - metadata
      - token
      - commit
    RevokeTokenRequest:
      type: object
      properties:
        reason:
          type: string
          nullable: true
    RevokeTokenResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
    Role:
      type: object
      description: A role that groups permissions
      required:
      - id
      - name
      - tenant-id
      - permissions
      - created-by
      - created-at
      - updated-at
      properties:
        created-at:
          type: string
          format: date-time
        created-by:
          type: string
          format: uuid
        description:
          type: string
          nullable: true
        id:
          type: string
          format: uuid
        name:
          type: string
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/PermissionGrant'
        tenant-id:
          type: string
          format: uuid
        updated-at:
          type: string
          format: date-time
    Schema:
      type: object
      required:
      - schema-id
      - fields
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/NestedField'
        identifier-field-ids:
          type: array
          items:
            type: integer
            format: int32
          nullable: true
        schema-id:
          type: integer
          format: int32
    SearchQuery:
      type: object
      required:
      - q
      properties:
        catalog:
          type: string
          description: Optional catalog name to filter results
          nullable: true
        limit:
          type: integer
          description: Maximum number of results to return
          minimum: 0
        offset:
          type: integer
          description: Offset for pagination
          minimum: 0
        q:
          type: string
          description: Search query string
    SearchRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
        tags:
          type: array
          items:
            type: string
          nullable: true
    SearchResponse:
      type: object
      required:
      - results
      - total
      - limit
      - offset
      properties:
        limit:
          type: integer
          minimum: 0
        offset:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/AssetSearchResult'
        total:
          type: integer
          minimum: 0
    SearchResultType:
      type: string
      enum:
      - Asset
      - Catalog
      - Namespace
      - Branch
    ServiceUser:
      type: object
      description: Service user for API key authentication
      required:
      - id
      - name
      - tenant-id
      - api-key-hash
      - role
      - created-at
      - created-by
      - active
      properties:
        active:
          type: boolean
        api-key-hash:
          type: string
        created-at:
          type: string
          format: date-time
        created-by:
          type: string
          format: uuid
        description:
          type: string
          nullable: true
        expires-at:
          type: string
          format: date-time
          nullable: true
        id:
          type: string
          format: uuid
        last-used:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
        role:
          $ref: '#/components/schemas/UserRole'
        tenant-id:
          type: string
          format: uuid
    Snapshot:
      type: object
      required:
      - snapshot-id
      - sequence-number
      - timestamp-ms
      - manifest-list
      - summary
      properties:
        manifest-list:
          type: string
        parent-snapshot-id:
          type: integer
          format: int64
          nullable: true
        schema-id:
          type: integer
          format: int32
          nullable: true
        sequence-number:
          type: integer
          format: int64
        snapshot-id:
          type: integer
          format: int64
        summary:
          type: object
          additionalProperties:
            type: string
        timestamp-ms:
          type: integer
          format: int64
    SnapshotLogEntry:
      type: object
      required:
      - timestamp-ms
      - snapshot-id
      properties:
        snapshot-id:
          type: integer
          format: int64
        timestamp-ms:
          type: integer
          format: int64
    SortField:
      type: object
      required:
      - source-id
      - transform
      - direction
      - null-order
      properties:
        direction:
          type: string
        null-order:
          type: string
        source-id:
          type: integer
          format: int32
        transform:
          type: string
    SortOrder:
      type: object
      required:
      - order-id
      - fields
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/SortField'
        order-id:
          type: integer
          format: int32
    StorageCredential:
      type: object
      required:
      - prefix
      - config
      properties:
        config:
          type: object
          additionalProperties:
            type: string
        prefix:
          type: string
    TableIdentifier:
      type: object
      required:
      - namespace
      - name
      properties:
        name:
          type: string
        namespace:
          type: array
          items:
            type: string
    TableMetadata:
      type: object
      required:
      - format-version
      - table-uuid
      - location
      - last-sequence-number
      - last-updated-ms
      - last-column-id
      - current-schema-id
      - schemas
      - current-partition-spec-id
      - partition-specs
      - default-sort-order-id
      - sort-orders
      properties:
        current-partition-spec-id:
          type: integer
          format: int32
        current-schema-id:
          type: integer
          format: int32
        current-snapshot-id:
          type: integer
          format: int64
          nullable: true
        default-sort-order-id:
          type: integer
          format: int32
        format-version:
          type: integer
          format: int32
        last-column-id:
          type: integer
          format: int32
        last-sequence-number:
          type: integer
          format: int64
        last-updated-ms:
          type: integer
          format: int64
        location:
          type: string
        metadata-log:
          type: array
          items:
            $ref: '#/components/schemas/MetadataLogEntry'
          nullable: true
        partition-specs:
          type: array
          items:
            $ref: '#/components/schemas/PartitionSpec'
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
        schemas:
          type: array
          items:
            $ref: '#/components/schemas/Schema'
        snapshot-log:
          type: array
          items:
            $ref: '#/components/schemas/SnapshotLogEntry'
          nullable: true
        snapshots:
          type: array
          items:
            $ref: '#/components/schemas/Snapshot'
          nullable: true
        sort-orders:
          type: array
          items:
            $ref: '#/components/schemas/SortOrder'
        table-uuid:
          type: string
          format: uuid
    TableResponse:
      type: object
      required:
      - metadata
      properties:
        config:
          type: object
          additionalProperties:
            type: string
          nullable: true
        id:
          type: string
          format: uuid
          description: Internal Pangolin asset ID for linking to business metadata
          nullable: true
        metadata:
          $ref: '#/components/schemas/TableMetadata'
        metadata-location:
          type: string
          nullable: true
    Tenant:
      type: object
      required:
      - id
      - name
      - properties
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
    TenantResponse:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
    TenantUpdate:
      type: object
      properties:
        name:
          type: string
          nullable: true
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
    Type:
      oneOf:
      - type: string
      - type: object
        required:
        - type
        - fields
        properties:
          fields:
            type: array
            items:
              $ref: '#/components/schemas/NestedField'
          type:
            type: string
      - type: object
        required:
        - type
        - element_id
        - element_required
        - element
        properties:
          element:
            $ref: '#/components/schemas/Type'
          element_id:
            type: integer
            format: int32
          element_required:
            type: boolean
          type:
            type: string
      - type: object
        required:
        - type
        - key_id
        - key
        - value_id
        - value_required
        - value
        properties:
          key:
            $ref: '#/components/schemas/Type'
          key_id:
            type: integer
            format: int32
          type:
            type: string
          value:
            $ref: '#/components/schemas/Type'
          value_id:
            type: integer
            format: int32
          value_required:
            type: boolean
    UnifiedSearchQuery:
      type: object
      required:
      - q
      properties:
        limit:
          type: integer
          minimum: 0
        q:
          type: string
    UnifiedSearchResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/UnifiedSearchResult'
    UnifiedSearchResult:
      type: object
      required:
      - name
      - kind
      properties:
        context:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        id:
          type: string
          nullable: true
        kind:
          $ref: '#/components/schemas/SearchResultType'
        name:
          type: string
    UpdateCatalogRequest:
      type: object
      properties:
        federated_config:
          allOf:
          - $ref: '#/components/schemas/pangolin_core.model.FederatedCatalogConfig'
          nullable: true
        properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
        storage_location:
          type: string
          nullable: true
        warehouse_name:
          type: string
          nullable: true
    UpdateNamespacePropertiesRequest:
      type: object
      properties:
        removals:
          type: array
          items:
            type: string
          nullable: true
        updates:
          type: object
          additionalProperties:
            type: string
          nullable: true
    UpdateNamespacePropertiesResponse:
      type: object
      required:
      - updated
      - removed
      - missing
      properties:
        missing:
          type: array
          items:
            type: string
        removed:
          type: array
          items:
            type: string
        updated:
          type: array
          items:
            type: string
    UpdateRequestStatus:
      type: object
      required:
      - status
      properties:
        comment:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/RequestStatus'
    UpdateServiceUserRequest:
      type: object
      properties:
        active:
          type: boolean
          nullable: true
        description:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
    UpdateUserRequest:
      type: object
      description: Request to update a user
      properties:
        active:
          type: boolean
          nullable: true
        email:
          type: string
          nullable: true
        password:
          type: string
          nullable: true
    UpdateWarehouseRequest:
      type: object
      properties:
        name:
          type: string
          nullable: true
        storage_config:
          type: object
          additionalProperties:
            type: string
          nullable: true
        use_sts:
          type: boolean
          nullable: true
        vending_strategy:
          allOf:
          - $ref: '#/components/schemas/VendingStrategy'
          nullable: true
    User:
      type: object
      description: User in the system
      required:
      - id
      - username
      - email
      - role
      - created-at
      - updated-at
      - active
      properties:
        active:
          type: boolean
        created-at:
          type: string
          format: date-time
        email:
          type: string
        id:
          type: string
          format: uuid
        last-login:
          type: string
          format: date-time
          nullable: true
        oauth-provider:
          allOf:
          - $ref: '#/components/schemas/OAuthProvider'
          nullable: true
        oauth-subject:
          type: string
          description: OAuth subject ID from provider
          nullable: true
        password-hash:
          type: string
          description: Password hash (bcrypt) - None for OAuth users
          nullable: true
        role:
          $ref: '#/components/schemas/UserRole'
        tenant-id:
          type: string
          format: uuid
          description: None for root user, Some(tenant_id) for tenant users
          nullable: true
        updated-at:
          type: string
          format: date-time
        username:
          type: string
    UserInfo:
      type: object
      description: Public user information
      required:
      - id
      - username
      - email
      - role
      - created-at
      properties:
        created-at:
          type: string
          format: date-time
        email:
          type: string
        id:
          type: string
          format: uuid
        last-login:
          type: string
          format: date-time
          nullable: true
        oauth-provider:
          allOf:
          - $ref: '#/components/schemas/OAuthProvider'
          nullable: true
        role:
          $ref: '#/components/schemas/UserRole'
        tenant-id:
          type: string
          format: uuid
          nullable: true
        username:
          type: string
    UserRole:
      type: string
      description: User role in the system
      enum:
      - root
      - tenant-admin
      - tenant-user
    UserSession:
      type: object
      description: User session for JWT or OAuth
      required:
      - user_id
      - username
      - role
      - issued_at
      - expires_at
      properties:
        expires_at:
          type: string
          format: date-time
        issued_at:
          type: string
          format: date-time
        role:
          $ref: '#/components/schemas/UserRole'
        tenant_id:
          type: string
          format: uuid
          nullable: true
        user_id:
          type: string
          format: uuid
        username:
          type: string
    ValidateNamesRequest:
      type: object
      required:
      - resource_type
      - names
      properties:
        names:
          type: array
          items:
            type: string
          description: List of names to validate
        resource_type:
          type: string
          description: 'Resource type: "catalog" or "warehouse"'
    ValidateNamesResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/NameValidationResult'
    VendingStrategy:
      oneOf:
      - type: object
        required:
        - AwsSts
        properties:
          AwsSts:
            type: object
            description: AWS S3 with STS temporary credentials
            required:
            - role_arn
            properties:
              external_id:
                type: string
                nullable: true
              role_arn:
                type: string
      - type: object
        required:
        - AwsStatic
        properties:
          AwsStatic:
            type: object
            description: AWS S3 with static credentials
            required:
            - access_key_id
            - secret_access_key
            properties:
              access_key_id:
                type: string
              secret_access_key:
                type: string
      - type: object
        required:
        - AzureSas
        properties:
          AzureSas:
            type: object
            description: Azure Blob Storage with SAS tokens
            required:
            - account_name
            - account_key
            properties:
              account_key:
                type: string
              account_name:
                type: string
      - type: object
        required:
        - GcpDownscoped
        properties:
          GcpDownscoped:
            type: object
            description: GCP with downscoped credentials
            required:
            - service_account_email
            - private_key
            properties:
              private_key:
                type: string
              service_account_email:
                type: string
      - type: string
        description: No credential vending (client-provided only)
        enum:
        - None
    ViewResponse:
      type: object
      required:
      - name
      - sql
      - dialect
      - properties
      properties:
        dialect:
          type: string
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
        sql:
          type: string
    Warehouse:
      type: object
      required:
      - id
      - name
      - tenant_id
      - storage_config
      - use_sts
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        storage_config:
          type: object
          additionalProperties:
            type: string
        tenant_id:
          type: string
          format: uuid
        use_sts:
          type: boolean
        vending_strategy:
          allOf:
          - $ref: '#/components/schemas/VendingStrategy'
          nullable: true
    WarehouseResponse:
      type: object
      required:
      - id
      - name
      - tenant_id
      - use_sts
      - storage_config
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        storage_config:
          type: object
          additionalProperties:
            type: string
        tenant_id:
          type: string
          format: uuid
        use_sts:
          type: boolean
        vending_strategy:
          allOf:
          - $ref: '#/components/schemas/VendingStrategy'
          nullable: true
    WarehouseUpdate:
      type: object
      properties:
        name:
          type: string
          nullable: true
        storage_config:
          type: object
          additionalProperties:
            type: string
          nullable: true
        use_sts:
          type: boolean
          nullable: true
        vending_strategy:
          allOf:
          - $ref: '#/components/schemas/VendingStrategy'
          nullable: true
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /api/v1/users/login or /api/v1/tokens
tags:
- name: Tenants
  description: Tenant management endpoints
- name: Warehouses
  description: Warehouse management endpoints
- name: Catalogs
  description: Catalog management endpoints
- name: Users
  description: User management and authentication endpoints
- name: Tokens
  description: Token generation and revocation endpoints
- name: Roles & Permissions
  description: Role and permission management endpoints
- name: Federated Catalogs
  description: Federated catalog management endpoints
- name: Service Users
  description: Service user and API key management endpoints
- name: OAuth
  description: OAuth authentication endpoints
- name: Branches
  description: Branch management endpoints
- name: Tags
  description: Tag management endpoints
- name: Merge Operations
  description: Merge operation and conflict resolution endpoints
- name: Business Metadata
  description: Business metadata and asset discovery endpoints
- name: Audit Logging
  description: Audit log viewing and filtering endpoints
- name: System Config
  description: System configuration management endpoints
- name: Iceberg REST
  description: Iceberg REST Catalog endpoints
- name: Assets
  description: Generic asset registration and management
- name: Data Explorer
  description: Data exploration and discovery endpoints
- name: Dashboard
  description: Dashboard statistics and summaries
- name: Search
  description: Asset search and discovery
- name: Bulk Operations
  description: Bulk operations for efficiency
- name: Validation
  description: Resource name validation