openapi: 3.0.3
info:
  title: LakeSail API
  x-logo:
    url: data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMTM2IDMyIiB3aWR0aD0iMTM2IiBoZWlnaHQ9IjMyIiBmaWxsPSIjMzc2MkUwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxwYXRoIGQ9Ik00MS44MDE5IDIyLjI2NzRWNi44ODM1SDM4LjIwMTlWMjUuNDY2OEg1MC4zMjczVjIyLjI2NzRINDEuODAxOVoiLz4KICA8cGF0aCBkPSJNNjEuMjM1OCAxMi42OTc5VjEzLjkwNEM2MC44ODE4IDEzLjUzOCA2MC40NjggMTMuMjMxNSA1OS45OTIzIDEyLjk4OUM1OS4yNjg4IDEyLjYxODUgNTguNDU2NyAxMi40MzMzIDU3LjU1NjIgMTIuNDMzM0M1Ni4zNzI0IDEyLjQzMzMgNTUuMzE5MSAxMi43MjQ0IDU0LjM5MiAxMy4zMDY1QzUzLjQ2NDkgMTMuODg4NiA1Mi43MzcgMTQuNjgwMiA1Mi4yMDgxIDE1LjY4NTZDNTEuNjc5MyAxNi42OTExIDUxLjQxMzggMTcuODI2NiA1MS40MTM4IDE5LjA5NjdDNTEuNDEzOCAyMC4zNjY3IDUxLjY3OTMgMjEuNDc1OCA1Mi4yMDgxIDIyLjQ4MTNDNTIuNzM3IDIzLjQ4NjcgNTMuNDY0OSAyNC4yNzgzIDU0LjM5MiAyNC44NjA0QzU1LjMxOTEgMjUuNDQyNSA1Ni4zNjM1IDI1LjczMzUgNTcuNTI5NiAyNS43MzM1QzU4LjQ0NzkgMjUuNzMzNSA1OS4yNzMyIDI1LjU0ODMgNjAuMDA1NiAyNS4xNzc5QzYwLjQ3OTEgMjQuOTM5OCA2MC44ODg1IDI0LjYzNzcgNjEuMjM1OCAyNC4yNzYxVjI1LjQ2NjdINjQuNzI5N1YxMi42OTc5SDYxLjIzNThaTTYwLjU0NTUgMjEuNTUzQzU5Ljk0NTkgMjIuMjA1NiA1OS4xNjA0IDIyLjUzMiA1OC4xODkgMjIuNTMyQzU3LjU3MTcgMjIuNTMyIDU3LjAxNDEgMjIuMzgyIDU2LjUyMDYgMjIuMDgyMkM1Ni4wMjcyIDIxLjc4MjMgNTUuNjQyMiAyMS4zNzY2IDU1LjM2NzggMjAuODY1QzU1LjA5MzUgMjAuMzUzNSA1NC45NTg1IDE5Ljc1MzcgNTQuOTU4NSAxOS4wNjhDNTQuOTU4NSAxOC4zODIzIDU1LjA5NTcgMTcuODA5IDU1LjM2NzggMTcuMjk3NEM1NS42NDIyIDE2Ljc4NTkgNTYuMDIwNiAxNi4zODI0IDU2LjUwNzQgMTYuMDgyNUM1Ni45OTE5IDE1Ljc4MjYgNTcuNTUzOSAxNS42MzI3IDU4LjE4OSAxNS42MzI3QzU4LjgyNCAxNS42MzI3IDU5LjQwNiAxNS43NzgyIDU5Ljg4MzkgMTYuMDY5M0M2MC4zNjE4IDE2LjM2MDMgNjAuNzQwMiAxNi43NzA0IDYxLjAyMzQgMTcuMjk3NEM2MS4zMDY2IDE3LjgyNjYgNjEuNDQ2IDE4LjQyNjQgNjEuNDQ2IDE5LjA5NDVDNjEuNDQ2IDIwLjA4MjMgNjEuMTQ1MSAyMC45MDAzIDYwLjU0NTUgMjEuNTUzWiIvPgogIDxwYXRoIGQ9Ik04MC4xMTIyIDI1LjQ2NjdMNzQuODUwNCAxOC43NzAzTDc5Ljg3MzIgMTIuNjk3OUg3NS44NDg0TDcxLjIxNSAxOC41NDk4VjYuMzU0MjhINjcuNzQ3OFYyNS40NjY3SDcxLjIxNVYxOS4yMzc4TDc1Ljg3NDkgMjUuNDY2N0g4MC4xMTIyWiIvPgogIDxwYXRoIGQ9Ik05Mi41MDMyIDE1LjUwMDRDOTEuOTc0NCAxNC41MzI1IDkxLjIzMzEgMTMuNzc0IDkwLjI3OTUgMTMuMjI3MUM4OS4zMjU4IDEyLjY4MDMgODguMjUwNCAxMi40MDY5IDg3LjA0ODkgMTIuNDA2OUM4NS43Nzg5IDEyLjQwNjkgODQuNjMwNSAxMi42OTc5IDgzLjYwODIgMTMuMjgwMUM4Mi41ODM4IDEzLjg2MjIgODEuNzc2MSAxNC42NTM3IDgxLjE4NTMgMTUuNjU5MkM4MC41OTQ2IDE2LjY2NDYgODAuMjk4MSAxNy44MDAyIDgwLjI5ODEgMTkuMDcwMkM4MC4yOTgxIDIwLjM0MDMgODAuNTk2OCAyMS41MDIzIDgxLjE5ODYgMjIuNTA3N0M4MS43OTgzIDIzLjUxMzIgODIuNjIzNiAyNC4zMDQ4IDgzLjY3NDYgMjQuODg2OUM4NC43MjU2IDI1LjQ2OSA4NS45MjA1IDI1Ljc2IDg3LjI2MTQgMjUuNzZDODguMzAzNSAyNS43NiA4OS4yNjM4IDI1LjU3NDggOTAuMTQ2NyAyNS4yMDQ0QzkxLjAyOTUgMjQuODM0IDkxLjc5NzMgMjQuMjc4MyA5Mi40NTAxIDIzLjUzOTdMOTAuMzg1NyAyMS40NzhDODkuOTk2MiAyMS45MzY3IDg5LjUzODIgMjIuMjcxOCA4OS4wMDk0IDIyLjQ4MzVDODguNDgwNSAyMi42OTUyIDg3Ljg4NzYgMjIuODAxIDg3LjIzNDggMjIuODAxQzg2LjUxMTMgMjIuODAxIDg1Ljg3NjIgMjIuNjUxMSA4NS4zMjc1IDIyLjM1MTJDODQuNzgxIDIyLjA1MTMgODQuMzYwNSAyMS42MTQ3IDg0LjA3MDcgMjEuMDQzN0M4My45NTU2IDIwLjgxNjUgODMuODYyNyAyMC41NzE4IDgzLjc5NDEgMjAuMzEzOEw5My4xMzgyIDIwLjI5MThDOTMuMjA5IDIwLjAwOTUgOTMuMjUzMyAxOS43NDk0IDkzLjI3MSAxOS41MTEyQzkzLjI4ODcgMTkuMjczMSA5My4yOTc1IDE5LjAzOTQgOTMuMjk3NSAxOC44MUM5My4yOTc1IDE3LjU3NzUgOTMuMDMyIDE2LjQ3NSA5Mi41MDMyIDE1LjUwNDhWMTUuNTAwNFpNODUuMjIxMyAxNS43NjVDODUuNzMyNCAxNS40NjUxIDg2LjMzMiAxNS4zMTUyIDg3LjAyMjQgMTUuMzE1MkM4Ny42NzUxIDE1LjMxNTIgODguMjIxNyAxNS40NDc1IDg4LjY2NDIgMTUuNzEyMUM4OS4xMDQ1IDE1Ljk3NjcgODkuNDQ5NyAxNi4zNjQ4IDg5LjY5NzUgMTYuODc2M0M4OS44MTcgMTcuMTIzMyA4OS45MDc3IDE3LjM5NjcgODkuOTc0MSAxNy43MDFMODMuNzk0MSAxNy43MTg2QzgzLjg1ODMgMTcuNDgwNSA4My45NDIzIDE3LjI1NzggODQuMDQ0MSAxNy4wNDgzQzg0LjMxODUgMTYuNDkyNyA4NC43MTAxIDE2LjA2NzEgODUuMjIxMyAxNS43NjcyVjE1Ljc2NVoiLz4KICA8cGF0aCBkPSJNMTAxLjIxMiAyNS43NTc4Qzk5LjcyOTggMjUuNzU3OCA5OC40NTMxIDI1LjUwMiA5Ny4zODY2IDI0Ljk5MDVDOTYuMzE3OSAyNC40Nzg5IDk1LjM1MzEgMjMuNzA1IDk0LjQ4OCAyMi42NjQzTDk2Ljg3MSAyMC4yODUxQzk3LjQzNTMgMjEuMDA4MyA5OC4wNzQ3IDIxLjU2NjIgOTguNzg5NCAyMS45NjMxQzk5LjUwNDEgMjIuMzYgMTAwLjM4MyAyMi41NTg0IDEwMS40MjUgMjIuNTU4NEMxMDIuMzYxIDIyLjU1ODQgMTAzLjEwMiAyMi4zNzMyIDEwMy42NDggMjIuMDAyOEMxMDQuMTk1IDIxLjYzMjQgMTA0LjQ2OSAyMS4xMjA4IDEwNC40NjkgMjAuNDcwM0MxMDQuNDY5IDE5LjkwNTkgMTA0LjMxIDE5LjQ0OTUgMTAzLjk5NCAxOS4wOTY3QzEwMy42NzUgMTguNzQzOSAxMDMuMjU3IDE4LjQ0ODQgMTAyLjczNyAxOC4yMTAzQzEwMi4yMTcgMTcuOTcyMSAxMDEuNjQyIDE3Ljc1MTYgMTAxLjAxNSAxNy41NDg4QzEwMC4zODkgMTcuMzQ1OSA5OS43Njc0IDE3LjExMjIgOTkuMTQ3OSAxNi44NDc2Qzk4LjUzMDUgMTYuNTgzIDk3Ljk1NzUgMTYuMjQ3OSA5Ny40MjY0IDE1Ljg0MjJDOTYuODk3NiAxNS40MzY1IDk2LjQ3NzIgMTQuOTI0OSA5Ni4xNjk2IDE0LjMwOTdDOTUuODU5OCAxMy42OTIzIDk1LjcwNzIgMTIuOTAwOCA5NS43MDcyIDExLjkzMDZDOTUuNzA3MiAxMC44MDM5IDk1Ljk4MTUgOS44NDI1MiA5Ni41MjgxIDkuMDQ4NzRDOTcuMDc0NiA4LjI1NDk2IDk3LjgyNDcgNy42NDg2IDk4Ljc3ODQgNy4yMjUyNUM5OS43MzIgNi44MDE5IDEwMC44MDcgNi41OTAyMyAxMDIuMDA5IDYuNTkwMjNDMTAzLjI3OSA2LjU5MDIzIDEwNC40MzIgNi44MjgzNiAxMDUuNDY1IDcuMzA0NjNDMTA2LjQ5OCA3Ljc4MDkgMTA3LjMzMyA4LjM5ODI4IDEwNy45NjggOS4xNTQ1OEwxMDUuNTg1IDExLjUzMzdDMTA1LjAzOCAxMC45MzQgMTA0LjQ3NiAxMC40OTMgMTAzLjkwMyAxMC4yMTI5QzEwMy4zMyA5LjkzMDcyIDEwMi42ODIgOS43ODk2IDEwMS45NTYgOS43ODk2QzEwMS4xMjYgOS43ODk2IDEwMC40NzMgOS45NTI3NyA5OS45OTc1IDEwLjI3OTFDOTkuNTIxOCAxMC42MDU0IDk5LjI4MjggMTEuMDU5NiA5OS4yODI0IDExLjYzOTVDOTkuMjgyOCAxMi4xNTExIDk5LjQ0MjIgMTIuNTYxMiA5OS43NTg2IDEyLjg2NzdDMTAwLjA3NyAxMy4xNzY0IDEwMC40OTUgMTMuNDQ5OCAxMDEuMDE1IDEzLjY4NzlDMTAxLjUzNSAxMy45MjYxIDEwMi4xMTUgMTQuMTUxIDEwMi43NSAxNC4zNjI3QzEwMy4zODUgMTQuNTc0MyAxMDQuMDExIDE0LjgxNjkgMTA0LjYzMSAxNS4wOTAzQzEwNS4yNDggMTUuMzYzNyAxMDUuODE3IDE1LjcwNzcgMTA2LjMzOSAxNi4xMjIyQzEwNi44NTkgMTYuNTM2NyAxMDcuMjc5IDE3LjA3NDcgMTA3LjU5NiAxNy43MzRDMTA3LjkxNCAxOC4zOTU1IDEwOC4wNzIgMTkuMjExMyAxMDguMDcyIDIwLjE3OTNDMTA4LjA3MiAyMS45MDU4IDEwNy40NjMgMjMuMjY4NCAxMDYuMjQ0IDI0LjI2MjhDMTA1LjAyNyAyNS4yNTk1IDEwMy4zNSAyNS43NTU2IDEwMS4yMTUgMjUuNzU1NkwxMDEuMjEyIDI1Ljc1NzhaIi8+CiAgPHBhdGggZD0iTTExOS40NTQgMTIuNjk3OVYxMy45MDRDMTE5LjEgMTMuNTM4IDExOC42ODYgMTMuMjMxNSAxMTguMjEgMTIuOTg5QzExNy40ODcgMTIuNjE4NSAxMTYuNjc0IDEyLjQzMzMgMTE1Ljc3NCAxMi40MzMzQzExNC41OSAxMi40MzMzIDExMy41MzcgMTIuNzI0NCAxMTIuNjEgMTMuMzA2NUMxMTEuNjgzIDEzLjg4ODYgMTEwLjk1NSAxNC42ODAyIDExMC40MjYgMTUuNjg1NkMxMDkuODk3IDE2LjY5MTEgMTA5LjYzMiAxNy44MjY2IDEwOS42MzIgMTkuMDk2N0MxMDkuNjMyIDIwLjM2NjcgMTA5Ljg5NyAyMS40NzU4IDExMC40MjYgMjIuNDgxM0MxMTAuOTU1IDIzLjQ4NjcgMTExLjY4MyAyNC4yNzgzIDExMi42MSAyNC44NjA0QzExMy41MzcgMjUuNDQyNSAxMTQuNTgxIDI1LjczMzUgMTE1Ljc0NyAyNS43MzM1QzExNi42NjYgMjUuNzMzNSAxMTcuNDkxIDI1LjU0ODMgMTE4LjIyMyAyNS4xNzc5QzExOC42OTcgMjQuOTM5OCAxMTkuMTA2IDI0LjYzNzcgMTE5LjQ1NCAyNC4yNzYxVjI1LjQ2NjdIMTIyLjk0N1YxMi42OTc5SDExOS40NTRaTTExOC43NjUgMjEuNTUzQzExOC4xNjYgMjIuMjA1NiAxMTcuMzggMjIuNTMyIDExNi40MDkgMjIuNTMyQzExNS43OTIgMjIuNTMyIDExNS4yMzQgMjIuMzgyIDExNC43NDEgMjIuMDgyMkMxMTQuMjQ3IDIxLjc4MjMgMTEzLjg2MiAyMS4zNzY2IDExMy41OSAyMC44NjVDMTEzLjMxNiAyMC4zNTM1IDExMy4xODEgMTkuNzUzNyAxMTMuMTgxIDE5LjA2OEMxMTMuMTgxIDE4LjM4MjMgMTEzLjMxOCAxNy44MDkgMTEzLjU5IDE3LjI5NzRDMTEzLjg2NCAxNi43ODU5IDExNC4yNDMgMTYuMzgyNCAxMTQuNzMgMTYuMDgyNUMxMTUuMjE0IDE1Ljc4MjYgMTE1Ljc3NiAxNS42MzI3IDExNi40MTEgMTUuNjMyN0MxMTcuMDQ2IDE1LjYzMjcgMTE3LjYyOCAxNS43NzgyIDExOC4xMDYgMTYuMDY5M0MxMTguNTg0IDE2LjM2MDMgMTE4Ljk2MiAxNi43NzA0IDExOS4yNDYgMTcuMjk3NEMxMTkuNTI5IDE3LjgyNjYgMTE5LjY2OCAxOC40MjY0IDExOS42NjggMTkuMDk0NUMxMTkuNjY4IDIwLjA4MjMgMTE5LjM2NyAyMC45MDAzIDExOC43NjggMjEuNTUzSDExOC43NjVaIi8+CiAgPHBhdGggZD0iTTEyOS40NjIgMTIuNjk3OUgxMjUuOTQxVjI1LjQ2NjdIMTI5LjQ2MlYxMi42OTc5WiIvPgogIDxwYXRoIGQ9Ik0xMjcuNzE2IDEwLjYzNjNDMTI4LjI5OCAxMC42MzYzIDEyOC43NzEgMTAuNDQ2NyAxMjkuMTMyIDEwLjA2NzRDMTI5LjQ5MyA5LjY4ODIgMTI5LjY3NCA5LjIxNjM0IDEyOS42NzQgOC42NTQwOEMxMjkuNjc0IDguMDkxODIgMTI5LjQ5MyA3LjYzOTgxIDEyOS4xMzIgNy4yNTM5NEMxMjguNzY5IDYuODY1ODcgMTI4LjI5OCA2LjY3MTg0IDEyNy43MTYgNi42NzE4NEMxMjcuMTM0IDYuNjcxODQgMTI2LjY4MiA2Ljg2NTg3IDEyNi4zMTMgNy4yNTM5NEMxMjUuOTQzIDcuNjQyMDEgMTI1Ljc1OCA4LjEwOTQ2IDEyNS43NTggOC42NTQwOEMxMjUuNzU4IDkuMTk4NyAxMjUuOTQzIDkuNjkwNCAxMjYuMzEzIDEwLjA2NzRDMTI2LjY4NSAxMC40NDY3IDEyNy4xNTEgMTAuNjM2MyAxMjcuNzE2IDEwLjYzNjNaIi8+CiAgPHBhdGggZD0iTTEzMi41MzMgMjUuNDY2N1Y2LjM1NDI4SDEzNlYyNS40NjY3SDEzMi41MzNaIi8+CiAgPHBhdGggZD0iTTE3Ljc5ODggMEw2LjM2ODA5IDIyLjQwMjlIMTcuNzk4OFYwWiIvPgogIDxwYXRoIGQ9Ik0yOC42NDk3IDI4LjgxMTNMNi4zNjgwOSAzMkwwIDI1LjYyNDhMMjkuOTI0MiAyNS42ODQ2TDI4LjY0OTcgMjguODExM1oiLz4KICA8cGF0aCBkPSJNMjEuMzI4IDYuNDE3MjhWMjIuNDAyOUgzMS44MzZDMjEuNzUyOCAxNS43OTk1IDIxLjMyOCA2LjQxNzI4IDIxLjMyOCA2LjQxNzI4WiIvPgo8L3N2Zz4=
    altText: LakeSail
  description: |
    The LakeSail platform API.

    **Beta Notice:** This API is currently in beta. All endpoints, request/response
    schemas, and authentication flows are subject to change.

    ## Getting Started

    ### Base URL

    All API requests are made to:

        https://platform.lakesail.com/api/v1

    All requests and responses use `application/json`.

    ### Authentication

    Most endpoints require a Bearer token in the `Authorization` header:

        Authorization: Bearer <token>

    Both user sessions and service account API keys are passed as Bearer tokens.
  license:
    name: LakeSail API License
  version: 0.3.0
  contact:
    name: LakeSail API Support
    url: https://lakesail.com
    email: hello@lakesail.com
servers:
  - url: https://platform.lakesail.com/{apiBase}/{apiVersion}
    variables:
      apiBase:
        default: api
        description: Base path for OpenAPI spec
      apiVersion:
        default: v1
        description: Current version of OpenAPI spec
security:
  - BearerAuth: []
tags:
  - name: authentication
    x-displayName: Authentication
    description: Account signup, login (password, SSO, one-time code), password reset, email verification, and logout.
  - name: identity-providers
    x-displayName: Identity Providers
    description: Configure external identity providers for single sign-on and list available provider types.
  - name: mfa
    x-displayName: MFA
    description: Multi-factor authentication enrollment, TOTP verification, and recovery codes.
  - name: authorization-policies
    x-displayName: Authorization Policies
    description: Fine-grained access control policies for users, teams, and service accounts.
  - name: invitations
    x-displayName: Invitations
    description: Invite users to join the organization.
  - name: members
    x-displayName: Members
    description: Organization membership, role assignment, and member search.
  - name: roles
    x-displayName: Roles
    description: Organization and team role definitions.
  - name: teams
    x-displayName: Teams
    description: Team management, membership, and team-level role assignment.
  - name: users
    x-displayName: Users
    description: User account management and self-service profile operations.
  - name: clusters
    x-displayName: Clusters
    description: Kubernetes cluster management, both self-registered and provisioned into cloud accounts.
  - name: connections
    x-displayName: Accounts
    description: Cloud account connections, CloudFormation template management, and resource discovery.
  - name: networks
    x-displayName: Networks
    description: Cloud network provisioning and lifecycle management.
  - name: catalogs
    x-displayName: Catalogs
    description: Data catalog management, both configured in LakeSail and provisioned into cloud accounts.
  - name: job-runs
    x-displayName: Job Runs
    description: Job run execution, monitoring, and lifecycle.
  - name: jobs
    x-displayName: Jobs
    description: Job definitions, versioning, drafts, and team assignment.
  - name: queries
    x-displayName: Queries
    description: Reusable SQL query definitions and team assignment.
  - name: sessions
    x-displayName: Sessions
    description: Interactive compute sessions, lifecycle management, and token issuance.
  - name: notifications
    x-displayName: Notifications
    description: Notification channels, delivery rules, event types, and notification history.
  - name: operations
    x-displayName: Operations
    description: Long-running operation status tracking.
paths:
  /auth/permissions:
    get:
      operationId: ListPermissions
      summary: List available permissions
      description: Returns all available permission definitions, including their descriptions and applicable resource types.
      tags:
        - authentication
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ListPermissionsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /auth/identity-provider-types:
    get:
      operationId: ListIdentityProviderTypes
      summary: List available identity provider types
      description: Returns a list of identity provider types that organizations can configure. Only enabled and visible providers are returned.
      tags:
        - identity-providers
      security:
        - BearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/ListIdentityProviderTypesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /auth/idps:
    get:
      operationId: ListIdentityProviders
      summary: List identity providers
      description: Returns a paginated list of all identity providers configured for the organization, including their type, status, and issuer information.
      tags:
        - identity-providers
      security:
        - Organization: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListIdentityProvidersResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateIdentityProvider
      summary: Create an identity provider
      description: Configures a new external identity provider (e.g. Okta, Azure AD, Google Workspace) for single sign-on. Users can then authenticate through this provider to access the organization.
      tags:
        - identity-providers
      requestBody:
        $ref: '#/components/requestBodies/CreateIdentityProviderRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateIdentityProviderResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /auth/idps/auto-setup:
    post:
      operationId: AutoSetupIdentityProvider
      summary: Auto-setup identity provider
      description: |
        Discovers the OIDC configuration from the provider's base URL and automatically
        registers LakeSail as an OAuth client using Dynamic Client Registration (RFC 7591).

        The provider URL must be a fully-qualified URL including the scheme (http:// or https://).

        Note: Not all identity providers support Dynamic Client Registration. The endpoint
        will return an error if the provider does not support it.
      tags:
        - identity-providers
      requestBody:
        $ref: '#/components/requestBodies/AutoSetupIdentityProviderRequest'
      responses:
        '201':
          $ref: '#/components/responses/AutoSetupIdentityProviderResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /auth/idps/{idp}:
    parameters:
      - $ref: '#/components/parameters/IdentityProviderId'
    get:
      operationId: DescribeIdentityProvider
      summary: Describe an identity provider
      description: Returns the configuration details of an identity provider, including its type, issuer URL, and client settings.
      tags:
        - identity-providers
      security:
        - Organization: []
      responses:
        '200':
          $ref: '#/components/responses/DescribeIdentityProviderResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateIdentityProvider
      summary: Update an identity provider
      description: Modifies an identity provider's configuration, such as its display name, issuer URL, or client settings. Changes take effect for subsequent sign-in attempts.
      tags:
        - identity-providers
      requestBody:
        $ref: '#/components/requestBodies/UpdateIdentityProviderRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateIdentityProviderResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteIdentityProvider
      summary: Delete an identity provider
      description: Removes an identity provider configuration. Users who authenticated exclusively through this provider will need an alternative sign-in method.
      tags:
        - identity-providers
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /auth/idps/{idp}/rotate-secret:
    parameters:
      - $ref: '#/components/parameters/IdentityProviderId'
    post:
      operationId: RotateIdentityProviderSecret
      summary: Rotate an identity provider's client secret
      description: |
        Updates the client secret for an identity provider. The new secret must be obtained 
        from the identity provider's admin console first.
      tags:
        - identity-providers
      requestBody:
        $ref: '#/components/requestBodies/RotateSecretRequest'
      responses:
        '200':
          $ref: '#/components/responses/RotateSecretResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /auth/idps/{idp}/test-connection:
    parameters:
      - $ref: '#/components/parameters/IdentityProviderId'
    post:
      operationId: TestIdentityProviderConnection
      summary: Test an identity provider connection
      description: |
        Validates the identity provider configuration by attempting to discover and fetch 
        the OIDC configuration from the provider's well-known endpoint.
      tags:
        - identity-providers
      responses:
        '200':
          $ref: '#/components/responses/TestConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me:
    get:
      operationId: DescribeCurrentIdentity
      summary: Get current user profile
      description: Returns the profile and organization membership details of the currently authenticated user.
      tags:
        - users
      responses:
        '200':
          $ref: '#/components/responses/DescribeCurrentIdentityResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateMyUser
      summary: Update my profile
      description: Modifies the authenticated user's profile information such as their display name or preferences.
      tags:
        - users
      requestBody:
        $ref: '#/components/requestBodies/UpdateMyUserRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateMyUserResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/catalogs:
    get:
      operationId: ListMyCatalogs
      summary: List my catalogs
      description: |
        Returns all catalogs that the current user can access based on their team memberships.
        Includes team associations and external catalog references in the normalized response.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/CatalogSortBy'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          $ref: '#/components/responses/ListMyCatalogsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/clusters:
    get:
      operationId: ListMyClusters
      summary: List my clusters
      description: Returns all Kubernetes clusters that the current user can access based on their team memberships.
      tags:
        - clusters
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/ClusterSortBy'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          $ref: '#/components/responses/ListMyClustersResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/clusters/{cluster}:
    parameters:
      - $ref: '#/components/parameters/ClusterId'
    get:
      operationId: DescribeMyCluster
      summary: Describe an accessible cluster
      description: |
        Returns a single Kubernetes cluster that the current user can access based on their team memberships.
        Returns 404 if the cluster does not exist or the user has no access.
      tags:
        - clusters
      responses:
        '200':
          $ref: '#/components/responses/DescribeMyClusterResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/emails:
    get:
      operationId: ListCurrentIdentityEmails
      summary: List my email addresses
      description: Returns all email addresses associated with the authenticated user's account, including their verification status.
      tags:
        - users
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListCurrentIdentityEmailsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: AddMyEmail
      summary: Add an email address
      description: Adds a new email address to the current user's account and sends a verification email.
      tags:
        - users
      requestBody:
        $ref: '#/components/requestBodies/AddMyEmailRequest'
      responses:
        '201':
          $ref: '#/components/responses/AddMyEmailResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '409':
          $ref: '#/components/responses/ErrorConflictResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/jobs:
    get:
      operationId: ListMyJobs
      summary: List my jobs
      description: |
        Returns all jobs that the current user can access based on their team memberships.
        Includes team associations and latest job run references in the normalized response.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/JobSortBy'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          $ref: '#/components/responses/ListMyJobsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/jobs/runs:
    get:
      operationId: ListMyJobRuns
      summary: List my job runs
      description: Returns all job runs that the authenticated user can access based on their team memberships and role permissions.
      tags:
        - job-runs
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListMyJobRunsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/mfa:
    delete:
      operationId: ResetMyMfa
      summary: Reset my MFA
      description: |
        Deletes all MFA configurations (TOTP and recovery codes) for the currently
        authenticated user and revokes all active sessions, requiring re-authentication.
      tags:
        - mfa
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/queries:
    get:
      operationId: ListMyQueries
      summary: List my queries
      description: |
        Returns all queries that the current user can access based on their team memberships.
        Includes team associations for each query in the normalized response.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/QuerySortBy'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          $ref: '#/components/responses/ListMyQueriesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/logins:
    get:
      operationId: ListMyLogins
      summary: List my logins
      description: Returns all active (non-expired) logins for the currently authenticated user, including device, IP address, and user agent information.
      tags:
        - users
      responses:
        '200':
          $ref: '#/components/responses/ListMyLoginsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/logins/{loginId}:
    parameters:
      - $ref: '#/components/parameters/LoginId'
    delete:
      operationId: RevokeMyLogin
      summary: Revoke a login
      description: Revokes a specific active login for the currently authenticated user. This immediately invalidates the login's access token.
      tags:
        - users
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/trusted-devices:
    get:
      operationId: ListMyTrustedDevices
      summary: List my trusted devices
      description: Returns all active (non-expired) trusted devices for the currently authenticated user. Trusted devices bypass two-factor authentication challenges.
      tags:
        - users
      responses:
        '200':
          $ref: '#/components/responses/ListMyTrustedDevicesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/trusted-devices/{trustedDeviceId}:
    parameters:
      - $ref: '#/components/parameters/TrustedDeviceId'
    delete:
      operationId: RevokeMyTrustedDevice
      summary: Revoke a trusted device
      description: Revokes a specific trusted device for the currently authenticated user. Future logins from this device will require two-factor authentication.
      tags:
        - users
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /me/teams:
    get:
      operationId: ListCurrentIdentityTeams
      summary: List my teams
      description: Returns all teams that the authenticated user is a member of, including their role within each team.
      tags:
        - users
      responses:
        '200':
          $ref: '#/components/responses/ListCurrentIdentityTeamsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/users:
    get:
      operationId: ListUsers
      summary: List users
      description: Returns a paginated list of all user accounts in the organization.
      tags:
        - users
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListUsersResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateUser
      summary: Create a user
      description: Creates a new user account in the platform with the specified profile information and credentials.
      tags:
        - users
      requestBody:
        $ref: '#/components/requestBodies/CreateUserRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateUserResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/users/{user}:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      operationId: DescribeUser
      summary: Describe a user
      description: Returns the full details of a user account, including their profile information and account status.
      tags:
        - users
      responses:
        '200':
          $ref: '#/components/responses/DescribeUserResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateUser
      summary: Update a user
      description: Modifies a user account's profile information or account settings.
      tags:
        - users
      requestBody:
        $ref: '#/components/requestBodies/UpdateUserRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateUserResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteUser
      summary: Delete a user
      description: Permanently removes a user account and revokes all their active sessions, organization memberships, and team assignments.
      tags:
        - users
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/users/{user}/mfa:
    parameters:
      - $ref: '#/components/parameters/UserId'
    delete:
      operationId: AdminResetMfa
      summary: Reset user MFA
      description: |
        Deletes all MFA configurations (TOTP and recovery codes) for the specified user
        and revokes all their active sessions. The user will be required to re-authenticate
        and set up MFA again.
      tags:
        - users
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/users/{user}/password:
    parameters:
      - $ref: '#/components/parameters/UserId'
    post:
      operationId: ChangePassword
      summary: Change user password
      description: |
        The current password must be provided in the request body.
        For organization administrators, to reset password for a user without their current password, use the [ResetPassword](./ResetPassword.html) operation instead.
      tags:
        - users
      requestBody:
        $ref: '#/components/requestBodies/ChangePasswordRequest'
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '422':
          $ref: '#/components/responses/ErrorUnprocessableEntityResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/users/{user}/password/reset:
    parameters:
      - $ref: '#/components/parameters/UserId'
    post:
      operationId: ResetPassword
      summary: Reset user password
      description: Admin operation that generates a new temporary password for a user. To change the current user's own password, use ChangePassword instead.
      tags:
        - users
      responses:
        '200':
          $ref: '#/components/responses/ResetPasswordResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/teams:
    get:
      operationId: ListTeams
      summary: List teams
      description: Returns all teams within the organization, including their member counts and descriptions.
      tags:
        - teams
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/SortBy'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          $ref: '#/components/responses/ListTeamsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateTeam
      summary: Create a team
      description: Creates a new team within the organization. Teams are used to group members and control access to clusters, jobs, and queries.
      tags:
        - teams
      requestBody:
        $ref: '#/components/requestBodies/CreateTeamRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateTeamResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/teams/{team}:
    parameters:
      - $ref: '#/components/parameters/TeamId'
    get:
      operationId: DescribeTeam
      summary: Describe a team
      description: Returns the full details of a team, including its name, description, and member count.
      tags:
        - teams
      responses:
        '200':
          $ref: '#/components/responses/DescribeTeamResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateTeam
      summary: Update a team
      description: Modifies a team's metadata such as its name or description.
      tags:
        - teams
      requestBody:
        $ref: '#/components/requestBodies/UpdateTeamRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateTeamResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteTeam
      summary: Delete a team
      description: Permanently removes a team and all its member assignments. Resources previously shared with this team become inaccessible to its former members unless they have access through another team.
      tags:
        - teams
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/teams/{team}/members:
    parameters:
      - $ref: '#/components/parameters/TeamId'
    get:
      operationId: ListTeamMembers
      summary: List team members
      description: Returns all members of a team, including their assigned team roles.
      tags:
        - teams
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/SortBy'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          $ref: '#/components/responses/ListTeamMembersResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/teams/{team}/members/{member}:
    parameters:
      - $ref: '#/components/parameters/TeamId'
      - $ref: '#/components/parameters/MemberId'
    post:
      operationId: AddTeamMember
      summary: Add a team member
      description: Adds an existing organization member to a team, granting them access to the team's associated resources (clusters, jobs, queries). If roleIds is omitted or empty, the team's configured default role is used.
      tags:
        - teams
      requestBody:
        $ref: '#/components/requestBodies/AddTeamMemberRequest'
      responses:
        '201':
          $ref: '#/components/responses/AddTeamMemberResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
        '422':
          $ref: '#/components/responses/ErrorUnprocessableEntityResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: RemoveTeamMember
      summary: Remove a team member
      description: Removes a member from a team. The member loses access to resources shared with this team unless they have access through another team.
      tags:
        - teams
      responses:
        '204':
          description: The member was removed from the team successfully.
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/teams/{team}/members/{member}/roles:
    parameters:
      - $ref: '#/components/parameters/TeamId'
      - $ref: '#/components/parameters/MemberId'
    put:
      operationId: UpdateTeamMemberRoles
      summary: Update team member roles
      description: |
        Syncs the team roles for a team member by replacing all existing roles with the provided list.
        At least one role must be provided; to remove a member from the team entirely use the
        remove-team-member endpoint instead.
        The member must be a member of the team before roles can be assigned.
      tags:
        - teams
      requestBody:
        $ref: '#/components/requestBodies/UpdateTeamMemberRolesRequest'
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/roles:
    get:
      operationId: ListOrganizationRoles
      summary: List organization roles
      description: Returns all roles available within the organization, including their names and descriptions. Organization roles define the permissions a member has at the organization level.
      tags:
        - roles
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/OrgRoleSortBy'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          $ref: '#/components/responses/ListOrganizationRolesResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/roles/{role}:
    get:
      operationId: DescribeOrganizationRole
      tags:
        - roles
      summary: Describe an organization role
      description: Retrieves detailed information about a specific organization role, including all assigned permissions and permission bundles.
      parameters:
        - $ref: '#/components/parameters/OrganizationRoleId'
      responses:
        '200':
          description: Organization role details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRoleNormalized'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/team-roles:
    get:
      operationId: ListTeamRoles
      summary: List team roles
      description: Returns all team roles within the organization that can be assigned to team members.
      tags:
        - roles
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/TeamRoleSortBy'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          $ref: '#/components/responses/ListTeamRolesResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/team-roles/{role}:
    get:
      operationId: DescribeTeamRole
      tags:
        - roles
      summary: Describe a team role
      description: Retrieves detailed information about a specific team role, including all assigned permissions and permission bundles.
      parameters:
        - $ref: '#/components/parameters/TeamRoleId'
      responses:
        '200':
          description: Team role details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamRoleNormalized'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/invites:
    post:
      operationId: CreateInvite
      summary: Create an invitation
      description: Sends an email invitation to a user to join the organization. If the user does not yet have an account, they will be guided through signup.
      tags:
        - invitations
      requestBody:
        $ref: '#/components/requestBodies/CreateInviteRequest'
      responses:
        '200':
          $ref: '#/components/responses/CreateInviteResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/invites/{token}:
    parameters:
      - $ref: '#/components/parameters/InvitationToken'
    get:
      operationId: DescribeInvite
      summary: Describe an invitation
      description: Returns the details of a pending invitation, including the invited email address, expiration time, and current status.
      tags:
        - invitations
      security: []
      responses:
        '200':
          $ref: '#/components/responses/DescribeInviteResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/invites/{token}/accept:
    parameters:
      - $ref: '#/components/parameters/InvitationToken'
    post:
      operationId: AcceptInvite
      summary: Accept an invitation
      description: Accepts a pending invitation, adding the authenticated user as a member of the organization.
      tags:
        - invitations
      security: []
      requestBody:
        $ref: '#/components/requestBodies/AcceptInviteRequest'
      responses:
        '200':
          $ref: '#/components/responses/AcceptInviteResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '422':
          $ref: '#/components/responses/ErrorUnprocessableEntityResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/members:
    get:
      operationId: SearchMembers
      summary: Search members
      description: Returns a filtered list of organization members matching the search criteria, including their profiles and role assignments.
      tags:
        - members
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/SortBy'
        - $ref: '#/components/parameters/SortDirection'
        - $ref: '#/components/parameters/MemberFilter'
      responses:
        '200':
          $ref: '#/components/responses/SearchMembersResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/members/{member}:
    parameters:
      - $ref: '#/components/parameters/MemberId'
    get:
      operationId: DescribeMember
      summary: Describe an organization member
      description: Returns the full details of an organization member, including their profile, assigned roles, and team memberships.
      tags:
        - members
      responses:
        '200':
          $ref: '#/components/responses/DescribeMemberResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateMember
      summary: Update a member
      description: Modifies an organization member's profile information such as their display name.
      tags:
        - members
      requestBody:
        $ref: '#/components/requestBodies/UpdateMemberRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateMemberResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: RemoveMember
      summary: Remove a member
      description: |
        Removes a user from the organization and revokes all their assigned roles and team memberships.
        The last Owner of the organization cannot be removed.
      tags:
        - members
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/members/{member}/roles:
    parameters:
      - $ref: '#/components/parameters/MemberId'
    put:
      operationId: UpdateMemberRoles
      summary: Update member roles
      description: |
        Replaces all organization roles for a member with the provided list.
        At least one role must be provided; to remove a member entirely use the
        remove-member endpoint instead.
        The last Owner of the organization cannot have their Owner role removed.
      tags:
        - members
      requestBody:
        $ref: '#/components/requestBodies/UpdateMemberRolesRequest'
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/policies:
    get:
      operationId: ListOrganizationPolicies
      summary: List organization policies
      description: Returns all access policies defined at the organization level, showing which principals have been granted specific permissions.
      tags:
        - authorization-policies
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListPoliciesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /org/policies/{principal}:
    parameters:
      - $ref: '#/components/parameters/Principal'
    get:
      operationId: DescribeOrganizationPolicy
      summary: Describe organization policy
      description: Returns the organization-level access policy for a specific principal, including all permissions that have been explicitly granted.
      tags:
        - authorization-policies
      responses:
        '200':
          $ref: '#/components/responses/DescribePolicyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: PutOrganizationPolicy
      summary: Set organization policy
      description: Sets the organization-level access policy for a principal, replacing any existing policy. Use this to grant or modify permissions for users or teams at the organization scope.
      tags:
        - authorization-policies
      requestBody:
        $ref: '#/components/requestBodies/PutPolicyRequest'
      responses:
        '200':
          $ref: '#/components/responses/PutExistingPolicyResponse'
        '201':
          $ref: '#/components/responses/PutNewPolicyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteOrganizationPolicy
      summary: Delete organization policy
      description: |
        This revokes all permissions that have been granted to the principal organization-wide,
        but the principal may still have permissions at the resource level.
      tags:
        - authorization-policies
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections:
    get:
      operationId: ListExternalConnections
      summary: List cloud accounts
      description: Returns a paginated list of cloud accounts configured for the organization.
      tags:
        - connections
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListExternalConnectionsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateExternalConnection
      summary: Create a cloud account
      description: Creates a new cloud account and returns the CloudFormation template information needed for deployment.
      tags:
        - connections
      requestBody:
        $ref: '#/components/requestBodies/CreateExternalConnectionRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateExternalConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    get:
      operationId: DescribeExternalConnection
      summary: Describe a cloud account
      description: Returns the details of a cloud account, including its provider, region, deployment status, and associated resources.
      tags:
        - connections
      responses:
        '200':
          $ref: '#/components/responses/DescribeExternalConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateExternalConnection
      summary: Update a cloud account
      description: Modifies a cloud account's metadata such as its name.
      tags:
        - connections
      requestBody:
        $ref: '#/components/requestBodies/UpdateExternalConnectionRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateExternalConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteExternalConnection
      summary: Delete a cloud account
      description: Permanently removes a cloud account. All associated clusters, networks, and catalogs must be destroyed before the connection can be deleted.
      tags:
        - connections
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/instance-types:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    get:
      operationId: ListExternalInstanceTypes
      summary: List available cloud instance types
      description: Returns EC2 instance types available in the cloud provider account for the specified connection. Supports filtering by region, architecture, CPU, and memory.
      tags:
        - connections
      parameters:
        - name: region
          in: query
          description: AWS region to list instance types for. If not provided, defaults to the connection's configured region.
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - name: architecture
          in: query
          description: Filter by architecture (x86_64 or arm64)
          schema:
            type: string
            enum:
              - x86_64
              - arm64
        - name: minVCpus
          in: query
          description: Minimum number of vCPUs
          schema:
            type: integer
            minimum: 1
        - name: minMemoryMiB
          in: query
          description: Minimum memory in MiB
          schema:
            type: integer
            minimum: 1024
      responses:
        '200':
          $ref: '#/components/responses/ListExternalInstanceTypesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/provider-networks:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    get:
      operationId: ListExternalNetworksForConnection
      summary: List available cloud provider networks
      description: Returns VPCs and subnets available in the cloud provider account for the specified connection and region.
      tags:
        - networks
      parameters:
        - name: region
          in: query
          description: AWS region to list networks for. If not provided, defaults to the connection's configured region.
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListExternalNetworksForConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/regions:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    get:
      operationId: ListExternalRegions
      summary: List available cloud provider regions
      description: Returns the cloud provider regions available for provisioning external clusters and networks.
      tags:
        - connections
      responses:
        '200':
          $ref: '#/components/responses/ListExternalRegionsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/sync-template:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    post:
      operationId: SyncExternalConnectionTemplate
      summary: Sync cloud account IaC template
      description: Updates the CloudFormation stack for this connection with the latest template. The update runs asynchronously. Only available for active connections with a deployed stack.
      tags:
        - connections
      responses:
        '202':
          $ref: '#/components/responses/SyncExternalConnectionTemplateResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/template:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    get:
      operationId: GetExternalConnectionTemplate
      summary: Get connection template
      description: Returns the CloudFormation template URL and parameters needed to deploy the connection stack in the cloud account.
      tags:
        - connections
      responses:
        '200':
          $ref: '#/components/responses/GetExternalConnectionTemplateResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/template/download:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    get:
      operationId: GetExternalConnectionTemplateDownload
      summary: Download connection template
      description: Downloads the CloudFormation template file with parameter defaults pre-filled, ready for upload to the AWS CloudFormation console. Use Get connection template for the URL and raw parameters instead.
      tags:
        - connections
      responses:
        '200':
          $ref: '#/components/responses/GetExternalConnectionTemplateDownloadResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/verify:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    post:
      operationId: VerifyExternalConnection
      summary: Verify a cloud account
      description: Validates that the cloud account is correctly configured. Call this after deploying the CloudFormation template.
      tags:
        - connections
      requestBody:
        $ref: '#/components/requestBodies/VerifyExternalConnectionRequest'
      responses:
        '200':
          $ref: '#/components/responses/VerifyExternalConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/networks:
    get:
      operationId: ListExternalNetworks
      summary: List cloud networks
      description: Returns all managed networks created through the API across all connections, supporting marker-based pagination.
      tags:
        - networks
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListExternalNetworksResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/networks/{network}:
    parameters:
      - $ref: '#/components/parameters/ExternalNetworkId'
    delete:
      operationId: DeleteExternalNetwork
      summary: Delete a cloud network record
      description: |
        Permanently deletes a cloud network record. The network's infrastructure must
        first be destroyed before the record can be deleted. A network in a failed state
        may still have active infrastructure and should be destroyed first.
      tags:
        - networks
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/networks:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    get:
      operationId: ListExternalNetworksByConnection
      summary: List cloud networks by connection
      description: Returns the managed networks provisioned through the specified connection.
      tags:
        - networks
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListExternalNetworksResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateExternalNetwork
      summary: Create a cloud network
      description: Creates a new network in the customer's cloud account via the specified connection. Requires an active connection.
      tags:
        - networks
      requestBody:
        $ref: '#/components/requestBodies/CreateExternalNetworkRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateExternalNetworkResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/networks/{network}:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
      - $ref: '#/components/parameters/ExternalNetworkId'
    get:
      operationId: DescribeExternalNetworkByConnection
      summary: Describe a cloud network
      description: Returns the details of a cloud network, including its VPC configuration, subnets, and provisioning status.
      tags:
        - networks
      responses:
        '200':
          $ref: '#/components/responses/DescribeExternalNetworkByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateExternalNetworkByConnection
      summary: Update a cloud network
      description: Modifies a cloud network's metadata such as its name.
      tags:
        - networks
      requestBody:
        $ref: '#/components/requestBodies/UpdateExternalNetworkByConnectionRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateExternalNetworkByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DestroyExternalNetworkByConnection
      summary: Destroy a cloud network
      description: Initiates destruction of an active cloud network and all associated networking resources. All clusters and catalogs in the network must be destroyed first. The network record is retained for reference. Returns an operation ID for tracking progress.
      tags:
        - networks
      responses:
        '202':
          $ref: '#/components/responses/DestroyExternalNetworkByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/networks/{network}/provision:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
      - $ref: '#/components/parameters/ExternalNetworkId'
    post:
      operationId: ProvisionExternalNetworkByConnection
      summary: Provision a cloud network
      description: Triggers provisioning of a cloud network in pending status. Returns an operation ID for progress tracking.
      tags:
        - networks
      responses:
        '202':
          $ref: '#/components/responses/ProvisionExternalNetworkByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/clusters:
    get:
      operationId: ListExternalClusters
      summary: List provisioned clusters
      description: Returns all provisioned clusters accessible to the organization across all connections, supporting marker-based pagination.
      tags:
        - clusters
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListExternalClustersResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/clusters/{cluster}:
    parameters:
      - $ref: '#/components/parameters/ExternalClusterId'
    get:
      operationId: DescribeExternalCluster
      summary: Describe a provisioned cluster
      description: Returns the details of a specific provisioned cluster including its connection information and related entities.
      tags:
        - clusters
      responses:
        '200':
          $ref: '#/components/responses/DescribeExternalClusterResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteExternalCluster
      summary: Delete a provisioned cluster record
      description: |
        Permanently deletes a provisioned cluster record. The cluster's infrastructure must
        first be destroyed before the record can be deleted. A cluster in a failed state
        may still have active infrastructure and should be destroyed first.
      tags:
        - clusters
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/clusters:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
    get:
      operationId: ListExternalClustersByConnection
      summary: List provisioned clusters by connection
      description: Returns the provisioned clusters within the specified connection.
      tags:
        - clusters
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListExternalClustersResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateExternalCluster
      summary: Create a provisioned cluster
      description: Creates a new EKS cluster in your AWS account via the specified connection. Requires an active connection and an active network.
      tags:
        - clusters
      requestBody:
        $ref: '#/components/requestBodies/CreateExternalClusterRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateExternalClusterResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/clusters/{cluster}:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
      - $ref: '#/components/parameters/ExternalClusterId'
    get:
      operationId: DescribeExternalClusterByConnection
      summary: Describe a provisioned cluster by connection
      description: Returns the details of a provisioned cluster, including its Kubernetes version, node group configuration, and provisioning status.
      tags:
        - clusters
      responses:
        '200':
          $ref: '#/components/responses/DescribeExternalClusterByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DestroyExternalClusterByConnection
      summary: Destroy a provisioned cluster
      description: Initiates destruction of an active provisioned cluster's cloud infrastructure. The cluster record is retained for reference. Returns an operation ID for tracking progress.
      tags:
        - clusters
      responses:
        '202':
          $ref: '#/components/responses/DestroyExternalClusterByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: UpdateExternalClusterByConnection
      summary: Update a provisioned cluster
      description: Update the Kubernetes version or node group configuration of a provisioned cluster. This triggers an asynchronous update process.
      requestBody:
        $ref: '#/components/requestBodies/UpdateExternalClusterByConnectionRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateExternalClusterByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - clusters
  /infra/connections/{connection}/clusters/{cluster}/health:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
      - $ref: '#/components/parameters/ExternalClusterId'
    get:
      operationId: GetExternalClusterHealthByConnection
      summary: Get provisioned cluster health status
      description: Returns the health status of the EKS cluster and its node groups.
      tags:
        - clusters
      responses:
        '200':
          $ref: '#/components/responses/GetExternalClusterHealthByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/clusters/{cluster}/kubeconfig:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
      - $ref: '#/components/parameters/ExternalClusterId'
    get:
      operationId: GetExternalClusterKubeconfigByConnection
      summary: Get provisioned cluster kubeconfig
      description: Returns a kubeconfig that can be used to access the EKS cluster.
      tags:
        - clusters
      responses:
        '200':
          $ref: '#/components/responses/GetExternalClusterKubeconfigByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/clusters/{cluster}/metrics:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
      - $ref: '#/components/parameters/ExternalClusterId'
    get:
      operationId: GetExternalClusterMetricsByConnection
      summary: Get provisioned cluster metrics
      description: Returns CPU and memory utilization metrics for the cluster over a specified period.
      tags:
        - clusters
      parameters:
        - name: period
          in: query
          description: The period for metrics (e.g., "1h", "24h", "7d"). Default is "1h".
          schema:
            type: string
            default: 1h
      responses:
        '200':
          $ref: '#/components/responses/GetExternalClusterMetricsByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /infra/connections/{connection}/clusters/{cluster}/provision:
    parameters:
      - $ref: '#/components/parameters/ExternalConnectionId'
      - $ref: '#/components/parameters/ExternalClusterId'
    post:
      operationId: ProvisionExternalClusterByConnection
      summary: Provision a cluster
      description: Triggers provisioning of a cluster in pending status. Returns an operation ID for progress tracking.
      tags:
        - clusters
      responses:
        '202':
          $ref: '#/components/responses/ProvisionExternalClusterByConnectionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/catalogs:
    get:
      operationId: ListOrgCatalogs
      summary: List catalogs
      description: Returns all catalogs the caller has permission to view across the organization.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListOrgCatalogsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateCatalog
      summary: Create a catalog
      description: Creates a new catalog with the specified provider and configuration. Returns 409 if a catalog with the same name already exists.
      tags:
        - catalogs
      requestBody:
        $ref: '#/components/requestBodies/CreateCatalogRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateCatalogResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '409':
          $ref: '#/components/responses/ErrorConflictResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/catalogs/{catalog}:
    parameters:
      - $ref: '#/components/parameters/CatalogId'
    get:
      operationId: DescribeCatalog
      summary: Describe a catalog
      description: Returns the full details of a catalog, including its provider configuration.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/CatalogId'
      responses:
        '200':
          $ref: '#/components/responses/DescribeCatalogResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateCatalog
      summary: Update a catalog
      description: Modifies a catalog's name or provider configuration.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/CatalogId'
      requestBody:
        $ref: '#/components/requestBodies/UpdateCatalogRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateCatalogResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteCatalog
      summary: Delete a catalog
      description: Permanently removes a catalog and its team associations. Queries that reference this catalog will need to be updated.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/CatalogId'
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/catalogs/{catalog}/teams:
    parameters:
      - $ref: '#/components/parameters/CatalogId'
    get:
      operationId: ListCatalogTeams
      summary: List catalog teams
      description: Returns all teams that have been granted access to the specified catalog.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/CatalogId'
      responses:
        '200':
          $ref: '#/components/responses/ListCatalogTeamsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: AddTeamsToCatalog
      summary: Add teams to a catalog
      description: Grants one or more teams access to the specified catalog.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/CatalogId'
      requestBody:
        $ref: '#/components/requestBodies/AddTeamsToCatalogRequest'
      responses:
        '201':
          $ref: '#/components/responses/AddTeamsToCatalogResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/catalogs/{catalog}/teams/{team}:
    parameters:
      - $ref: '#/components/parameters/CatalogId'
      - $ref: '#/components/parameters/TeamId'
    delete:
      operationId: RemoveTeamFromCatalog
      summary: Remove a team from a catalog
      description: Revokes a team's access to the specified catalog.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/CatalogId'
        - $ref: '#/components/parameters/TeamId'
      responses:
        '204':
          description: The team was removed from the catalog successfully.
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/catalogs/{catalog}/queries:
    parameters:
      - $ref: '#/components/parameters/CatalogId'
    get:
      operationId: ListCatalogQueries
      summary: List queries that use a catalog
      description: Returns all queries that reference the specified catalog as a data source.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListCatalogQueriesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/teams/{team}/catalogs:
    parameters:
      - $ref: '#/components/parameters/TeamId'
    get:
      operationId: ListTeamCatalogs
      summary: List team catalogs
      description: Returns all catalogs that have been assigned to the specified team.
      tags:
        - catalogs
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListTeamCatalogsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/queries:
    get:
      operationId: ListOrgQueries
      summary: List queries
      description: Returns a paginated list of all queries in the organization, including their SQL statements and catalog configuration.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListOrgQueriesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateQuery
      summary: Create a query
      description: Defines a new reusable SQL query within the organization. Queries can be referenced by one or more jobs and shared with teams for collaborative use.
      tags:
        - queries
      requestBody:
        $ref: '#/components/requestBodies/CreateQueryRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateQueryResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/queries/{query}:
    parameters:
      - $ref: '#/components/parameters/QueryId'
    get:
      operationId: DescribeQuery
      summary: Describe a query
      description: Returns the full details of a query, including its SQL statement, catalog provider, schema, and associated teams.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/QueryId'
      responses:
        '200':
          $ref: '#/components/responses/DescribeQueryResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateQuery
      summary: Update a query
      description: Modifies a query's properties such as its name, SQL statement, catalog provider, or schema configuration.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/QueryId'
      requestBody:
        $ref: '#/components/requestBodies/UpdateQueryRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateQueryResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteQuery
      summary: Delete a query
      description: Permanently removes a query and its team assignments. Queries that are still referenced by active jobs cannot be deleted.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/QueryId'
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/queries/{query}/teams:
    parameters:
      - $ref: '#/components/parameters/QueryId'
    get:
      operationId: ListQueryTeams
      summary: List query teams
      description: Returns the teams that have been granted access to the specified query.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListQueryTeamsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: AddTeamsToQuery
      summary: Add teams to a query
      description: Grants one or more teams access to a query. Team members inherit the ability to view and use the query based on their team role permissions.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/QueryId'
      requestBody:
        $ref: '#/components/requestBodies/AddTeamsToQueryRequest'
      responses:
        '201':
          $ref: '#/components/responses/AddTeamsToQueryResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/queries/{query}/teams/{team}:
    parameters:
      - $ref: '#/components/parameters/QueryId'
      - $ref: '#/components/parameters/TeamId'
    delete:
      operationId: RemoveTeamFromQuery
      summary: Remove a team from a query
      description: Revokes a team's access to a query. Team members will no longer be able to view or use the query unless they have access through another team.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/QueryId'
        - $ref: '#/components/parameters/TeamId'
      responses:
        '204':
          description: The team was removed from the query successfully.
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/teams/{team}/queries:
    parameters:
      - $ref: '#/components/parameters/TeamId'
    get:
      operationId: ListTeamQueries
      summary: List team queries
      description: Returns a paginated list of queries that the specified team has been granted access to.
      tags:
        - queries
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListTeamQueriesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs:
    get:
      operationId: ListOrgJobs
      summary: List jobs
      description: Returns a paginated list of all jobs in the organization, including their current status, active version, and schedule information.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListOrgJobsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateJob
      summary: Create a job
      description: Defines a new job within the organization. The job is created with an initial published version containing the provided configuration, including the target cluster, schedule, and query assignments. Requires an active cluster and at least one team.
      tags:
        - jobs
      requestBody:
        $ref: '#/components/requestBodies/CreateJobRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateJobResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      operationId: DescribeJob
      summary: Describe a job
      description: Returns the full details of a job, including its current active version configuration, schedule, and associated cluster and query information.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          $ref: '#/components/responses/DescribeJobResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateJob
      summary: Update a job
      description: Modifies a job's metadata such as its name or description. To change execution configuration (cluster, schedule, queries), create a new version using the versioning endpoints instead.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      requestBody:
        $ref: '#/components/requestBodies/UpdateJobRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateJobResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteJob
      summary: Delete a job
      description: Permanently removes a job and all its associated versions, runs, and team assignments. Active or pending runs are cancelled before deletion.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/activate-version:
    parameters:
      - $ref: '#/components/parameters/JobId'
    post:
      operationId: ActivateJobVersion
      summary: Activate a job version
      description: |
        Changes the job's active configuration to a previously published version.
        The target version must exist and be published. Any existing draft version
        must be discarded or published before activating a different version.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      requestBody:
        $ref: '#/components/requestBodies/ActivateJobVersionRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActivateJobVersionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/draft:
    parameters:
      - $ref: '#/components/parameters/JobId'
    post:
      operationId: CreateJobDraft
      summary: Create a new draft version for a job
      description: |
        Creates a new draft version by copying the currently published version's
        configuration. Fields provided in the request body override the copied values.
        A job can have at most one draft version at a time. If a draft already exists,
        returns 409 Conflict.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      requestBody:
        $ref: '#/components/requestBodies/CreateJobDraftRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateJobDraftResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorConflictResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: DescribeJobDraft
      summary: Describe the draft version of a job
      description: |
        Returns the current draft version for the specified job.
        Returns 404 if no draft version exists.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          $ref: '#/components/responses/DescribeJobDraftResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateJobDraft
      summary: Update the draft version of a job
      description: |
        Updates fields on the current draft version. Only provided fields are modified;
        omitted fields retain their current values. Returns 404 if no draft version exists.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      requestBody:
        $ref: '#/components/requestBodies/UpdateJobDraftRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateJobDraftResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteJobDraft
      summary: Discard the draft version of a job
      description: |
        Discards (deletes) the current draft version without publishing it.
        The job continues running its current published version unchanged.
        Returns 404 if no draft version exists.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '204':
          description: The draft version was discarded successfully.
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/draft/publish:
    parameters:
      - $ref: '#/components/parameters/JobId'
    post:
      operationId: PublishJobDraft
      summary: Publish the draft version of a job
      description: |
        Publishes the current draft version, making it the new active configuration.
        The draft version's status changes to 'published' and the job's version pointer
        is updated. Returns 400 if no draft version exists, 404 if the job does not exist.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          $ref: '#/components/responses/PublishJobDraftResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/teams:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      operationId: ListJobTeams
      summary: List job teams
      description: Returns the teams that have been granted access to the specified job.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListJobTeamsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: AddTeamsToJob
      summary: Add teams to a job
      description: Grants one or more teams access to a job. Team members inherit the ability to view the job and its runs based on their team role permissions.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      requestBody:
        $ref: '#/components/requestBodies/AddTeamsToJobRequest'
      responses:
        '201':
          $ref: '#/components/responses/AddTeamsToJobResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/teams/{team}:
    parameters:
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/TeamId'
    delete:
      operationId: RemoveTeamFromJob
      summary: Remove a team from a job
      description: Revokes a team's access to a job. Team members will no longer be able to view or interact with the job unless they have access through another team.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
        - $ref: '#/components/parameters/TeamId'
      responses:
        '204':
          description: The team was removed from the job successfully.
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/versions:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      operationId: ListJobVersions
      summary: List job versions
      description: Returns a paginated list of all published versions for a job, ordered by version number. Each version represents a point-in-time configuration snapshot.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          $ref: '#/components/responses/ListJobVersionsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateJobVersion
      summary: Create a job version
      description: |
        Creates and publishes a new version for the job in a single request. This is
        equivalent to creating a draft, updating fields, and publishing. The job must
        not have an existing draft version.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      requestBody:
        $ref: '#/components/requestBodies/CreateJobVersionRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateJobVersionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorConflictResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/versions/{jobVersionNumber}:
    parameters:
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/JobVersionNumber'
    get:
      operationId: DescribeJobVersion
      summary: Describe a job version
      description: Returns the full configuration snapshot for a specific version of a job, including cluster assignment, schedule, queries, and dependency settings.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
        - $ref: '#/components/parameters/JobVersionNumber'
      responses:
        '200':
          $ref: '#/components/responses/DescribeJobVersionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/teams/{team}/jobs:
    parameters:
      - $ref: '#/components/parameters/TeamId'
    get:
      operationId: ListTeamJobs
      summary: List team jobs
      description: Returns a paginated list of jobs that the specified team has been granted access to.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListTeamJobsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/runs:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      operationId: ListJobRuns
      summary: List job runs
      description: Returns a paginated list of runs for a specific job, ordered by creation time. Includes status, timing, and trigger information for each run.
      tags:
        - job-runs
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListJobRunsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateJobRun
      summary: Create a job run
      description: Triggers a new execution of the job using its currently active version configuration. The run is placed in a pending state until released or automatically dispatched by the scheduler.
      tags:
        - job-runs
      parameters:
        - $ref: '#/components/parameters/JobId'
      requestBody:
        $ref: '#/components/requestBodies/CreateJobRunRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateJobRunResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/runs/{jobRun}:
    parameters:
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/JobRunId'
    get:
      operationId: DescribeJobRun
      summary: Describe a job run
      description: Returns the full details of a job run, including its current status, timing information, and execution results.
      tags:
        - job-runs
      parameters:
        - $ref: '#/components/parameters/JobId'
        - $ref: '#/components/parameters/JobRunId'
      responses:
        '200':
          $ref: '#/components/responses/DescribeJobRunResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteJobRun
      summary: Delete a job run
      description: Permanently removes a job run record. Only completed, failed, or cancelled runs can be deleted.
      tags:
        - job-runs
      parameters:
        - $ref: '#/components/parameters/JobId'
        - $ref: '#/components/parameters/JobRunId'
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/runs/{jobRun}/ready:
    parameters:
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/JobRunId'
    post:
      operationId: ReleaseJobRun
      summary: Release a pending job run for execution
      description: |
        Transitions a job run from `pending` to `ready`, making it eligible for execution.
        Use this when orchestrating job runs that were created in `pending` status and
        should be released once their dependencies are satisfied.
        Returns 409 if the run is not currently in `pending` status.
      tags:
        - job-runs
      responses:
        '200':
          $ref: '#/components/responses/ReleaseJobRunResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          description: The job run is not in `pending` status and cannot be released.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/jobs/{job}/runs/{jobRun}/retry:
    parameters:
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/JobRunId'
    post:
      operationId: RetryJobRun
      summary: Retry a job run
      description: |
        Resets a terminal job run so it can be executed again.
        The run keeps its original ID, version, parameters, and audit trail.

        The run's status must be `failed`, `timeout`, or `cancelled`. By default
        the run transitions to `ready` (immediately eligible for execution).
        If `hold` is true in the request body, the run transitions to `pending`
        instead, requiring a subsequent Release call before execution.

        Returns 409 if the run is not in an allowed terminal status.
      tags:
        - job-runs
      requestBody:
        $ref: '#/components/requestBodies/RetryJobRunRequest'
      responses:
        '200':
          $ref: '#/components/responses/RetryJobRunResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          description: The job run is not in a retryable terminal status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/clusters/{cluster}/jobs:
    parameters:
      - $ref: '#/components/parameters/ClusterId'
    get:
      operationId: ListClusterJobs
      summary: List jobs on a cluster
      description: Returns a paginated list of jobs whose active version is configured to execute on the specified cluster.
      tags:
        - jobs
      parameters:
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/ListClusterJobsResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/sessions:
    get:
      operationId: ListSessions
      summary: List sessions
      description: Returns sessions visible to the caller. Members see their own sessions; team admins see all sessions in their team; org admins see all sessions.
      tags:
        - sessions
      parameters:
        - $ref: '#/components/parameters/FilterBySessionTeamId'
        - $ref: '#/components/parameters/FilterBySessionEndpoint'
        - $ref: '#/components/parameters/FilterBySessionStatus'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListSessionsResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateSession
      summary: Create a session
      description: Creates a new session. Resolves or creates a compute config, finds a reusable compute instance or provisions a new one, and returns the session in pending state. The session transitions to active on the first proxy request after the compute instance is ready.
      tags:
        - sessions
      requestBody:
        $ref: '#/components/requestBodies/CreateSessionRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateSessionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '409':
          $ref: '#/components/responses/ErrorConflictResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/sessions/{session}:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      operationId: DescribeSession
      summary: Describe a session
      description: Returns the session details. For the session owner, includes connectionInfo with the proxy authentication URL (HTTP-transport endpoints) or gRPC endpoint (gRPC-transport endpoints).
      tags:
        - sessions
      responses:
        '200':
          $ref: '#/components/responses/DescribeSessionResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: CloseSession
      summary: Close a session
      description: Closes the session immediately. The session transitions to closed and closed_at is set. Infrastructure cleanup (marimo pod, compute instance) is handled asynchronously. Can be called by the session owner, team admin, or org admin.
      tags:
        - sessions
      responses:
        '204':
          description: The session was closed successfully.
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorConflictResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/sessions/{session}/token:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      operationId: IssueSessionToken
      summary: Issue a session proxy token
      description: "Issues a short-lived signed JWT bearer token for authenticating with the session gRPC proxy. Use the grpcEndpoint from the session's connectionInfo as the dial address and pass the token as Authorization: Bearer <token> in the gRPC metadata. The token encodes the session ID and routing target; no additional metadata header is required. Only the session owner (or an org admin) can issue a token."
      tags:
        - sessions
      requestBody:
        $ref: '#/components/requestBodies/IssueSessionTokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/IssueSessionTokenResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorConflictResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/sessions/{session}/relaunch:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      operationId: RelaunchSession
      summary: Relaunch a closed session
      description: |-
        Creates a new session using the same workload configuration as a previously closed or failed session. Useful for restarting a recurring session without having to reconfigure compute settings from scratch.
        The original session must be in a terminal state (closed or failed). A brand-new session ID is returned — the original session is not mutated. The caller must be the original session owner.
      tags:
        - sessions
      responses:
        '201':
          $ref: '#/components/responses/RelaunchSessionResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        '409':
          $ref: '#/components/responses/ErrorConflictResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/compute-configs:
    get:
      operationId: ListWorkloadConfigs
      summary: List workload configs
      description: Returns workload configs visible to the caller. Org admins see all configs; team admins see configs belonging to their teams; members see configs for teams they belong to. Anonymous (inline) configs are excluded.
      tags:
        - sessions
      parameters:
        - $ref: '#/components/parameters/FilterByWorkloadConfigTeamId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          $ref: '#/components/responses/ListOrgWorkloadConfigsResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateWorkloadConfig
      summary: Create a workload config
      description: Creates a named workload config for a team. Named configs can be reused across multiple sessions and shared with team members. Once created, workloadType, clusterId, and teamId are immutable.
      tags:
        - sessions
      requestBody:
        $ref: '#/components/requestBodies/CreateWorkloadConfigRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateWorkloadConfigResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /workloads/compute-configs/{workloadConfig}:
    parameters:
      - $ref: '#/components/parameters/WorkloadConfigId'
    get:
      operationId: DescribeWorkloadConfig
      summary: Describe a workload config
      description: Returns the full detail of a workload config.
      tags:
        - sessions
      responses:
        '200':
          $ref: '#/components/responses/DescribeWorkloadConfigResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /notifications/event-types:
    get:
      operationId: ListNotificationEventTypes
      summary: List available notification event types
      description: Returns the list of event types that notification rules can subscribe to. Includes shortcut types (e.g., 'any terminal status') that expand into individual event types at rule creation time.
      tags:
        - notifications
      responses:
        '200':
          $ref: '#/components/responses/ListNotificationEventTypesResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /notifications/channels:
    get:
      operationId: ListNotificationChannels
      summary: List notification channels
      description: Lists notification channels for the organization, optionally filtered by team or member ownership.
      tags:
        - notifications
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
        - $ref: '#/components/parameters/FilterByTeamId'
        - $ref: '#/components/parameters/FilterByMemberId'
      responses:
        '200':
          $ref: '#/components/responses/ListNotificationChannelsResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateNotificationChannel
      summary: Create a notification channel
      description: Creates a new notification channel for delivering notifications to a team or member destination (email or webhook).
      tags:
        - notifications
      requestBody:
        $ref: '#/components/requestBodies/CreateNotificationChannelRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateNotificationChannelResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /notifications/channels/{channel}:
    parameters:
      - $ref: '#/components/parameters/NotificationChannelId'
    get:
      operationId: DescribeNotificationChannel
      summary: Get notification channel details
      description: Returns the details of a specific notification channel.
      tags:
        - notifications
      responses:
        '200':
          $ref: '#/components/responses/DescribeNotificationChannelResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateNotificationChannel
      summary: Update a notification channel
      description: Updates the configuration of an existing notification channel.
      tags:
        - notifications
      requestBody:
        $ref: '#/components/requestBodies/UpdateNotificationChannelRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateNotificationChannelResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteNotificationChannel
      summary: Delete a notification channel
      description: Soft-deletes a notification channel. The channel is marked as deleted but preserved for delivery log history.
      tags:
        - notifications
      responses:
        '204':
          description: The notification channel was deleted successfully.
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /notifications/channels/{channel}/test:
    parameters:
      - $ref: '#/components/parameters/NotificationChannelId'
    post:
      operationId: TestNotificationChannel
      summary: Send a test notification
      description: Sends a test notification to verify the channel is configured correctly. On success, sets the channel's verifiedAt timestamp.
      tags:
        - notifications
      responses:
        '204':
          description: The test notification was sent successfully.
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /notifications/rules:
    get:
      operationId: ListNotificationRules
      summary: List notification rules
      description: Lists notification rules for the organization, optionally filtered by team, member, resource type, or scope type.
      tags:
        - notifications
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
        - $ref: '#/components/parameters/FilterByTeamId'
        - $ref: '#/components/parameters/FilterByMemberId'
        - $ref: '#/components/parameters/FilterByResourceType'
        - $ref: '#/components/parameters/FilterByScopeType'
      responses:
        '200':
          $ref: '#/components/responses/ListNotificationRulesResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: CreateNotificationRule
      summary: Create a notification rule
      description: Creates a new notification rule that maps event types to notification channels.
      tags:
        - notifications
      requestBody:
        $ref: '#/components/requestBodies/CreateNotificationRuleRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateNotificationRuleResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /notifications/rules/{rule}:
    parameters:
      - $ref: '#/components/parameters/NotificationRuleId'
    get:
      operationId: DescribeNotificationRule
      summary: Get notification rule details
      description: Returns the details of a specific notification rule.
      tags:
        - notifications
      responses:
        '200':
          $ref: '#/components/responses/DescribeNotificationRuleResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      operationId: UpdateNotificationRule
      summary: Update a notification rule
      description: Updates an existing notification rule (including enable/disable).
      tags:
        - notifications
      requestBody:
        $ref: '#/components/requestBodies/UpdateNotificationRuleRequest'
      responses:
        '200':
          $ref: '#/components/responses/UpdateNotificationRuleResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: DeleteNotificationRule
      summary: Delete a notification rule
      description: Deletes a notification rule. Future events will no longer match this rule.
      tags:
        - notifications
      responses:
        '204':
          description: The notification rule was deleted successfully.
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /notifications:
    get:
      operationId: ListNotifications
      summary: List notification delivery history
      description: Lists notification delivery log entries, optionally filtered by channel, rule, or status.
      tags:
        - notifications
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
        - $ref: '#/components/parameters/FilterByChannelId'
        - $ref: '#/components/parameters/FilterByRuleId'
        - $ref: '#/components/parameters/FilterByStatus'
      responses:
        '200':
          $ref: '#/components/responses/ListNotificationsResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /operations/{operationId}:
    parameters:
      - $ref: '#/components/parameters/OperationId'
    get:
      operationId: GetOperation
      summary: Get async operation status
      description: Returns the current status and results of a long-running operation, such as cluster provisioning or infrastructure deployment. Poll this endpoint to track progress.
      tags:
        - operations
      responses:
        '200':
          $ref: '#/components/responses/GetOperationResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequestResponse'
        '401':
          $ref: '#/components/responses/ErrorUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorForbiddenResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFoundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    Organization:
      type: apiKey
      in: header
      name: LakeSail-Organization-Id
    AuthRequest:
      type: apiKey
      in: header
      name: Auth-Request-Id
    HmacSignature:
      type: apiKey
      in: header
      name: LakeSail-Signature
      description: 'HMAC-SHA256 signature for webhook authentication. Value format: sha256=<hex-encoded HMAC digest>.'
  schemas:
    AcceptInvite:
      type: object
      description: The details to accept the invite.
      required:
        - user
      properties:
        user:
          allOf:
            - $ref: '#/components/schemas/UserSignupSpec'
    AccountType:
      type: string
      enum:
        - managed
        - external
      description: |
        The account type determines who can modify the user's profile.
        - 'managed': Organization controls the user account (employee)
        - 'external': User self-manages their account (consultant/contractor)
      default: managed
    AcrValue:
      type: string
      description: ACR values for LakeSail auth
      enum:
        - urn:lakesail:loa:1fa:any
        - urn:lakesail:loa:1fa:pwd
        - urn:lakesail:loa:2fa:any
        - urn:lakesail:loa:2fa:any:ifpossible
        - urn:lakesail:loa:2fa:phr
    ActivateJobVersionSpec:
      type: object
      description: The specification to activate a previously published job version.
      required:
        - version
      properties:
        version:
          type: integer
          description: The published version number to activate.
          minimum: 1
    AddMyEmailSpec:
      type: object
      description: A request to add an email address to the current user.
      required:
        - email
      properties:
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The email address to add.
    AddTeamMember:
      type: object
      description: The body for adding a member to a team.
      properties:
        roleIds:
          type: array
          items:
            $ref: '#/components/schemas/ResourceId'
          description: The team role IDs to assign to the member upon joining the team. When omitted or empty, the team's configured default role is used.
          example:
            - ROLE123
    AddTeamsToCatalog:
      type: object
      required:
        - teamIds
      properties:
        teamIds:
          type: array
          description: The team IDs to add to the catalog.
          minItems: 1
          items:
            $ref: '#/components/schemas/ResourceId'
    AutoSetupIdentityProviderSpec:
      type: object
      description: Specification to automatically setup an identity provider using DCR.
      required:
        - name
        - providerUrl
      properties:
        name:
          type: string
          description: The display name for this identity provider.
          minLength: 1
          maxLength: 255
          example: Company SSO
          x-access-type: ReadWrite
          x-order: 1
        providerUrl:
          type: string
          format: uri
          description: |
            The base URL of the OIDC provider. Must be a fully-qualified URL with scheme.

            The system will automatically append `/.well-known/openid-configuration` 
            to discover the OIDC configuration.

            Examples:
            - Okta: `https://mycompany.okta.com`
            - Auth0: `https://mycompany.auth0.com`
            - Azure AD: `https://login.microsoftonline.com/tenant-id`
            - Keycloak: `https://keycloak.example.com/realms/myrealm`
            - Local development: `http://localhost:28092/realms/lakesail-test`
          minLength: 1
          maxLength: 512
          example: https://keycloak.example.com/realms/myrealm
          x-access-type: ReadWrite
          x-order: 2
        providerType:
          type: string
          description: |
            Type of provider. If not specified, the system will attempt to auto-detect
            based on the provider domain. Specifying this helps handle provider-specific
            requirements (e.g., initial access tokens).
          enum:
            - okta
            - auth0
            - onelogin
            - azure
            - google
            - adfs
            - keycloak
            - generic
          example: okta
          x-access-type: ReadWrite
          x-order: 3
        initialAccessToken:
          type: string
          description: |
            Initial access token required by some providers for DCR (e.g., Okta, Auth0, OneLogin).
            If required and not provided, the endpoint will return an error with
            instructions on how to obtain this token.

            Not required for: Keycloak, generic OIDC providers
            Not supported: ADFS (use manual setup instead)
          minLength: 1
          maxLength: 2048
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
          x-access-type: WriteOnly
          x-order: 4
    Base64:
      type: string
      pattern: ^[a-zA-Z0-9\-_]+(%3D|=){0,2}$
    CapacityType:
      type: string
      enum:
        - on-demand
      default: on-demand
      description: The capacity type for the nodes. Only the on-demand capacity type is supported. Support for spot is not yet available.
    Catalog:
      type: object
      description: Full catalog detail.
      required:
        - id
        - name
        - provider
        - config
        - createdAt
        - createdBy
        - updatedAt
        - updatedBy
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The catalog ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The catalog name.
          x-access-type: ReadWrite
          x-order: 2
        provider:
          allOf:
            - $ref: '#/components/schemas/CatalogProvider'
          description: The Sail catalog provider type.
          x-access-type: ReadImmutable
          x-order: 3
        config:
          allOf:
            - $ref: '#/components/schemas/CatalogConfigRead'
          description: Provider-specific catalog configuration (read operations, secrets redacted).
          x-access-type: ReadOnly
          x-order: 4
        configWrite:
          allOf:
            - $ref: '#/components/schemas/CatalogConfigWrite'
          description: Provider-specific catalog configuration (write operations). Secret fields are optional; omit to keep the existing value.
          x-access-type: WriteOnly
          x-order: 4
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this catalog was created.
          x-access-type: ReadOnly
          x-order: 5
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this catalog.
          x-access-type: ReadOnly
          x-order: 6
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this catalog was last updated.
          x-access-type: ReadOnly
          x-order: 7
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this catalog.
          x-access-type: ReadOnly
          x-order: 8
    CatalogConfigGlue:
      type: object
      description: Configuration for the AWS Glue catalog provider.
      additionalProperties: false
      properties:
        region:
          type: string
          description: The AWS region where the Glue catalog is located (e.g. us-east-1).
          example: us-east-1
          x-order: 1
        endpointUrl:
          type: string
          description: Optional custom endpoint URL to override the default Glue endpoint.
          example: https://glue.us-east-1.amazonaws.com
          x-order: 2
        database:
          type: string
          description: The default Glue database (schema) name to use. Populates SAIL_CATALOG__DEFAULT_DATABASE when set.
          example: analytics_db
          x-order: 3
    CatalogConfigIcebergRestRead:
      type: object
      description: Configuration for the Iceberg REST catalog provider (read operations).
      additionalProperties: false
      properties:
        uri:
          type: string
          description: The URI of the Iceberg REST catalog server.
          x-order: 1
        warehouse:
          type: string
          description: The warehouse identifier / storage root path.
          x-order: 2
        prefix:
          type: string
          description: Optional prefix to prepend to all catalog paths.
          x-order: 3
        oauthAccessTokenConfigured:
          type: boolean
          description: Whether an OAuth 2.0 access token is configured.
          x-order: 4
        bearerAccessTokenConfigured:
          type: boolean
          description: Whether a bearer access token is configured.
          x-order: 5
    CatalogConfigIcebergRestWrite:
      type: object
      description: Configuration for the Iceberg REST catalog provider (write operations).
      additionalProperties: false
      required:
        - uri
      properties:
        uri:
          type: string
          description: The URI of the Iceberg REST catalog server.
          x-order: 1
        warehouse:
          type: string
          description: The warehouse identifier / storage root path.
          x-order: 2
        prefix:
          type: string
          description: Optional prefix to prepend to all catalog paths.
          x-order: 3
        oauthAccessToken:
          type: string
          description: OAuth 2.0 access token for authentication. Omit to keep the existing value.
          format: password
          x-order: 4
        bearerAccessToken:
          type: string
          description: Bearer token for authentication (alternative to OAuth). Omit to keep the existing value.
          format: password
          x-order: 5
    CatalogConfigMemory:
      type: object
      description: Configuration for the Memory catalog provider.
      additionalProperties: false
      required:
        - initialDatabase
      properties:
        initialDatabase:
          type: string
          description: The name of the initial database to create in the in-memory catalog.
          example: default
          x-order: 1
        initialDatabaseComment:
          type: string
          description: Optional comment for the initial database.
          example: Default in-memory database for development
          x-order: 2
    CatalogConfigOneLakeRead:
      type: object
      description: Configuration for the Microsoft OneLake catalog provider (read operations).
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          description: The OneLake endpoint URL (e.g. https://<account>.dfs.fabric.microsoft.com).
          x-order: 1
        bearerTokenConfigured:
          type: boolean
          description: Whether a bearer token for authentication with OneLake is configured.
          x-order: 2
    CatalogConfigOneLakeWrite:
      type: object
      description: Configuration for the Microsoft OneLake catalog provider (write operations).
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          description: The OneLake endpoint URL (e.g. https://<account>.dfs.fabric.microsoft.com).
          x-order: 1
        bearerToken:
          type: string
          description: Bearer token for authentication with OneLake. Omit to keep the existing value.
          format: password
          x-order: 2
    CatalogConfigRead:
      type: object
      description: Provider-specific catalog configuration (read operations, secrets redacted).
      anyOf:
        - $ref: '#/components/schemas/CatalogConfigMemory'
        - $ref: '#/components/schemas/CatalogConfigIcebergRestRead'
        - $ref: '#/components/schemas/CatalogConfigUnityRead'
        - $ref: '#/components/schemas/CatalogConfigGlue'
        - $ref: '#/components/schemas/CatalogConfigOneLakeRead'
    CatalogConfigUnityRead:
      type: object
      description: Configuration for the Unity Catalog provider (read operations).
      additionalProperties: false
      properties:
        uri:
          type: string
          description: The URI of the Unity Catalog server. Defaults to localhost if not specified.
          x-order: 1
        defaultCatalog:
          type: string
          description: The default catalog name to use.
          x-order: 2
        tokenConfigured:
          type: boolean
          description: Whether a personal access token or service principal token is configured.
          x-order: 3
    CatalogConfigUnityWrite:
      type: object
      description: Configuration for the Unity Catalog provider (write operations).
      additionalProperties: false
      properties:
        uri:
          type: string
          description: The URI of the Unity Catalog server. Defaults to localhost if not specified.
          x-order: 1
        defaultCatalog:
          type: string
          description: The default catalog name to use.
          x-order: 2
        token:
          type: string
          description: Personal access token or service principal token for authentication. Omit to keep the existing value.
          format: password
          x-order: 3
    CatalogConfigWrite:
      type: object
      description: Provider-specific catalog configuration (write operations, secrets optional).
      anyOf:
        - $ref: '#/components/schemas/CatalogConfigMemory'
        - $ref: '#/components/schemas/CatalogConfigIcebergRestWrite'
        - $ref: '#/components/schemas/CatalogConfigUnityWrite'
        - $ref: '#/components/schemas/CatalogConfigGlue'
        - $ref: '#/components/schemas/CatalogConfigOneLakeWrite'
    CatalogIncluded:
      type: object
      description: |
        Included entities for catalog responses.
      properties:
        catalogs:
          type: array
          description: Array of catalog summary entities.
          items:
            $ref: '#/components/schemas/CatalogSummary'
        teams:
          type: array
          description: Array of expanded team objects associated with catalogs.
          items:
            $ref: '#/components/schemas/TeamExpanded'
        externalCatalogs:
          type: array
          description: Array of external catalog summaries linked to managed catalogs.
          items:
            $ref: '#/components/schemas/ExternalCatalogSummary'
    CatalogItem:
      type: object
      description: A catalog reference containing only IDs for related entities.
      required:
        - catalogId
      properties:
        catalogId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The catalog ID.
        teamIds:
          type: array
          description: Array of team IDs associated with this catalog.
          items:
            allOf:
              - $ref: '#/components/schemas/ResourceId'
        externalCatalogIds:
          type: array
          description: Array of IDs of external catalogs linked to this managed catalog.
          items:
            allOf:
              - $ref: '#/components/schemas/ResourceId'
    CatalogList:
      type: object
      description: A list of LakeSail catalogs.
      required:
        - total
        - items
        - included
      properties:
        total:
          type: integer
          description: The total number of catalogs accessible to the member.
          x-order: 1
        items:
          type: array
          description: Catalog list items with ID references only.
          items:
            $ref: '#/components/schemas/CatalogItem'
          x-order: 2
        included:
          allOf:
            - $ref: '#/components/schemas/CatalogIncluded'
          description: Related entities referenced by IDs in the list items.
          x-order: 3
    CatalogProvider:
      type: string
      enum:
        - memory
        - iceberg-rest
        - unity
        - glue
        - onelake
        - system
      description: |
        The Sail provider of the data catalog where this query will be executed.

        See https://docs.lakesail.com/sail/latest/guide/catalog/ for more information about supported Sail providers.
      example: glue
    CatalogSpec:
      type: object
      description: The specification to create a catalog.
      required:
        - teamIds
        - name
        - provider
        - configWrite
      x-filter-group: Spec
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The catalog name.
          x-access-type: ReadWrite
          x-order: 2
        provider:
          allOf:
            - $ref: '#/components/schemas/CatalogProvider'
          description: The Sail catalog provider type.
          x-access-type: ReadImmutable
          x-order: 3
        configWrite:
          allOf:
            - $ref: '#/components/schemas/CatalogConfigWrite'
          description: Provider-specific catalog configuration (write operations). Secret fields are optional; omit to keep the existing value.
          x-access-type: WriteOnly
          x-order: 4
        teamIds:
          type: array
          description: The team IDs that will have access to this catalog.
          minItems: 1
          items:
            $ref: '#/components/schemas/ResourceId'
    CatalogSummary:
      type: object
      description: A summary of a catalog.
      required:
        - id
        - name
        - provider
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The catalog ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The catalog name.
          x-access-type: ReadWrite
          x-order: 2
        provider:
          allOf:
            - $ref: '#/components/schemas/CatalogProvider'
          description: The Sail catalog provider type.
          x-access-type: ReadImmutable
          x-order: 3
        config:
          allOf:
            - $ref: '#/components/schemas/CatalogConfigRead'
          description: Provider-specific catalog configuration (read operations, secrets redacted).
          x-access-type: ReadOnly
          x-order: 4
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this catalog was created.
          x-access-type: ReadOnly
          x-order: 5
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this catalog.
          x-access-type: ReadOnly
          x-order: 6
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this catalog was last updated.
          x-access-type: ReadOnly
          x-order: 7
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this catalog.
          x-access-type: ReadOnly
          x-order: 8
    CatalogTeamList:
      type: object
      description: A list of catalog-team associations.
      required:
        - items
      properties:
        items:
          type: array
          description: Array of catalog-team association summaries.
          items:
            $ref: '#/components/schemas/CatalogTeamSummary'
    CatalogTeamSummary:
      type: object
      description: A summary of a catalog-team association.
      required:
        - catalogId
        - teamId
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        catalogId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The catalog ID.
          x-access-type: ReadImmutable
          x-order: 1
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team ID.
          x-access-type: ReadImmutable
          x-order: 2
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this association was created.
          x-access-type: ReadOnly
          x-order: 3
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this association.
          x-access-type: ReadOnly
          x-order: 4
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this association was last updated.
          x-access-type: ReadOnly
          x-order: 5
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this association.
          x-access-type: ReadOnly
          x-order: 6
    CatalogUpdate:
      type: object
      description: An update to a catalog.
      x-filter-group: Update
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The catalog name.
          x-access-type: ReadWrite
          x-order: 2
        configWrite:
          allOf:
            - $ref: '#/components/schemas/CatalogConfigWrite'
          description: Provider-specific catalog configuration (write operations). Secret fields are optional; omit to keep the existing value.
          x-access-type: WriteOnly
          x-order: 4
    ChangePasswordSpec:
      type: object
      description: The specification to change a password.
      required:
        - currentPassword
        - newPassword
      properties:
        currentPassword:
          allOf:
            - $ref: '#/components/schemas/Password'
          description: The current password.
          x-order: 1
        newPassword:
          allOf:
            - $ref: '#/components/schemas/Password'
          description: The new password.
          x-order: 2
    CloudProvider:
      type: string
      description: Cloud provider type
      enum:
        - AWS
    ClusterExpanded:
      type: object
      description: A summary of a Kubernetes cluster with optional external cluster information.
      required:
        - id
        - name
        - createdAt
        - updatedAt
      allOf:
        - $ref: '#/components/schemas/ClusterSummary'
        - type: object
          properties:
            externalClusterId:
              allOf:
                - $ref: '#/components/schemas/ResourceId'
              description: The ID of the linked external cluster resource. Only present for clusters backed by an external cluster.
            region:
              type: string
              description: AWS region where the cluster is deployed. Only present for clusters backed by an external cluster.
              example: us-east-1
            connectionId:
              allOf:
                - $ref: '#/components/schemas/ResourceId'
              description: External connection ID for the cluster's cloud account. Only present for clusters backed by an external cluster.
            networkId:
              allOf:
                - $ref: '#/components/schemas/ResourceId'
              description: External network ID for the cluster's cloud network. Only present for clusters backed by an external cluster.
            externalStatus:
              allOf:
                - $ref: '#/components/schemas/ExternalClusterStatus'
              description: The provisioning status of the external cluster. Only present for clusters backed by an external cluster resource.
            operationId:
              allOf:
                - $ref: '#/components/schemas/ResourceId'
              nullable: true
              description: The ID of the current long-running operation (provisioning or destroying). Only present when an operation is in progress.
    ClusterExpandedList:
      type: object
      description: A normalized list of Kubernetes clusters with external cluster information.
      required:
        - total
        - items
        - included
      properties:
        total:
          type: integer
          description: The total number of clusters found.
          x-order: 1
        items:
          type: array
          description: Cluster references with ID information.
          items:
            $ref: '#/components/schemas/ClusterItem'
          x-order: 2
        included:
          allOf:
            - $ref: '#/components/schemas/ClusterIncluded'
          x-order: 3
    ClusterIncluded:
      type: object
      description: Related entities for a cluster list response.
      required:
        - clusters
      properties:
        clusters:
          type: array
          description: Cluster details referenced by items.
          items:
            $ref: '#/components/schemas/ClusterExpanded'
          x-order: 1
        connections:
          type: array
          description: External connections referenced by clusters.
          items:
            $ref: '#/components/schemas/ExternalConnectionSummary'
          x-order: 2
        networks:
          type: array
          description: External networks referenced by clusters.
          items:
            $ref: '#/components/schemas/ExternalNetworkSummary'
          x-order: 3
        externalClusters:
          type: array
          description: External cluster resources linked to clusters.
          items:
            $ref: '#/components/schemas/ExternalClusterSummary'
          x-order: 4
    ClusterItem:
      type: object
      description: Cluster reference containing only identifier fields (no full cluster details).
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The unique identifier for the cluster.
          x-order: 1
        externalClusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The linked external cluster ID, if present.
          x-order: 2
        connectionId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The associated external connection ID, if present.
          x-order: 3
    ClusterNormalized:
      type: object
      description: Cluster details with related entities.
      required:
        - item
        - included
      properties:
        item:
          allOf:
            - $ref: '#/components/schemas/ClusterItem'
          description: The cluster with entity ID references.
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/ClusterIncluded'
          description: Related entities referenced by IDs in the response.
          x-order: 2
    ClusterSummary:
      type: object
      description: A summary of a Kubernetes cluster.
      required:
        - id
        - name
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The cluster name.
          x-access-type: ReadWrite
          x-order: 2
        createdAt:
          type: string
          format: date-time
          description: The time when the cluster was created.
          x-access-type: ReadOnly
          x-order: 4
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this cluster.
          x-access-type: ReadOnly
          x-order: 5
        updatedAt:
          type: string
          format: date-time
          description: The time when the cluster was last updated.
          x-access-type: ReadOnly
          x-order: 6
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this cluster.
          x-access-type: ReadOnly
          x-order: 7
    ConcurrencyPolicy:
      type: string
      enum:
        - skip
        - allow
        - replace
      description: |
        The concurrency policy when a scheduled run overlaps with an already-running run:
        - `skip`: Skip this tick if any run is in a non-terminal state.
        - `allow`: Allow up to `maxConcurrentRuns` parallel runs.
        - `replace`: Cancel the running run and start a new one.
      example: skip
    CurrentIdentity:
      type: object
      description: |
        The current identity that makes the API request.
      properties:
        root:
          type: object
          description: The API request is made using a root key.
          x-order: 1
        user:
          allOf:
            - $ref: '#/components/schemas/User'
          description: The API request is made by a user.
          x-order: 2
        serviceAccount:
          allOf:
            - $ref: '#/components/schemas/ServiceAccount'
          description: The API request is made by a service account.
          x-order: 3
    CurrentIdentityTeamList:
      type: object
      description: A list of teams the current identity belongs to.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of teams.
          items:
            $ref: '#/components/schemas/TeamSummary'
          x-order: 1
    DCRCapability:
      type: object
      description: DCR (Dynamic Client Registration) capabilities
      required:
        - supported
        - requiresToken
      properties:
        supported:
          type: boolean
          description: Whether the provider supports DCR
        requiresToken:
          type: boolean
          description: Whether DCR requires an authentication token
        tokenType:
          type: string
          description: Type of token required (e.g., initial_access_token, m2m_token, api_token)
    EBSConfig:
      type: object
      description: EBS volume configuration for node storage.
      properties:
        volumeType:
          allOf:
            - $ref: '#/components/schemas/EBSVolumeType'
          description: The EBS volume type.
          x-order: 1
        volumeSize:
          type: integer
          minimum: 1
          maximum: 256000
          default: 100
          description: The EBS volume size in GB.
          example: 100
          x-order: 2
        iops:
          type: integer
          minimum: 3000
          maximum: 256000
          default: 3000
          description: 'Provisioned IOPS per volume. gp3 max: 80,000 (baseline 3000 free). io2 max: 256,000.'
          x-order: 3
        throughput:
          type: integer
          minimum: 125
          maximum: 4000
          default: 125
          description: 'Provisioned throughput per volume in MB/s. gp3 max: 2,000 (baseline 125 free). io2 max: 4,000.'
          x-order: 4
        deleteOnTermination:
          type: boolean
          default: true
          description: 'Whether the volume is deleted when the node is terminated. WARNING: Setting to false will leave orphaned EBS volumes that incur ongoing storage charges.'
          x-order: 5
    EBSVolumeType:
      type: string
      enum:
        - gp3
        - io2
      default: gp3
      description: The EBS volume type.
    EmailAddress:
      type: string
      description: An email address.
      format: email
      maxLength: 320
      example: alice@example.com
    Error:
      type: object
      description: An error returned from an API operation.
      required:
        - message
      properties:
        message:
          type: string
          description: An error message.
          example: An error occurred.
          x-order: 1
    ExternalCatalogConfig:
      type: object
      description: Provider-specific catalog configuration.
      required:
        - catalogName
      properties:
        catalogName:
          type: string
          description: The name of the catalog. Used to name the underlying provider resource (e.g., Glue database).
          example: default
          x-order: 1
    ExternalCatalogStatus:
      type: string
      description: The status of an external catalog.
      enum:
        - pending
        - provisioning
        - failed
        - active
        - destroying
        - destroyed
        - deleted
    ExternalCatalogSummary:
      type: object
      description: A summary of an external catalog.
      required:
        - id
        - connectionId
        - networkId
        - name
        - region
        - config
        - status
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The catalog ID.
          x-access-type: ReadOnly
          x-order: 1
        connectionId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The external connection ID.
          x-access-type: ReadImmutable
          x-order: 2
        networkId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The external network ID this catalog belongs to.
          x-access-type: ReadImmutable
          x-order: 3
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The catalog name.
          x-access-type: ReadWrite
          x-order: 4
        region:
          type: string
          minLength: 1
          maxLength: 50
          description: The cloud provider region where the catalog is provisioned.
          example: us-east-1
          x-access-type: ReadOnly
          x-order: 5
        config:
          allOf:
            - $ref: '#/components/schemas/ExternalCatalogConfig'
          description: Provider-specific catalog configuration.
          x-access-type: ReadImmutable
          x-order: 6
        iacState:
          allOf:
            - $ref: '#/components/schemas/ExternalResourceIacState'
          description: Infrastructure as Code state information.
          x-access-type: ReadOnly
          x-order: 7
        iacOutputs:
          type: object
          additionalProperties: true
          description: Infrastructure as Code stack outputs (database name, etc.).
          x-access-type: ReadOnly
          x-order: 8
        status:
          allOf:
            - $ref: '#/components/schemas/ExternalCatalogStatus'
          description: The catalog status.
          x-access-type: ReadOnly
          x-order: 9
        statusMessage:
          type: string
          nullable: true
          description: Additional status information.
          x-access-type: ReadOnly
          x-order: 10
        createdAt:
          type: string
          format: date-time
          description: The time when the catalog was created.
          x-access-type: ReadOnly
          x-order: 11
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this catalog.
          x-access-type: ReadOnly
          x-order: 12
        updatedAt:
          type: string
          format: date-time
          description: The time when the catalog was last updated.
          x-access-type: ReadOnly
          x-order: 13
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this catalog.
          x-access-type: ReadOnly
          x-order: 14
        catalogId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: The ID of the managed catalog linked to this external catalog (set when provisioned).
          x-access-type: ReadOnly
          x-order: 15
    ExternalClusterCapacity:
      type: object
      description: Provider-specific cluster system resource requirements for capacity planning
      oneOf:
        - $ref: '#/components/schemas/ExternalClusterCapacityAws'
    ExternalClusterCapacityAws:
      type: object
      description: |
        AWS EKS cluster system resource requirements for capacity planning. Used by consumers to validate that a system node group configuration has sufficient pod slots and CPU for EKS system components and Karpenter.
      required:
        - provider
        - systemPodsPerNode
        - systemPodsPerSystemNode
        - systemPodsFixed
        - systemPodsPerNodeMargin
        - systemPodsFixedMargin
        - systemMilliCPUPerNode
        - systemMilliCPUFixed
        - karpenterMilliCPUPerReplica
        - karpenterReplicas
      properties:
        provider:
          allOf:
            - $ref: '#/components/schemas/CloudProvider'
            - enum:
                - AWS
        systemPodsPerNode:
          type: integer
          description: |
            Number of kube-system DaemonSet pods deployed to every node (all node types), e.g. vpc-cni, kube-proxy, ebs-csi-node, cloudwatch-agent, fluent-bit. Multiply by total node count and add systemPodsFixed to get the base system pod count.
        systemPodsPerSystemNode:
          type: integer
          description: |
            Number of additional pods on each system node group node beyond the standard DaemonSet pods (systemPodsPerNode). These are static pods injected via EC2 user data (e.g. konnectivity-bootstrap) that do NOT run on Karpenter nodes. Add to systemPodsPerNode when computing thresholds for the system node group.
        systemPodsFixed:
          type: integer
          description: |
            Number of kube-system Deployment replicas that run cluster-wide regardless of node count (e.g. coredns×2, karpenter×2). Add to (systemPodsPerNode + systemPodsPerSystemNode) × systemNodeCount to get the total expected system pod count.
        systemPodsPerNodeMargin:
          type: integer
          description: |
            Minimum free pod slots required per node beyond the system pod count. Use to ensure at least this many non-system pods can be scheduled per node.
        systemPodsFixedMargin:
          type: integer
          description: |
            Additional fixed pod headroom required cluster-wide beyond the fixed system pod count.
        systemMilliCPUPerNode:
          type: integer
          description: |
            Total millicores requested by DaemonSet pods on every node (e.g. vpc-cni 50m + kube-proxy 100m + ebs-csi-node 30m). Multiply by node count and add systemMilliCPUFixed to estimate the base CPU demand.
        systemMilliCPUFixed:
          type: integer
          description: |
            Total millicores requested by fixed cluster-wide Deployment pods, excluding Karpenter controllers (e.g. coredns×2, ebs-csi-controller×2, konnectivity-agent). Add to systemMilliCPUPerNode × nodeCount to get the total non-Karpenter CPU demand.
        karpenterMilliCPUPerReplica:
          type: integer
          description: |
            Millicores requested per Karpenter controller replica (requests == limits, Guaranteed QoS). Multiply by karpenterReplicas to get full HA CPU demand for Karpenter.
        karpenterReplicas:
          type: integer
          description: |
            Desired number of Karpenter controller replicas for high availability. Full HA requires sufficient CPU capacity on the system node group. If CPU is insufficient, the cluster will start with degraded health status.
    ExternalClusterConfig:
      type: object
      description: Provider-specific cluster configuration
      oneOf:
        - $ref: '#/components/schemas/ExternalClusterConfigAws'
    ExternalClusterConfigAws:
      type: object
      description: AWS EKS-specific cluster configuration
      properties:
        kubernetesVersion:
          type: string
          description: The Kubernetes version (e.g., "1.35"). If not specified, defaults to the latest supported version.
          example: '1.35'
          x-order: 1
        systemNodeGroup:
          type: object
          description: EKS managed node group configuration for system components (e.g., Karpenter, CoreDNS, etc...).
          allOf:
            - $ref: '#/components/schemas/ExternalNodeGroupConfigAws'
          x-order: 2
        publicAccessCidrs:
          type: array
          description: List of CIDR blocks that can access the public EKS API endpoint. Used when creating a new VPC or when vpcId is not specified.
          items:
            type: string
          x-order: 3
    ExternalClusterHealth:
      type: object
      required:
        - status
        - nodeGroups
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterHealthStatus'
          description: Overall health status
        providerMetadata:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterHealthProviderMetadata'
          description: Provider-specific cluster health metadata
          nullable: true
        nodeGroups:
          type: array
          items:
            $ref: '#/components/schemas/ExternalClusterHealthNodeGroup'
        systemPods:
          type: array
          description: Health status of core system pods in kube-system namespace
          items:
            $ref: '#/components/schemas/ExternalClusterHealthSystemPod'
        totalNodes:
          type: integer
          description: Total number of nodes in the cluster
        readyNodes:
          type: integer
          description: Number of nodes in Ready condition
        lastCheckedAt:
          type: string
          format: date-time
          description: Timestamp of the health check
      x-filter-group: Full
    ExternalClusterHealthNodeGroup:
      type: object
      description: Health information for an EKS node group
      required:
        - name
        - status
        - desiredSize
        - readyNodes
      properties:
        name:
          type: string
          description: Node group name
        status:
          type: string
          description: Node group status from AWS EKS
        desiredSize:
          type: integer
          description: Desired number of nodes in the group
        readyNodes:
          type: integer
          description: Number of nodes that are ready
        message:
          type: string
          description: Status message if node group is unhealthy
    ExternalClusterHealthProviderMetadata:
      type: object
      description: Provider-specific cluster health metadata
      oneOf:
        - $ref: '#/components/schemas/ExternalClusterHealthProviderMetadataAws'
    ExternalClusterHealthProviderMetadataAws:
      type: object
      description: AWS EKS-specific cluster health metadata
      properties:
        status:
          type: string
          description: EKS cluster status from AWS (e.g., ACTIVE, CREATING, DELETING)
          example: ACTIVE
          x-order: 1
    ExternalClusterHealthStatus:
      type: string
      description: Overall health status of an external cluster
      enum:
        - healthy
        - degraded
        - unhealthy
        - unknown
    ExternalClusterHealthSystemPod:
      type: object
      description: Health status of a system pod in the kube-system namespace
      required:
        - name
        - namespace
        - ready
        - phase
      properties:
        name:
          type: string
          description: Pod name
        namespace:
          type: string
          description: Pod namespace
        ready:
          type: boolean
          description: Whether the pod is ready
        phase:
          type: string
          description: Pod phase (Running, Pending, Failed, etc.)
        restartCount:
          type: integer
          description: Total restart count across all containers
        message:
          type: string
          description: Status message if pod is unhealthy
    ExternalClusterIncluded:
      type: object
      description: Related entities for an external cluster response.
      required:
        - clusters
        - connections
        - operations
      properties:
        clusters:
          type: array
          description: External clusters referenced by connections.
          items:
            $ref: '#/components/schemas/ExternalClusterSummary'
          x-order: 1
        connections:
          type: array
          description: External connections referenced by clusters.
          items:
            $ref: '#/components/schemas/ExternalConnectionSummary'
          x-order: 2
        operations:
          type: array
          description: Active operations for the listed clusters.
          items:
            $ref: '#/components/schemas/OperationSummary'
          x-order: 3
    ExternalClusterItem:
      type: object
      description: External cluster reference with ID only.
      required:
        - id
        - connectionId
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The unique identifier for the external cluster.
          x-order: 1
        connectionId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The associated external connection ID.
          x-order: 2
    ExternalClusterKubeconfig:
      type: object
      description: Kubeconfig for an external cluster.
      required:
        - kubeconfig
      properties:
        kubeconfig:
          type: string
          description: The kubeconfig content in YAML format.
        clusterEndpoint:
          type: string
          description: The EKS cluster API endpoint.
        clusterCertificateAuthority:
          type: string
          description: The base64-encoded cluster certificate authority data.
    ExternalClusterList:
      type: object
      description: A list of External clusters.
      required:
        - total
        - items
        - included
      properties:
        total:
          type: integer
          description: The total number of external clusters found.
          x-order: 1
        items:
          type: array
          description: A page of external cluster search results with ID references.
          items:
            $ref: '#/components/schemas/ExternalClusterItem'
          x-order: 2
        included:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterIncluded'
          x-order: 3
        marker:
          type: string
          description: The pagination token to request more items.
          nullable: true
          x-order: 4
    ExternalClusterMetrics:
      type: object
      description: Metrics for an external cluster.
      required:
        - cpuUtilization
        - memoryUtilization
        - estimatedCost
      properties:
        cpuUtilization:
          type: array
          description: CPU utilization percentage over time (average across all nodes).
          items:
            $ref: '#/components/schemas/MetricDataPoint'
          x-access-type: ReadOnly
        memoryUtilization:
          type: array
          description: Memory utilization percentage over time (average across all nodes).
          items:
            $ref: '#/components/schemas/MetricDataPoint'
          x-access-type: ReadOnly
        estimatedCost:
          type: array
          description: Estimated daily cost in USD for the cluster resources.
          items:
            $ref: '#/components/schemas/MetricDataPoint'
          x-access-type: ReadOnly
        activeJobCount:
          type: array
          description: Number of active LakeSail jobs running on the cluster.
          items:
            $ref: '#/components/schemas/MetricDataPoint'
          x-access-type: ReadOnly
    ExternalClusterNormalized:
      type: object
      description: External cluster details with connection information.
      required:
        - item
        - included
      properties:
        item:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterItem'
          description: The external cluster details with entity ID references.
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterIncluded'
          description: Related entities referenced by IDs in the response.
          x-order: 2
    ExternalClusterProviderMetadata:
      type: object
      description: Provider-specific cluster metadata
      oneOf:
        - $ref: '#/components/schemas/ExternalClusterProviderMetadataAws'
    ExternalClusterProviderMetadataAws:
      type: object
      description: AWS EKS-specific cluster metadata
      required:
        - clusterName
        - clusterArn
      properties:
        clusterName:
          type: string
          description: EKS cluster name in AWS
          x-order: 1
        clusterArn:
          type: string
          description: EKS cluster ARN
          x-order: 2
    ExternalClusterSpec:
      type: object
      description: The specification to create an external cluster.
      required:
        - connectionId
        - networkId
        - name
        - region
        - config
      x-filter-group: Spec
      properties:
        connectionId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the external connection that owns this cluster.
          x-access-type: ReadImmutable
          x-order: 2
        networkId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the external network this cluster is deployed into.
          x-access-type: ReadImmutable
          x-order: 3
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The cluster name.
          x-access-type: ReadWrite
          x-order: 5
        region:
          type: string
          minLength: 1
          maxLength: 50
          description: The cloud provider region where the cluster is provisioned.
          example: us-east-1
          x-access-type: ReadImmutable
          x-order: 6
        config:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterConfig'
          description: Provider-specific cluster configuration (Kubernetes version, node groups, etc.).
          x-access-type: ReadWrite
          x-order: 9
    ExternalClusterStatus:
      type: string
      description: The status of an external cluster.
      enum:
        - pending
        - provisioning
        - failed
        - active
        - updating
        - destroying
        - destroyed
        - deleted
    ExternalClusterSummary:
      type: object
      description: A summary of an external cluster.
      required:
        - id
        - connectionId
        - networkId
        - name
        - region
        - status
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The external cluster ID.
          x-access-type: ReadOnly
          x-order: 1
        connectionId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the external connection that owns this cluster.
          x-access-type: ReadImmutable
          x-order: 2
        networkId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the external network this cluster is deployed into.
          x-access-type: ReadImmutable
          x-order: 3
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the internal LakeSail cluster linked to this external cluster. Set by the system after the cluster record is created.
          nullable: true
          x-access-type: ReadOnly
          x-order: 4
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The cluster name.
          x-access-type: ReadWrite
          x-order: 5
        region:
          type: string
          minLength: 1
          maxLength: 50
          description: The cloud provider region where the cluster is provisioned.
          example: us-east-1
          x-access-type: ReadImmutable
          x-order: 6
        status:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterStatus'
          description: The cluster status.
          x-access-type: ReadOnly
          x-order: 7
        statusMessage:
          type: string
          nullable: true
          description: Additional status information.
          x-access-type: ReadOnly
          x-order: 8
        config:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterConfig'
          description: Provider-specific cluster configuration (Kubernetes version, node groups, etc.).
          x-access-type: ReadWrite
          x-order: 9
        providerMetadata:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterProviderMetadata'
          description: Provider-specific cluster metadata (read-only, system-generated).
          nullable: true
          x-access-type: ReadOnly
          x-order: 10
        iacState:
          allOf:
            - $ref: '#/components/schemas/ExternalResourceIacState'
          description: Infrastructure as Code state information.
          x-access-type: ReadOnly
          x-order: 11
        iacOutputs:
          type: object
          additionalProperties: true
          description: Infrastructure as Code stack outputs (Pulumi/Terraform outputs).
          x-access-type: ReadOnly
          x-order: 12
        jobRunnerRoleArn:
          type: string
          maxLength: 2048
          description: |
            The IAM role ARN used by the job runner pods in this cluster.
            Grant this ARN read access on any AWS resources (S3 buckets, Glue databases, etc.)
            that jobs running on this cluster need to access.
          example: arn:aws:iam::123456789012:role/lakesail-conn1234-clus5678-jr
          x-access-type: ReadOnly
          x-order: 13
        createdAt:
          type: string
          format: date-time
          description: The time when the cluster was created.
          x-access-type: ReadOnly
          x-order: 14
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this cluster.
          x-access-type: ReadOnly
          x-order: 15
        updatedAt:
          type: string
          format: date-time
          description: The time when the cluster was last updated.
          x-access-type: ReadOnly
          x-order: 16
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this cluster.
          x-access-type: ReadOnly
          x-order: 17
        lastHealthStatus:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterHealthStatus'
          nullable: true
          description: The last known health status of the cluster. Set after provisioning and updated by the background health check job.
          x-access-type: ReadOnly
          x-order: 18
        lastHealthMessage:
          type: string
          maxLength: 1023
          nullable: true
          description: A human-readable message explaining the current health status, present when the cluster is degraded or unhealthy.
          x-access-type: ReadOnly
          x-order: 19
        lastHealthCheckAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the cluster health was last checked.
          x-access-type: ReadOnly
          x-order: 20
    ExternalClusterUpdate:
      type: object
      description: A summary of an external cluster.
      required:
        - name
      x-filter-group: Update
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The cluster name.
          x-access-type: ReadWrite
          x-order: 5
        config:
          allOf:
            - $ref: '#/components/schemas/ExternalClusterConfig'
          description: Provider-specific cluster configuration (Kubernetes version, node groups, etc.).
          x-access-type: ReadWrite
          x-order: 9
    ExternalConnection:
      type: object
      description: An external connection.
      required:
        - id
        - name
        - provider
        - providerConfig
        - status
        - createdAt
        - updatedAt
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The connection ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The connection name.
          x-access-type: ReadWrite
          x-order: 2
        provider:
          allOf:
            - $ref: '#/components/schemas/CloudProvider'
          description: The cloud provider type.
          x-access-type: ReadImmutable
          x-order: 3
        providerConfig:
          allOf:
            - $ref: '#/components/schemas/ExternalConnectionProviderConfig'
          description: Provider-specific connection configuration.
          x-access-type: ReadWrite
          x-order: 4
        status:
          allOf:
            - $ref: '#/components/schemas/ExternalConnectionStatus'
          description: The connection status.
          x-access-type: ReadOnly
          x-order: 5
        statusMessage:
          type: string
          nullable: true
          description: Additional status information.
          x-access-type: ReadOnly
          x-order: 6
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the connection was last successfully used (role assumption succeeded).
          x-access-type: ReadOnly
          x-order: 7
        templateSyncedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the CloudFormation stack was last successfully synced to the current template.
          x-access-type: ReadOnly
          x-order: 8
        templateSyncMessage:
          type: string
          maxLength: 1023
          nullable: true
          description: The error message from the last failed template sync, or null if the last sync succeeded.
          x-access-type: ReadOnly
          x-order: 9
        createdAt:
          type: string
          format: date-time
          description: The time when the connection was created.
          x-access-type: ReadOnly
          x-order: 10
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this connection.
          x-access-type: ReadOnly
          x-order: 11
        updatedAt:
          type: string
          format: date-time
          description: The time when the connection was last updated.
          x-access-type: ReadOnly
          x-order: 12
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this connection.
          x-access-type: ReadOnly
          x-order: 13
    ExternalConnectionIncluded:
      type: object
      description: Related entities for an external connection list response.
      required:
        - operations
      properties:
        operations:
          type: array
          description: Active operations for the listed connections.
          items:
            $ref: '#/components/schemas/OperationSummary'
          x-order: 1
    ExternalConnectionList:
      type: object
      description: A list of External connections.
      required:
        - items
        - included
      properties:
        items:
          type: array
          description: A list of External connections.
          items:
            $ref: '#/components/schemas/ExternalConnectionSummary'
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/ExternalConnectionIncluded'
          x-order: 2
        marker:
          type: string
          description: The pagination token to request more items.
          nullable: true
          x-order: 3
    ExternalConnectionProviderConfig:
      type: object
      description: Provider-specific connection configuration
      oneOf:
        - $ref: '#/components/schemas/ExternalConnectionProviderConfigAws'
    ExternalConnectionProviderConfigAws:
      type: object
      description: AWS-specific connection configuration
      required:
        - accountId
        - region
        - roleArn
        - externalIdSecretArn
      properties:
        accountId:
          type: string
          description: AWS account ID
          example: '123456789012'
          x-order: 1
        region:
          type: string
          description: AWS region
          example: us-east-1
          x-order: 2
        roleArn:
          type: string
          description: IAM role ARN to assume in customer account
          example: arn:aws:iam::123456789012:role/LakeSailConnection
          x-order: 3
        externalIdSecretArn:
          type: string
          description: ARN of the secret containing the external ID for role assumption
          example: arn:aws:secretsmanager:us-east-1:123456789012:secret:lakesail-ext-id
          x-order: 4
        stackArn:
          type: string
          description: ARN of the CloudFormation stack that provisioned this connection
          example: arn:aws:cloudformation:us-east-1:123456789012:stack/lakesail-connection/abc123
          x-order: 5
    ExternalConnectionSpec:
      type: object
      description: The specification to create an external connection.
      required:
        - provider
        - providerConfig
      x-filter-group: Spec
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The connection name.
          x-access-type: ReadWrite
          x-order: 2
        provider:
          allOf:
            - $ref: '#/components/schemas/CloudProvider'
          description: The cloud provider type.
          x-access-type: ReadImmutable
          x-order: 3
        providerConfig:
          allOf:
            - $ref: '#/components/schemas/ExternalConnectionProviderConfig'
          description: Provider-specific connection configuration.
          x-access-type: ReadWrite
          x-order: 4
    ExternalConnectionStatus:
      type: string
      description: The status of an external connection.
      enum:
        - pending
        - verifying
        - active
        - failed
        - disconnected
        - deleted
      example: active
    ExternalConnectionSummary:
      type: object
      description: A summary of an external connection.
      required:
        - id
        - name
        - provider
        - status
        - createdAt
        - updatedAt
        - providerConfig
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The connection ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The connection name.
          x-access-type: ReadWrite
          x-order: 2
        provider:
          allOf:
            - $ref: '#/components/schemas/CloudProvider'
          description: The cloud provider type.
          x-access-type: ReadImmutable
          x-order: 3
        providerConfig:
          allOf:
            - $ref: '#/components/schemas/ExternalConnectionProviderConfig'
          description: Provider-specific connection configuration.
          x-access-type: ReadWrite
          x-order: 4
        status:
          allOf:
            - $ref: '#/components/schemas/ExternalConnectionStatus'
          description: The connection status.
          x-access-type: ReadOnly
          x-order: 5
        statusMessage:
          type: string
          nullable: true
          description: Additional status information.
          x-access-type: ReadOnly
          x-order: 6
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the connection was last successfully used (role assumption succeeded).
          x-access-type: ReadOnly
          x-order: 7
        templateSyncedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the CloudFormation stack was last successfully synced to the current template.
          x-access-type: ReadOnly
          x-order: 8
        templateSyncMessage:
          type: string
          maxLength: 1023
          nullable: true
          description: The error message from the last failed template sync, or null if the last sync succeeded.
          x-access-type: ReadOnly
          x-order: 9
        createdAt:
          type: string
          format: date-time
          description: The time when the connection was created.
          x-access-type: ReadOnly
          x-order: 10
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this connection.
          x-access-type: ReadOnly
          x-order: 11
        updatedAt:
          type: string
          format: date-time
          description: The time when the connection was last updated.
          x-access-type: ReadOnly
          x-order: 12
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this connection.
          x-access-type: ReadOnly
          x-order: 13
    ExternalConnectionTemplate:
      type: object
      description: CloudFormation template information for an external connection.
      required:
        - templateUrl
        - parameters
      properties:
        templateUrl:
          type: string
          description: URL to the CloudFormation template.
        quickLaunchUrl:
          type: string
          description: AWS Console quick-launch URL with pre-filled parameters.
        downloadUrl:
          type: string
          description: URL to download the CloudFormation template with parameter defaults pre-filled (for manual upload).
        parameters:
          type: object
          description: Template parameters to use.
          properties:
            ConnectionId:
              type: string
            LakeSailPrincipal:
              type: string
            ExternalId:
              type: string
              description: The external ID (only shown once at creation).
    ExternalConnectionUpdate:
      type: object
      description: The specification to update an external connection.
      x-filter-group: Update
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The connection name.
          x-access-type: ReadWrite
          x-order: 2
        providerConfig:
          allOf:
            - $ref: '#/components/schemas/ExternalConnectionProviderConfig'
          description: Provider-specific connection configuration.
          x-access-type: ReadWrite
          x-order: 4
    ExternalConnectionVerifySpec:
      type: object
      description: The specification to verify an external connection.
      required:
        - roleArn
      properties:
        roleArn:
          type: string
          description: The IAM role ARN in the customer AWS account.
      x-filter-group: Spec
    ExternalInstanceType:
      type: object
      description: Provider-specific instance type information
      oneOf:
        - $ref: '#/components/schemas/ExternalInstanceTypeAws'
    ExternalInstanceTypeAws:
      type: object
      description: AWS EC2 instance type information
      required:
        - provider
        - instanceType
        - vCpus
        - memoryMiB
        - architecture
        - maxPods
        - allocatableMilliCpu
      properties:
        provider:
          allOf:
            - $ref: '#/components/schemas/CloudProvider'
            - enum:
                - AWS
          x-order: 1
        instanceType:
          type: string
          description: The instance type name (e.g., m5.xlarge)
          x-order: 2
        vCpus:
          type: integer
          description: Number of vCPUs
          x-order: 3
        memoryMiB:
          type: integer
          description: Memory in MiB
          x-order: 4
        architecture:
          type: string
          description: Processor architecture (e.g., x86_64, arm64)
          x-order: 5
        gpuCount:
          type: integer
          description: Number of GPUs (0 if none)
          x-order: 6
        instanceFamily:
          type: string
          description: Instance family (e.g., m5, r6i, c7g)
          x-order: 7
        maxPods:
          type: integer
          description: |
            Maximum number of pods this instance type can run, using the EKS VPC CNI formula: (maxENIs × (ipv4PerENI − 1)) + 2. Each ENI's primary IP is reserved for the node itself (−1 per ENI); aws-node and kube-proxy run on the host network and don't consume a pod IP (+2). The result is capped at 110 for instances with ≤ 30 vCPUs and 250 for > 30 vCPUs, matching the kubelet --max-pods ceiling enforced by EKS node bootstrap scripts.
          x-order: 8
        group:
          type: string
          description: Grouping category for UI organization (e.g., "General Purpose", "Compute Optimized")
          x-order: 9
        allocatableMilliCpu:
          type: integer
          description: |
            Approximate allocatable millicores per node after subtracting the EKS kubelet CPU reservation (50m + 10m × vCPUs). Computed server-side so callers do not need to replicate the formula.
          x-order: 10
    ExternalInstanceTypeList:
      type: object
      required:
        - items
        - metadata
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExternalInstanceType'
        metadata:
          $ref: '#/components/schemas/ExternalClusterCapacity'
    ExternalNetworkConfig:
      type: object
      description: Provider-specific network configuration
      oneOf:
        - $ref: '#/components/schemas/ExternalNetworkConfigAws'
    ExternalNetworkConfigAws:
      type: object
      description: AWS VPC-specific network configuration (input only - outputs in iacOutputs and providerNetworkId)
      required:
        - cidr
      properties:
        cidr:
          type: string
          description: |
            The CIDR block for the network (e.g., 10.0.0.0/16). Must not intersect with the VPC CIDR block used by the LakeSail platform.
          example: 10.0.0.0/16
          x-order: 1
    ExternalNetworkIncluded:
      type: object
      description: Related entities for a managed external network response.
      required:
        - networks
        - connections
        - clusters
        - operations
      properties:
        networks:
          type: array
          description: Managed external networks referenced by connections.
          items:
            $ref: '#/components/schemas/ExternalNetworkSummary'
          x-order: 1
        connections:
          type: array
          description: External connections referenced by networks.
          items:
            $ref: '#/components/schemas/ExternalConnectionSummary'
          x-order: 2
        clusters:
          type: array
          description: External clusters belonging to the listed networks.
          items:
            $ref: '#/components/schemas/ExternalClusterSummary'
          x-order: 3
        operations:
          type: array
          description: Active operations for the listed networks.
          items:
            $ref: '#/components/schemas/OperationSummary'
          x-order: 4
    ExternalNetworkItem:
      type: object
      description: Managed external network reference with ID only.
      required:
        - id
        - connectionId
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The unique identifier for the managed external network.
          x-order: 1
        connectionId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The associated external connection ID.
          x-order: 2
    ExternalNetworkList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProviderNetwork'
    ExternalNetworkNormalized:
      type: object
      description: Managed external network details with connection information.
      required:
        - item
        - included
      properties:
        item:
          allOf:
            - $ref: '#/components/schemas/ExternalNetworkItem'
          description: The managed external network details with entity ID references.
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/ExternalNetworkIncluded'
          description: Related entities referenced by IDs in the response.
          x-order: 2
    ExternalNetworkSpec:
      type: object
      description: The specification to create a managed external network.
      required:
        - name
        - region
        - config
        - connectionId
      x-filter-group: Spec
      properties:
        connectionId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The External connection ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The network name.
          x-access-type: ReadWrite
          x-order: 3
        region:
          type: string
          minLength: 1
          maxLength: 50
          description: The cloud provider region where the network is provisioned.
          example: us-east-1
          x-access-type: ReadImmutable
          x-order: 4
        config:
          allOf:
            - $ref: '#/components/schemas/ExternalNetworkConfig'
          description: Provider-specific network configuration (CIDR, network ID, subnets, etc.).
          x-access-type: ReadWrite
          x-order: 6
    ExternalNetworkStatus:
      type: string
      description: The status of a managed external VPC.
      enum:
        - pending
        - provisioning
        - failed
        - active
        - destroying
        - destroyed
        - deleted
    ExternalNetworkSummary:
      type: object
      description: A summary of a managed external network.
      required:
        - id
        - connectionId
        - name
        - region
        - config
        - status
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The network ID.
          x-access-type: ReadOnly
          x-order: 1
        connectionId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The External connection ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The network name.
          x-access-type: ReadWrite
          x-order: 3
        region:
          type: string
          minLength: 1
          maxLength: 50
          description: The cloud provider region where the network is provisioned.
          example: us-east-1
          x-access-type: ReadImmutable
          x-order: 4
        providerNetworkId:
          type: string
          maxLength: 255
          description: Provider-specific network identifier (e.g., vpc-xxx for AWS, self-link for GCP, ARM path for Azure). Populated after provisioning completes.
          example: vpc-0a1b2c3d4e5f6g7h8
          nullable: true
          x-access-type: ReadOnly
          x-order: 5
        config:
          allOf:
            - $ref: '#/components/schemas/ExternalNetworkConfig'
          description: Provider-specific network configuration (CIDR, network ID, subnets, etc.).
          x-access-type: ReadWrite
          x-order: 6
        iacState:
          allOf:
            - $ref: '#/components/schemas/ExternalResourceIacState'
          description: Infrastructure as Code state information.
          x-access-type: ReadOnly
          x-order: 7
        iacOutputs:
          type: object
          additionalProperties: true
          description: Infrastructure as Code stack outputs (network ID, subnet IDs, etc.).
          x-access-type: ReadOnly
          x-order: 8
        status:
          allOf:
            - $ref: '#/components/schemas/ExternalNetworkStatus'
          description: The network status.
          x-access-type: ReadOnly
          x-order: 9
        statusMessage:
          type: string
          nullable: true
          description: Additional status information.
          x-access-type: ReadOnly
          x-order: 10
        createdAt:
          type: string
          format: date-time
          description: The time when the network was created.
          x-access-type: ReadOnly
          x-order: 11
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this network.
          x-access-type: ReadOnly
          x-order: 12
        updatedAt:
          type: string
          format: date-time
          description: The time when the network was last updated.
          x-access-type: ReadOnly
          x-order: 13
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this network.
          x-access-type: ReadOnly
          x-order: 14
    ExternalNetworkUpdate:
      type: object
      description: The specification to update an external network.
      required:
        - name
      x-filter-group: Update
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The network name.
          x-access-type: ReadWrite
          x-order: 3
        config:
          allOf:
            - $ref: '#/components/schemas/ExternalNetworkConfig'
          description: Provider-specific network configuration (CIDR, network ID, subnets, etc.).
          x-access-type: ReadWrite
          x-order: 6
    ExternalNodeGroupConfigAws:
      type: object
      description: Configuration for an AWS EKS managed node group.
      required:
        - name
        - instanceTypes
        - minSize
        - maxSize
        - desiredSize
      properties:
        name:
          type: string
          description: Node group name.
          example: system
          x-order: 1
        instanceTypes:
          type: array
          description: EC2 instance types for this node group.
          items:
            type: string
          example:
            - m7g.large
            - m7g.xlarge
          x-order: 2
        minSize:
          type: integer
          description: Minimum number of nodes.
          minimum: 1
          default: 1
          x-order: 3
        maxSize:
          type: integer
          description: Maximum number of nodes.
          minimum: 1
          default: 3
          x-order: 4
        desiredSize:
          type: integer
          description: Desired number of nodes.
          minimum: 1
          default: 2
          x-order: 5
        diskSizeGb:
          type: integer
          description: EBS volume size in GB.
          default: 100
          x-order: 6
    ExternalRegion:
      type: object
      description: Provider-specific region information
      oneOf:
        - $ref: '#/components/schemas/ExternalRegionAws'
    ExternalRegionAws:
      type: object
      description: AWS region information
      required:
        - provider
        - regionCode
        - regionName
      properties:
        provider:
          allOf:
            - $ref: '#/components/schemas/CloudProvider'
            - enum:
                - AWS
          x-order: 1
        regionCode:
          type: string
          description: The AWS region code (e.g., us-east-1, eu-west-2)
          example: us-east-1
          x-order: 2
        regionName:
          type: string
          description: Human-readable region name with location
          example: US East 1 (N. Virginia)
          x-order: 3
        group:
          type: string
          description: Geographic grouping for UI organization (e.g., "North America", "Europe")
          x-order: 4
    ExternalRegionList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExternalRegion'
    ExternalResourceIacState:
      type: object
      description: Infrastructure as Code state information for the resource (e.g., vpc, cluster, etc.) provisioning.
      properties:
        projectName:
          type: string
          description: The IaC project name (Pulumi project, Terraform workspace, etc.).
          example: lakesail-byoc-cluster
        stackName:
          type: string
          description: The IaC stack name (Pulumi stack, Terraform workspace, etc.).
          example: lakesail-prod-cluster-abc123
      required:
        - projectName
        - stackName
    IdentityProvider:
      type: object
      description: An identity provider.
      required:
        - id
        - name
        - config
        - createdAt
        - updatedAt
        - identityProviderTypeId
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The identity provider ID.
          x-access-type: ReadOnly
          x-order: 1
        identityProviderTypeId:
          allOf:
            - $ref: '#/components/schemas/ResourceCode'
          description: The identity provider type ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The identity provider name.
          x-access-type: ReadWrite
          x-order: 3
        config:
          description: The identity provider configuration.
          x-access-type: ReadOnly
          x-order: 4
          allOf:
            - $ref: '#/components/schemas/IdentityProviderConfigurationRead'
        configWrite:
          description: The identity provider configuration.
          x-access-type: WriteOnly
          x-order: 4
          allOf:
            - $ref: '#/components/schemas/IdentityProviderConfigurationWrite'
        createdAt:
          type: string
          format: date-time
          description: The time when the identity provider was created.
          x-access-type: FullOnly
          x-order: 5
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this identity provider.
          x-access-type: FullOnly
          x-order: 6
        updatedAt:
          type: string
          format: date-time
          description: The time when the identity provider was last updated.
          x-access-type: FullOnly
          x-order: 7
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this identity provider.
          x-access-type: FullOnly
          x-order: 8
    IdentityProviderConfigurationRead:
      type: object
      description: The configuration of an identity provider (read operations).
      properties:
        oidc:
          $ref: '#/components/schemas/IdentityProviderOidcConfigRead'
    IdentityProviderConfigurationWrite:
      type: object
      description: The configuration of an identity provider (write operations).
      properties:
        oidc:
          $ref: '#/components/schemas/IdentityProviderOidcConfigWrite'
    IdentityProviderList:
      type: object
      description: A list of identity providers.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of identity providers.
          items:
            $ref: '#/components/schemas/IdentityProviderSummary'
          x-order: 1
        marker:
          type: string
          description: The pagination token to request more items.
          x-order: 2
    IdentityProviderOidcConfigRead:
      type: object
      description: OIDC configuration for read operations
      properties:
        issuer:
          type: string
          description: The OIDC issuer URL
          x-order: 1
        clientId:
          type: string
          description: The OAuth client ID
          x-order: 2
        clientSecretConfigured:
          type: boolean
          description: Whether a client secret is configured
          x-order: 3
        scopes:
          type: array
          description: The OAuth scopes
          items:
            type: string
          x-order: 4
    IdentityProviderOidcConfigWrite:
      type: object
      description: OIDC configuration for write operations
      required:
        - issuer
        - clientId
        - scopes
      properties:
        issuer:
          type: string
          description: The OIDC issuer URL
          x-order: 1
        clientId:
          type: string
          description: The OAuth client ID
          x-order: 2
        clientSecret:
          type: string
          description: The OAuth client secret. Optional for public clients that use PKCE.
          x-order: 3
        scopes:
          type: array
          description: The OAuth scopes
          items:
            type: string
          x-order: 4
    IdentityProviderSpec:
      type: object
      description: The specification to create an identity provider.
      required:
        - name
        - configWrite
        - identityProviderTypeId
      x-filter-group: Spec
      properties:
        identityProviderTypeId:
          allOf:
            - $ref: '#/components/schemas/ResourceCode'
          description: The identity provider type ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The identity provider name.
          x-access-type: ReadWrite
          x-order: 3
        configWrite:
          description: The identity provider configuration.
          x-access-type: WriteOnly
          x-order: 4
          allOf:
            - $ref: '#/components/schemas/IdentityProviderConfigurationWrite'
    IdentityProviderSummary:
      type: object
      description: A summary of an identity provider.
      required:
        - id
        - name
        - config
        - identityProviderTypeId
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The identity provider ID.
          x-access-type: ReadOnly
          x-order: 1
        identityProviderTypeId:
          allOf:
            - $ref: '#/components/schemas/ResourceCode'
          description: The identity provider type ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The identity provider name.
          x-access-type: ReadWrite
          x-order: 3
        config:
          description: The identity provider configuration.
          x-access-type: ReadOnly
          x-order: 4
          allOf:
            - $ref: '#/components/schemas/IdentityProviderConfigurationRead'
    IdentityProviderTypeList:
      type: object
      description: A list of identity provider types.
      required:
        - items
      properties:
        items:
          type: array
          description: Available identity provider types.
          items:
            $ref: '#/components/schemas/IdentityProviderTypeSummary'
          x-order: 1
    IdentityProviderTypeSummary:
      type: object
      required:
        - id
        - name
        - capabilities
        - enabled
        - visible
        - displayOrder
        - createdAt
        - updatedAt
      x-filter-group: Summary
      description: An identity provider type available for organizations to configure
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceCode'
          description: Unique identifier for the provider type
          x-access-type: ReadImmutable
          x-order: 1
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Display name of the provider
          x-access-type: ReadWrite
          x-order: 2
        description:
          type: string
          minLength: 1
          maxLength: 1023
          description: Description of the provider
          x-access-type: ReadWrite
          x-order: 3
        providerType:
          allOf:
            - $ref: '#/components/schemas/ProviderType'
          description: The provider type, which determines protocol behavior and available features.
          x-access-type: ReadImmutable
          x-order: 4
        capabilities:
          allOf:
            - $ref: '#/components/schemas/ProviderCapabilities'
          description: Capabilities supported by the provider
          x-access-type: ReadOnly
          x-order: 5
        metadata:
          allOf:
            - $ref: '#/components/schemas/ProviderMetadata'
          description: Additional metadata about the provider
          x-access-type: ReadOnly
          x-order: 6
        enabled:
          type: boolean
          description: Whether the provider is enabled (hard disable)
          x-access-type: ReadWrite
          x-order: 7
        visible:
          type: boolean
          description: Whether the provider is visible to new organizations
          x-access-type: ReadWrite
          x-order: 8
        displayOrder:
          type: integer
          description: Display order in UI listings
          x-access-type: ReadWrite
          x-order: 9
        createdAt:
          type: string
          format: date-time
          description: When the provider type was created
          x-access-type: ReadOnly
          x-order: 10
        updatedAt:
          type: string
          format: date-time
          description: When the provider type was last updated
          x-access-type: ReadOnly
          x-order: 11
    IdentityProviderUpdate:
      type: object
      description: The specification to update an identity provider.
      x-filter-group: Update
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: The identity provider name.
          x-access-type: ReadWrite
          x-order: 3
        configWrite:
          description: The identity provider configuration.
          x-access-type: WriteOnly
          x-order: 4
          allOf:
            - $ref: '#/components/schemas/IdentityProviderConfigurationWrite'
    InfraStatus:
      type: string
      description: The infrastructure status of a workload.
      enum:
        - provisioning
        - provisioned
        - provision_failed
        - cleaning
        - cleaned
        - cleanup_failed
    InvitationToken:
      type: string
      description: A invitation token.
      minLength: 20
      allOf:
        - $ref: '#/components/schemas/Base64'
    InviteSpec:
      type: object
      description: Specification for creating an invitation to join an organization.
      required:
        - name
        - email
        - sendEmail
      x-filter-group: Spec
      properties:
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          type: string
          minLength: 1
          maxLength: 127
          description: The user's name
          x-access-type: ReadImmutable
          x-order: 3
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The user's email
          x-access-type: ReadImmutable
          x-order: 4
        organizationRoleId:
          type: string
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization role ID to assign to the invited member.
          nullable: true
          x-access-type: ReadImmutable
          x-order: 5
        accountType:
          allOf:
            - $ref: '#/components/schemas/AccountType'
          description: The account type for the invited member.
          x-access-type: ReadImmutable
          x-order: 6
        teamAssignments:
          type: array
          items:
            $ref: '#/components/schemas/TeamAssignment'
          description: The team assignments for the invited member. Each entry specifies a team and a required team role. When omitted, the member is assigned to the organization's default team with that team's default role.
          x-access-type: WriteOnly
          x-order: 7
        sendEmail:
          type: boolean
          description: Indicates whether to send an invitation email to the invitee after creating.
    InviteSummary:
      type: object
      description: An invitation to join an organization.
      required:
        - organization
        - name
        - email
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization user ID.
          x-access-type: ReadOnly
          x-order: 1
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          type: string
          minLength: 1
          maxLength: 127
          description: The user's name
          x-access-type: ReadImmutable
          x-order: 3
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The user's email
          x-access-type: ReadImmutable
          x-order: 4
        organizationRoleId:
          type: string
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization role ID to assign to the invited member.
          nullable: true
          x-access-type: ReadImmutable
          x-order: 5
        accountType:
          allOf:
            - $ref: '#/components/schemas/AccountType'
          description: The account type for the invited member.
          x-access-type: ReadImmutable
          x-order: 6
        invitationToken:
          allOf:
            - $ref: '#/components/schemas/InvitationToken'
          description: The token used to accept the invite.
          x-access-type: ReadOnly
          x-order: 8
        invitedAt:
          type: string
          format: date-time
          description: The time at which the invite was sent.
          x-access-type: ReadOnly
          x-order: 9
        createdAt:
          type: string
          format: date-time
          description: The time when the invite was created.
          x-access-type: ReadOnly
          x-order: 10
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this invite.
          x-access-type: ReadOnly
          x-order: 11
        expiresAt:
          type: string
          format: date-time
          description: The time when the invite expires.
          x-access-type: ReadOnly
          x-order: 12
        organization:
          $ref: '#/components/schemas/OrganizationSummary'
        inviteUrl:
          type: string
          format: uri
          description: URL to accept the invitation.
    IssueSessionTokenRequestSpec:
      type: object
      description: Options for issuing a session proxy token.
      properties:
        durationSeconds:
          type: integer
          format: int64
          description: 'How long the token should be valid, in seconds. Minimum: 60 (1 minute). Maximum: 7776000 (90 days). Defaults to 28800 (8 hours) when not specified.'
          minimum: 60
          maximum: 7776000
          default: 28800
          x-order: 1
    JobConfig:
      type: object
      description: Job-specific configuration parameters.
      properties:
        sql:
          $ref: '#/components/schemas/JobConfigSql'
        python:
          $ref: '#/components/schemas/JobConfigPython'
        compute:
          allOf:
            - $ref: '#/components/schemas/JobConfigCompute'
          description: Compute configuration for the job execution.
        lakesail:
          allOf:
            - $ref: '#/components/schemas/JobConfigLakeSail'
          description: LakeSail server configuration. See [LakeSail Configuration](https://docs.lakesail.com/sail/latest/reference/configuration/)
    JobConfigCompute:
      type: object
      description: Compute configuration for the job execution.
      oneOf:
        - $ref: '#/components/schemas/JobConfigComputeAws'
    JobConfigComputeAws:
      type: object
      description: AWS compute configuration for the job execution.
      properties:
        driver:
          allOf:
            - $ref: '#/components/schemas/JobConfigComputeAwsDriver'
          description: Configuration for the driver node.
          x-order: 1
        worker:
          allOf:
            - $ref: '#/components/schemas/JobConfigComputeAwsWorker'
          description: Configuration for worker nodes.
          x-order: 2
    JobConfigComputeAwsDriver:
      type: object
      description: Configuration for the driver node.
      properties:
        instanceType:
          type: string
          description: The EC2 instance type (e.g., c8g.2xlarge).
          example: c8g.2xlarge
          x-order: 1
        ebsConfig:
          allOf:
            - $ref: '#/components/schemas/EBSConfig'
          description: EBS volume configuration for the driver node.
          x-order: 2
    JobConfigComputeAwsWorker:
      type: object
      description: Configuration for worker nodes.
      properties:
        instanceType:
          type: string
          description: The EC2 instance type (e.g., c8g.2xlarge).
          example: c8g.4xlarge
          x-order: 1
        ebsConfig:
          allOf:
            - $ref: '#/components/schemas/EBSConfig'
          description: EBS volume configuration for the worker nodes.
          x-order: 2
        maxNodes:
          type: integer
          minimum: 1
          default: 1
          description: The maximum number of worker nodes.
          example: 4
          x-order: 3
        capacityType:
          allOf:
            - $ref: '#/components/schemas/CapacityType'
          description: The capacity type for the worker nodes.
          x-order: 4
    JobConfigLakeSail:
      type: object
      description: LakeSail Job-specific configuration.
      properties:
        executionMode:
          allOf:
            - $ref: '#/components/schemas/JobConfigLakeSailExecutionMode'
          description: Execution mode for the LakeSail server.
          x-order: 1
        maxRetries:
          type: integer
          description: An optional maximum number of times to retry an unsuccessful run. 0 means no retries (default) and -1 means retry indefinitely.
          default: 0
          example: 3
          x-order: 2
        lakesailImageUri:
          type: string
          description: Optional container image URI for the LakeSail engine. If not specified, the default engine image from the platform configuration is used.
          x-order: 3
        libraries:
          type: array
          description: Optional list of libraries to install for the job execution.
          items:
            $ref: '#/components/schemas/JobConfigLakeSailLibrary'
          x-order: 4
      additionalProperties:
        description: LakeSail server configuration and environment variables. See [LakeSail Configuration](https://docs.lakesail.com/sail/latest/reference/configuration/)
        type: string
    JobConfigLakeSailExecutionMode:
      type: string
      enum:
        - standalone
        - cluster
      default: standalone
      description: |
        Execution mode for the LakeSail server.
        In `standalone` mode, LakeSail runs as a single process in one pod, while query execution remains parallelized via threads.
        In `cluster` mode, LakeSail manages a Kubernetes cluster. The driver and workers run in separate pods and communicate with each other via RPC.
    JobConfigLakeSailLibrary:
      type: object
      description: Library specification for a dependency to install for the job execution.
      properties:
        pypi:
          allOf:
            - $ref: '#/components/schemas/JobConfigLakeSailLibraryPypi'
          description: A PyPI package to install.
          x-order: 1
        requirements:
          $ref: '#/components/schemas/JobConfigLakeSailLibraryRequirements'
        whl:
          type: string
          description: URI of the wheel library to install. If S3 is used, please make sure the cluster has read access on the library. You may need to launch the cluster with an IAM role to access the S3 URI.
          x-order: 3
    JobConfigLakeSailLibraryPypi:
      type: object
      description: A PyPI package to install.
      required:
        - package
      properties:
        package:
          type: string
          description: 'The name of the PyPI package to install. An optional exact version specification is also supported. Examples: "pysail" and "pysail==1.2.3".'
          x-order: 1
        repo:
          type: string
          description: The repository where the package can be found. If not specified, the default pip index is used.
          x-order: 2
    JobConfigLakeSailLibraryRequirements:
      description: |
        Requirements specification for library dependencies. Exactly one source variant must be specified,
        determined by the `source` discriminator field:

        - **`uri`**: Install from a requirements.txt file at a URI location (S3, HTTPS).
        - **`text`**: Install from inline requirements.txt content.
      oneOf:
        - $ref: '#/components/schemas/JobConfigLakeSailLibraryRequirementsUri'
        - $ref: '#/components/schemas/JobConfigLakeSailLibraryRequirementsText'
      discriminator:
        propertyName: source
        mapping:
          uri: '#/components/schemas/JobConfigLakeSailLibraryRequirementsUri'
          text: '#/components/schemas/JobConfigLakeSailLibraryRequirementsText'
    JobConfigLakeSailLibraryRequirementsText:
      type: object
      description: Install dependencies from inline requirements.txt content.
      required:
        - source
        - text
      properties:
        source:
          type: string
          description: Discriminator value identifying this as an inline text requirements specification.
          enum:
            - text
          x-order: 0
        text:
          type: string
          description: Inline requirements.txt content. Each line specifies a package requirement (e.g., "pandas>=1.5.0\nnumpy>=1.20").
          x-order: 1
    JobConfigLakeSailLibraryRequirementsUri:
      type: object
      description: Install dependencies from a requirements.txt file at a URI location.
      required:
        - source
        - uri
      properties:
        source:
          type: string
          description: Discriminator value identifying this as a URI-based requirements specification.
          enum:
            - uri
          x-order: 0
        uri:
          type: string
          description: URI pointing to a requirements.txt file (e.g., s3://bucket/requirements.txt, https://example.com/requirements.txt). If S3 is used, please make sure the cluster has read access on the file.
          x-order: 1
    JobConfigPython:
      description: |
        Configuration schema for Python execution jobs. Exactly one Python source variant must be specified,
        determined by the `source` discriminator field:

        - **`pythonWheelJob`**: Run a Python wheel package by specifying a package name and entry point.
        - **`pythonFileJob`**: Run a Python file from a cloud storage URI or workspace path.
      oneOf:
        - $ref: '#/components/schemas/JobConfigPythonWheelJob'
        - $ref: '#/components/schemas/JobConfigPythonFileJob'
      discriminator:
        propertyName: source
        mapping:
          pythonWheelJob: '#/components/schemas/JobConfigPythonWheelJob'
          pythonFileJob: '#/components/schemas/JobConfigPythonFileJob'
    JobConfigPythonFileJob:
      type: object
      description: |
        The job runs a Python file. The file is loaded from a cloud storage URI or workspace path
        at execution time.
      required:
        - source
        - pythonFile
      properties:
        source:
          type: string
          enum:
            - pythonFileJob
          description: Discriminator value identifying this as a Python file job.
          x-order: 0
        pythonFile:
          type: string
          description: |
            The Python file to be executed. Cloud file URIs (such as `s3:/`, `adls:/`, `gcs:/`)
            and workspace paths are supported.
          example: s3:/path/to/file.py
          x-order: 1
        parameters:
          type: array
          items:
            type: string
          description: |
            Command-line parameters passed to the Python file.
            Use job parameter variables to set parameters containing information about job runs.
          example:
            - '--data'
            - s3:/path/to/data.json
          x-order: 2
    JobConfigPythonWheelJob:
      type: object
      description: |
        The job runs a Python wheel. The wheel package is identified by name and an entry point
        is invoked directly. Parameters can be passed as named key-value pairs or as positional
        command-line arguments.
      required:
        - source
        - packageName
        - entryPoint
      properties:
        source:
          type: string
          enum:
            - pythonWheelJob
          description: Discriminator value identifying this as a Python wheel job.
          x-order: 0
        packageName:
          type: string
          description: Name of the package to execute.
          x-order: 1
        entryPoint:
          type: string
          description: |
            Named entry point to use. If it does not exist in the metadata of the package,
            it executes the function from the package directly using `$packageName.$entryPoint()`.
          x-order: 2
        parameters:
          type: array
          items:
            type: string
          description: |
            Command-line parameters passed to the Python wheel job.
            Leave it empty if `namedParameters` is not null.
          example:
            - '--name=job'
            - one
            - two
          x-order: 3
        namedParameters:
          type: object
          additionalProperties:
            type: string
          description: |
            Command-line parameters passed to the Python wheel job in the form of
            `["--name=job", "--data=s3:/path/to/data.json"]`.
            Leave it empty if `parameters` is not null.
          example:
            data: s3:/path/to/data.json
            name: job
          x-order: 4
    JobConfigSql:
      description: |
        Configuration schema for SQL execution jobs. Exactly one SQL source variant must be specified,
        determined by the `source` discriminator field:

        - **`queryRef`**: Execute a saved query by ID. The query text is resolved at execution time.
        - **`file`**: Execute SQL from a file location (workspace or VCS path). NOT SUPPORTED YET
        - **`snapshot`**: Execute inline SQL text, optionally tracking origin for drift detection.
      oneOf:
        - $ref: '#/components/schemas/JobConfigSqlQueryRef'
        - $ref: '#/components/schemas/JobConfigSqlSnapshot'
      discriminator:
        propertyName: source
        mapping:
          queryRef: '#/components/schemas/JobConfigSqlQueryRef'
          snapshot: '#/components/schemas/JobConfigSqlSnapshot'
    JobConfigSqlQueryRef:
      type: object
      description: |
        Execute a saved query by ID. The query text is resolved at execution time,
        so the job always runs the latest version of the saved query.
      required:
        - source
        - queryId
      properties:
        source:
          type: string
          enum:
            - queryRef
          description: Discriminator value identifying this as a live query reference.
          x-order: 0
        queryId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: |
            Reference to a saved query to execute. The query text is resolved at execution time.
          example: Q1R2S3T4U5
          x-order: 1
    JobConfigSqlSnapshot:
      type: object
      description: |
        Execute inline SQL text. This is a snapshot of the query at the time the job version
        was created. When `originQueryId` is also set, the snapshot can be compared
        against the current saved query to detect drift.
      required:
        - source
        - queryText
      properties:
        source:
          type: string
          enum:
            - snapshot
          description: Discriminator value identifying this as an inline SQL snapshot.
          x-order: 0
        queryText:
          type: string
          description: |
            Inline SQL query text to execute. This is a snapshot of the query at the time the job
            version was created. When originating from a saved query, this is copied at save time
            to ensure the job version is self-contained and isolated from subsequent changes to
            the source query.
          example: SELECT * FROM sales WHERE date >= CURRENT_DATE - INTERVAL 1 DAY
          x-order: 1
        originQueryId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: |
            Optional reference to the saved query this SQL was copied from. Used for drift
            detection — when set, the current queryText can be compared with the source
            query to determine whether it has been modified since the snapshot was taken.
          x-order: 2
    JobDependencies:
      type: array
      description: An array of objects specifying the dependency graph of the job. All jobs specified in this field must complete before executing this job.
      items:
        $ref: '#/components/schemas/JobDependency'
    JobDependency:
      type: object
      description: Specification of a job dependency relationship.
      allOf:
        - oneOf:
            - required:
                - jobKey
              properties:
                jobKey:
                  allOf:
                    - $ref: '#/components/schemas/ResourceId'
                  description: The key of the job this job depends on.
                  x-order: 1
            - required:
                - jobId
              properties:
                jobId:
                  allOf:
                    - $ref: '#/components/schemas/ResourceId'
                  description: The ID of the job this job depends on.
                  x-order: 2
        - properties:
            runStateCheck:
              allOf:
                - $ref: '#/components/schemas/JobDependencyRunStateCheck'
              x-order: 3
            groupId:
              allOf:
                - $ref: '#/components/schemas/ResourceId'
              description: Optional group identifier for grouping dependencies together. Required when using GROUP_* run state checks.
              x-order: 4
    JobDependencyRunStateCheck:
      type: string
      enum:
        - MUST_SUCCEED
        - MUST_FAIL
        - GROUP_ALL_SUCCESS
        - GROUP_ALL_FAILED
        - GROUP_AT_LEAST_ONE_SUCCESS
        - GROUP_AT_LEAST_ONE_FAILED
        - GROUP_NONE_FAILED
        - GROUP_ALL_DONE
      description: |
        The condition that determines whether the job is run once this dependency has been completed:

        Individual conditions:
        - MUST_SUCCEED: This specific dependency must succeed
        - MUST_FAIL: This specific dependency must fail

        Group conditions (requires groupId):
        - GROUP_ALL_SUCCESS: All dependencies in the group must succeed
        - GROUP_ALL_FAILED: All dependencies in the group must fail
        - GROUP_AT_LEAST_ONE_SUCCESS: At least one dependency in the group must succeed
        - GROUP_AT_LEAST_ONE_FAILED: At least one dependency in the group must fail
        - GROUP_NONE_FAILED: None of the dependencies in the group can fail (at least one must execute)
        - GROUP_ALL_DONE: All dependencies in the group must complete (any outcome)
    JobDraftSpec:
      type: object
      description: |
        Optional overrides for a job draft version. All fields are optional.
        When creating a draft, unspecified fields are copied from the currently published version.
        When updating a draft, unspecified fields are left unchanged.
      x-filter-access-types:
        - ReadWrite
        - ReadImmutable
      properties:
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster the job will run on.
          x-access-type: ReadImmutable
          x-order: 6
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: An optional description for this job.
          x-access-type: ReadWrite
          x-order: 8
        config:
          allOf:
            - $ref: '#/components/schemas/JobConfig'
          description: The job configuration for this version.
          x-access-type: ReadImmutable
          x-order: 9
        timeoutSeconds:
          type: integer
          description: An optional timeout applied to each run of this job. A value of 0 means no timeout.
          x-access-type: ReadImmutable
          x-order: 10
        sourceConfig:
          allOf:
            - $ref: '#/components/schemas/SourceConfig'
          description: An optional specification for a remote version control repository containing the source code used by jobs. If sourceConfig is set, these jobs retrieve the file from the remote repository by default. However, this behavior can be overridden by setting source to WORKSPACE on the job.
          x-access-type: ReadImmutable
          x-order: 11
        dependsOn:
          allOf:
            - $ref: '#/components/schemas/JobDependencies'
          description: An optional array of objects specifying the dependency graph of the job. All jobs specified in this field must complete before executing this job.
          x-access-type: ReadImmutable
          x-order: 12
        cronExpression:
          type: string
          description: A standard 5-field cron expression defining the schedule. Null means manual-only.
          maxLength: 100
          nullable: true
          x-access-type: ReadWrite
          x-order: 13
        cronTimezone:
          type: string
          description: IANA timezone for cron evaluation (e.g. 'America/New_York'). Defaults to UTC.
          maxLength: 64
          nullable: true
          x-access-type: ReadWrite
          x-order: 14
        concurrencyPolicy:
          allOf:
            - $ref: '#/components/schemas/ConcurrencyPolicy'
          description: The concurrency policy when a scheduled run overlaps a still-running run.
          x-access-type: ReadWrite
          x-order: 15
        maxConcurrentRuns:
          type: integer
          description: Maximum number of parallel runs when concurrencyPolicy is 'allow'. Minimum 1.
          minimum: 1
          x-access-type: ReadWrite
          x-order: 16
        missedSchedulePolicy:
          allOf:
            - $ref: '#/components/schemas/MissedSchedulePolicy'
          description: The behavior when the scheduler recovers after missing one or more cron ticks.
          x-access-type: ReadWrite
          x-order: 17
    JobIncluded:
      type: object
      description: |
        Included entities for job responses.
        Job summaries include published version fields inlined.
        Version history is available as a separate sub-resource.
      properties:
        jobs:
          type: array
          description: Array of job entities with published version config inlined
          items:
            $ref: '#/components/schemas/JobSummary'
        jobRuns:
          type: array
          description: Array of job run entities
          items:
            $ref: '#/components/schemas/JobRunSummary'
        teams:
          type: array
          description: Array of job-team associations
          items:
            $ref: '#/components/schemas/TeamSummary'
    JobItem:
      type: object
      description: A job reference containing only IDs for related entities.
      required:
        - jobId
      properties:
        jobId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job ID
        latestJobRunId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The latest job run ID (null if no runs exist)
          nullable: true
        teamIds:
          type: array
          description: Array of team IDs associated with this job
          items:
            allOf:
              - $ref: '#/components/schemas/ResourceId'
    JobKey:
      type: string
      description: The job key, a unique name within the workflow used to reference this job from other jobs.
      minLength: 1
      maxLength: 100
      pattern: ^[\w\-_]+$
      example: daily-sales-etl
    JobList:
      type: object
      description: A list of LakeSail jobs.
      required:
        - total
        - items
        - included
      properties:
        total:
          type: integer
          description: The total number of jobs accessible to the member.
          x-order: 1
        items:
          type: array
          description: Job list items with ID references only.
          items:
            $ref: '#/components/schemas/JobItem'
          x-order: 2
        included:
          allOf:
            - $ref: '#/components/schemas/JobIncluded'
          description: Related entities referenced by IDs in the list items.
          x-order: 3
    JobNormalized:
      type: object
      description: A single job with related entities included.
      required:
        - item
        - included
      properties:
        item:
          allOf:
            - $ref: '#/components/schemas/JobItem'
          description: Job with ID references only.
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/JobIncluded'
          description: Full entity data for referenced IDs.
          x-order: 2
    JobRun:
      type: object
      description: A LakeSail job run.
      required:
        - id
        - jobId
        - jobVersion
        - status
        - resourceCleanupMode
        - trigger
        - createdAt
        - updatedAt
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job run ID.
          x-access-type: ReadOnly
          x-order: 1
        jobId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job this run belongs to.
          x-access-type: ReadImmutable
          x-order: 2
        jobVersion:
          type: integer
          description: The job version used for this run. If omitted when creating a run, the job's current active published version is used.
          example: 3
          x-access-type: ReadImmutable
          x-order: 3
        status:
          allOf:
            - $ref: '#/components/schemas/JobRunStatus'
          description: The current status of this run.
          x-access-type: ReadOnly
          x-order: 4
        statusMessage:
          type: string
          nullable: true
          description: A message providing additional context for the current status (e.g., error details when the run has failed).
          x-access-type: ReadOnly
          x-order: 5
        hold:
          type: boolean
          description: |
            When true, the run is created in `pending` status instead of `ready`.
            A pending run will not be picked up by the job worker until it is
            explicitly released via the Release Job Run endpoint. This enables
            batch orchestration, approval gates, and agentic workflows.
            Defaults to false.
          x-access-type: WriteOnly
          x-order: 6
        resourceCleanupMode:
          allOf:
            - $ref: '#/components/schemas/JobRunResourceCleanupMode'
          description: The resource cleanup mode for this run.
          x-access-type: ReadImmutable
          x-order: 7
        dispatchedAt:
          type: string
          format: date-time
          description: Timestamp when this run was dispatched for execution.
          nullable: true
          x-access-type: ReadOnly
          x-order: 8
        finishedAt:
          type: string
          format: date-time
          description: Timestamp when the platform recorded a terminal state for this run.
          nullable: true
          x-access-type: ReadOnly
          x-order: 9
        runnerStartedAt:
          type: string
          format: date-time
          description: Timestamp when the job runner began executing (set by the runner callback). Represents the start of actual job execution, after infrastructure provisioning.
          nullable: true
          x-access-type: ReadOnly
          x-order: 10
        runnerCompletedAt:
          type: string
          format: date-time
          description: Timestamp when the job runner finished executing (set by the runner callback). Represents the end of actual job execution, before resource cleanup.
          nullable: true
          x-access-type: ReadOnly
          x-order: 11
        runnerExecutionTimeUs:
          type: integer
          format: int64
          description: The runner's self-reported execution time in microseconds. Set by the runner callback upon job completion.
          nullable: true
          example: 45200000
          x-access-type: ReadOnly
          x-order: 12
        trigger:
          allOf:
            - $ref: '#/components/schemas/JobRunTrigger'
          description: How this run was triggered (manually or by the scheduler).
          x-access-type: ReadOnly
          x-order: 13
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this run was created.
          x-access-type: ReadOnly
          x-order: 14
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this run.
          x-access-type: ReadOnly
          x-order: 15
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this run was last updated.
          x-access-type: ReadOnly
          x-order: 16
        results:
          allOf:
            - $ref: '#/components/schemas/JobRunResults'
          description: Results metadata from the job run (e.g., output path).
          x-access-type: ReadOnly
          x-order: 17
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this run.
          x-access-type: ReadOnly
          x-order: 18
        cleanedAt:
          type: string
          format: date-time
          description: Timestamp when K8s resources for this run were cleaned up. Null if cleanup has not yet occurred or resourceCleanupMode is `never`.
          nullable: true
          x-access-type: ReadOnly
          x-order: 19
    JobRunList:
      type: object
      description: A list of LakeSail job runs
      required:
        - items
      properties:
        total:
          type: integer
          description: The total number of job runs.
          nullable: true
          x-order: 1
        items:
          type: array
          description: A list of LakeSail job runs.
          items:
            $ref: '#/components/schemas/JobRunSummary'
          x-order: 2
        marker:
          type: string
          description: Pagination token for the next page.
          nullable: true
          x-order: 3
    JobRunResourceCleanupMode:
      type: string
      enum:
        - always
        - on_success
        - never
      description: |
        The resource cleanup mode for a job run:
        - always: Clean up resources after every run, regardless of outcome
        - on_success: Clean up resources only when the run succeeds
        - never: Never clean up resources (useful for debugging)
      example: always
    JobRunResults:
      type: object
      nullable: true
      description: Results metadata from the job run.
      properties:
        outputPath:
          type: string
          nullable: true
          description: Storage URI where job results were written.
          example: s3://lakesail-output/jobs/daily-sales-etl/runs/2026-04-06/
    JobRunSpec:
      type: object
      description: |
        The specification to create a job run.
        If jobVersion is omitted, the job's current active published version is used.
        Only published versions can be used for runs.
      x-filter-group: Spec
      properties:
        jobId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job this run belongs to.
          x-access-type: ReadImmutable
          x-order: 2
        jobVersion:
          type: integer
          description: The job version used for this run. If omitted when creating a run, the job's current active published version is used.
          example: 3
          x-access-type: ReadImmutable
          x-order: 3
        hold:
          type: boolean
          description: |
            When true, the run is created in `pending` status instead of `ready`.
            A pending run will not be picked up by the job worker until it is
            explicitly released via the Release Job Run endpoint. This enables
            batch orchestration, approval gates, and agentic workflows.
            Defaults to false.
          x-access-type: WriteOnly
          x-order: 6
        resourceCleanupMode:
          allOf:
            - $ref: '#/components/schemas/JobRunResourceCleanupMode'
          description: The resource cleanup mode for this run.
          x-access-type: ReadImmutable
          x-order: 7
    JobRunStatus:
      type: string
      enum:
        - pending
        - ready
        - starting
        - creating_sail
        - waiting_for_sail
        - creating_runner
        - running
        - succeeded
        - failed
        - cancelled
        - timeout
        - unknown
      description: |
        The current status of a job run.

        - `pending`: Created but not yet ready for execution. Used by e.g. external orchestrators
           to hold a run until dependencies are satisfied. Transitions to `ready` when released.
        - `ready`: Ready to be claimed by the job worker on its next poll tick.
    JobRunSummary:
      type: object
      description: A summary of a LakeSail job run.
      required:
        - id
        - jobId
        - jobVersion
        - status
        - resourceCleanupMode
        - trigger
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job run ID.
          x-access-type: ReadOnly
          x-order: 1
        jobId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job this run belongs to.
          x-access-type: ReadImmutable
          x-order: 2
        jobVersion:
          type: integer
          description: The job version used for this run. If omitted when creating a run, the job's current active published version is used.
          example: 3
          x-access-type: ReadImmutable
          x-order: 3
        status:
          allOf:
            - $ref: '#/components/schemas/JobRunStatus'
          description: The current status of this run.
          x-access-type: ReadOnly
          x-order: 4
        statusMessage:
          type: string
          nullable: true
          description: A message providing additional context for the current status (e.g., error details when the run has failed).
          x-access-type: ReadOnly
          x-order: 5
        resourceCleanupMode:
          allOf:
            - $ref: '#/components/schemas/JobRunResourceCleanupMode'
          description: The resource cleanup mode for this run.
          x-access-type: ReadImmutable
          x-order: 7
        dispatchedAt:
          type: string
          format: date-time
          description: Timestamp when this run was dispatched for execution.
          nullable: true
          x-access-type: ReadOnly
          x-order: 8
        finishedAt:
          type: string
          format: date-time
          description: Timestamp when the platform recorded a terminal state for this run.
          nullable: true
          x-access-type: ReadOnly
          x-order: 9
        runnerStartedAt:
          type: string
          format: date-time
          description: Timestamp when the job runner began executing (set by the runner callback). Represents the start of actual job execution, after infrastructure provisioning.
          nullable: true
          x-access-type: ReadOnly
          x-order: 10
        runnerCompletedAt:
          type: string
          format: date-time
          description: Timestamp when the job runner finished executing (set by the runner callback). Represents the end of actual job execution, before resource cleanup.
          nullable: true
          x-access-type: ReadOnly
          x-order: 11
        runnerExecutionTimeUs:
          type: integer
          format: int64
          description: The runner's self-reported execution time in microseconds. Set by the runner callback upon job completion.
          nullable: true
          example: 45200000
          x-access-type: ReadOnly
          x-order: 12
        trigger:
          allOf:
            - $ref: '#/components/schemas/JobRunTrigger'
          description: How this run was triggered (manually or by the scheduler).
          x-access-type: ReadOnly
          x-order: 13
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this run was created.
          x-access-type: ReadOnly
          x-order: 14
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this run.
          x-access-type: ReadOnly
          x-order: 15
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this run was last updated.
          x-access-type: ReadOnly
          x-order: 16
        results:
          allOf:
            - $ref: '#/components/schemas/JobRunResults'
          description: Results metadata from the job run (e.g., output path).
          x-access-type: ReadOnly
          x-order: 17
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this run.
          x-access-type: ReadOnly
          x-order: 18
        cleanedAt:
          type: string
          format: date-time
          description: Timestamp when K8s resources for this run were cleaned up. Null if cleanup has not yet occurred or resourceCleanupMode is `never`.
          nullable: true
          x-access-type: ReadOnly
          x-order: 19
    JobRunTrigger:
      type: string
      enum:
        - manual
        - schedule
      description: |
        How this job run was triggered:
        - `manual`: Triggered by a user via the API or UI.
        - `schedule`: Triggered automatically by the job scheduler.
      example: manual
    JobSpec:
      type: object
      description: |
        The specification to create a job. Creates both the parent job and its initial
        published version (v1) atomically. The job is immediately operational after creation.
      required:
        - teamIds
        - jobKey
        - clusterId
        - config
      x-filter-group: Spec
      properties:
        jobKey:
          allOf:
            - $ref: '#/components/schemas/JobKey'
          description: A unique name within the workflow, used to reference this job from other jobs.
          x-access-type: ReadWrite
          x-order: 3
        status:
          allOf:
            - $ref: '#/components/schemas/JobStatus'
          description: The current status of this job.
          x-access-type: ReadWrite
          x-order: 8
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster the job runs on (from the published version).
          x-access-type: ReadImmutable
          x-order: 9
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: An optional description for this job (from the published version).
          x-access-type: ReadWrite
          x-order: 10
        config:
          allOf:
            - $ref: '#/components/schemas/JobConfig'
          description: The job configuration (from the published version).
          x-access-type: ReadImmutable
          x-order: 11
        timeoutSeconds:
          type: integer
          description: An optional timeout applied to each run of this job. A value of 0 means no timeout. From the published version.
          example: 3600
          x-access-type: ReadImmutable
          x-order: 12
        sourceConfig:
          allOf:
            - $ref: '#/components/schemas/SourceConfig'
          description: An optional specification for a remote version control repository. From the published version.
          x-access-type: ReadImmutable
          x-order: 13
        dependsOn:
          allOf:
            - $ref: '#/components/schemas/JobDependencies'
          description: An optional array of objects specifying the dependency graph. From the published version.
          x-access-type: ReadImmutable
          x-order: 14
        teamIds:
          type: array
          description: The team IDs that will have access to this job.
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/ResourceId'
    JobStatus:
      type: string
      enum:
        - active
        - paused
      description: |
        The status of a LakeSail job. A job can be in one of two states:

        - `active`: The job is active and will run according to its schedule.
        - `paused`: The job is paused and will not run until it is resumed.
      example: active
    JobSummary:
      type: object
      description: |
        A summary of a LakeSail job with published version configuration inlined.
      required:
        - id
        - jobKey
        - status
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job ID.
          x-access-type: ReadOnly
          x-order: 1
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: ID of the member who created this job.
          x-access-type: ReadOnly
          x-order: 2
        jobKey:
          allOf:
            - $ref: '#/components/schemas/JobKey'
          description: A unique name within the workflow, used to reference this job from other jobs.
          x-access-type: ReadWrite
          x-order: 3
        version:
          type: integer
          description: The version number whose configuration fields (config, clusterId, description, etc.) are inlined in this response. May differ from currentVersion when viewing a historical version.
          example: 3
          x-access-type: ReadOnly
          x-order: 4
        currentVersion:
          type: integer
          description: The current published version number of the job. Use PATCH with `version` to change which version is current.
          example: 3
          x-access-type: ReadOnly
          x-order: 5
        draftVersion:
          type: integer
          description: The draft version number, or null if no draft exists.
          nullable: true
          example: 4
          x-access-type: ReadOnly
          x-order: 6
        basedOnVersion:
          type: integer
          description: The version this version is based on, if any. Inlined from the requested version.
          nullable: true
          x-access-type: ReadOnly
          x-order: 7
        status:
          allOf:
            - $ref: '#/components/schemas/JobStatus'
          description: The current status of this job.
          x-access-type: ReadWrite
          x-order: 8
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster the job runs on (from the published version).
          x-access-type: ReadImmutable
          x-order: 9
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: An optional description for this job (from the published version).
          x-access-type: ReadWrite
          x-order: 10
        config:
          allOf:
            - $ref: '#/components/schemas/JobConfig'
          description: The job configuration (from the published version).
          x-access-type: ReadImmutable
          x-order: 11
        timeoutSeconds:
          type: integer
          description: An optional timeout applied to each run of this job. A value of 0 means no timeout. From the published version.
          example: 3600
          x-access-type: ReadImmutable
          x-order: 12
        sourceConfig:
          allOf:
            - $ref: '#/components/schemas/SourceConfig'
          description: An optional specification for a remote version control repository. From the published version.
          x-access-type: ReadImmutable
          x-order: 13
        dependsOn:
          allOf:
            - $ref: '#/components/schemas/JobDependencies'
          description: An optional array of objects specifying the dependency graph. From the published version.
          x-access-type: ReadImmutable
          x-order: 14
        cronExpression:
          type: string
          description: A standard 5-field cron expression defining the schedule. Null means manual-only. From the published version.
          maxLength: 100
          nullable: true
          example: 0 2 * * *
          x-access-type: ReadOnly
          x-order: 15
        cronTimezone:
          type: string
          description: IANA timezone for cron evaluation (e.g. 'America/New_York'). Defaults to UTC. From the published version.
          maxLength: 64
          nullable: true
          example: America/New_York
          x-access-type: ReadOnly
          x-order: 16
        concurrencyPolicy:
          allOf:
            - $ref: '#/components/schemas/ConcurrencyPolicy'
          description: The concurrency policy when a scheduled run overlaps a still-running run. From the published version.
          x-access-type: ReadOnly
          x-order: 17
        maxConcurrentRuns:
          type: integer
          description: Maximum number of parallel runs when concurrencyPolicy is 'allow'. Minimum 1. From the published version.
          minimum: 1
          example: 1
          x-access-type: ReadOnly
          x-order: 18
        missedSchedulePolicy:
          allOf:
            - $ref: '#/components/schemas/MissedSchedulePolicy'
          description: The behavior when the scheduler recovers after missing one or more cron ticks. From the published version.
          x-access-type: ReadOnly
          x-order: 19
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this job was created.
          x-access-type: ReadOnly
          x-order: 20
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this job.
          x-access-type: ReadOnly
          x-order: 21
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this job was last updated.
          x-access-type: ReadOnly
          x-order: 22
        nextRunAt:
          type: string
          format: date-time
          description: The precomputed next scheduled run time. Null if the job has no schedule or is paused.
          nullable: true
          x-access-type: ReadOnly
          x-order: 23
        lastScheduledAt:
          type: string
          format: date-time
          description: Timestamp when the scheduler last triggered a run for this job.
          nullable: true
          x-access-type: ReadOnly
          x-order: 24
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this job.
          x-access-type: ReadOnly
          x-order: 25
    JobTeamList:
      type: object
      description: A list of teams associated with a job.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of job-team associations.
          items:
            $ref: '#/components/schemas/JobTeamSummary'
          x-order: 1
    JobTeamSummary:
      type: object
      description: A summary of a job-team association.
      required:
        - jobId
        - teamId
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        jobId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job ID.
          x-access-type: ReadImmutable
          x-order: 1
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team ID.
          x-access-type: ReadImmutable
          x-order: 2
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this association was created.
          x-access-type: ReadOnly
          x-order: 3
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this association.
          x-access-type: ReadOnly
          x-order: 4
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this association was last updated.
          x-access-type: ReadOnly
          x-order: 5
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this association.
          x-access-type: ReadOnly
          x-order: 6
    JobUpdate:
      type: object
      description: |
        An update to a LakeSail job.
        Metadata fields (jobKey, status) are always editable.
        Configuration fields (config, clusterId, description, etc.) can only be
        updated when a draft version exists.
      x-filter-group: Update
      properties:
        jobKey:
          allOf:
            - $ref: '#/components/schemas/JobKey'
          description: A unique name within the workflow, used to reference this job from other jobs.
          x-access-type: ReadWrite
          x-order: 3
        status:
          allOf:
            - $ref: '#/components/schemas/JobStatus'
          description: The current status of this job.
          x-access-type: ReadWrite
          x-order: 8
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: An optional description for this job (from the published version).
          x-access-type: ReadWrite
          x-order: 10
        version:
          type: integer
          description: Set the current published version number for the job.
    JobVersionList:
      type: object
      description: A list of LakeSail job versions
      required:
        - total
        - items
      properties:
        total:
          type: integer
          description: The total number of job versions.
          x-order: 1
        items:
          type: array
          description: A list of LakeSail job versions.
          items:
            $ref: '#/components/schemas/JobVersionSummary'
          x-order: 2
    JobVersionSpec:
      type: object
      description: |
        The specification to create a new published version for an existing job.
        Creates and publishes the version atomically. The job must be in active status
        and must not have an existing draft version.
      required:
        - clusterId
        - config
      x-filter-group: Spec
      properties:
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster the job will run on.
          x-access-type: ReadImmutable
          x-order: 6
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: An optional description for this job.
          x-access-type: ReadWrite
          x-order: 8
        config:
          allOf:
            - $ref: '#/components/schemas/JobConfig'
          description: The job configuration for this version.
          x-access-type: ReadImmutable
          x-order: 9
        timeoutSeconds:
          type: integer
          description: An optional timeout applied to each run of this job. A value of 0 means no timeout.
          x-access-type: ReadImmutable
          x-order: 10
        sourceConfig:
          allOf:
            - $ref: '#/components/schemas/SourceConfig'
          description: An optional specification for a remote version control repository containing the source code used by jobs. If sourceConfig is set, these jobs retrieve the file from the remote repository by default. However, this behavior can be overridden by setting source to WORKSPACE on the job.
          x-access-type: ReadImmutable
          x-order: 11
        dependsOn:
          allOf:
            - $ref: '#/components/schemas/JobDependencies'
          description: An optional array of objects specifying the dependency graph of the job. All jobs specified in this field must complete before executing this job.
          x-access-type: ReadImmutable
          x-order: 12
        cronExpression:
          type: string
          description: A standard 5-field cron expression defining the schedule. Null means manual-only.
          maxLength: 100
          nullable: true
          x-access-type: ReadWrite
          x-order: 13
        cronTimezone:
          type: string
          description: IANA timezone for cron evaluation (e.g. 'America/New_York'). Defaults to UTC.
          maxLength: 64
          nullable: true
          x-access-type: ReadWrite
          x-order: 14
        concurrencyPolicy:
          allOf:
            - $ref: '#/components/schemas/ConcurrencyPolicy'
          description: The concurrency policy when a scheduled run overlaps a still-running run.
          x-access-type: ReadWrite
          x-order: 15
        maxConcurrentRuns:
          type: integer
          description: Maximum number of parallel runs when concurrencyPolicy is 'allow'. Minimum 1.
          minimum: 1
          x-access-type: ReadWrite
          x-order: 16
        missedSchedulePolicy:
          allOf:
            - $ref: '#/components/schemas/MissedSchedulePolicy'
          description: The behavior when the scheduler recovers after missing one or more cron ticks.
          x-access-type: ReadWrite
          x-order: 17
    JobVersionStatus:
      type: string
      enum:
        - draft
        - published
      description: |
        The status of a job version:

        - `draft`: The version is being prepared and can be edited. Only one draft per job is allowed.
        - `published`: The version is finalized and immutable. It can be used as the active configuration.
    JobVersionSummary:
      type: object
      description: A summary of a LakeSail job version.
      required:
        - jobId
        - version
        - status
        - jobType
        - config
        - concurrencyPolicy
        - maxConcurrentRuns
        - missedSchedulePolicy
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        jobId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The job this version belongs to.
          x-access-type: ReadOnly
          x-order: 1
        version:
          type: integer
          description: The version number.
          x-access-type: ReadOnly
          x-order: 2
        basedOnVersion:
          type: integer
          description: The version this version is based on, if any.
          nullable: true
          x-access-type: ReadOnly
          x-order: 3
        status:
          allOf:
            - $ref: '#/components/schemas/JobVersionStatus'
          description: The status of this version (draft or published).
          x-access-type: ReadOnly
          x-order: 4
        jobType:
          allOf:
            - $ref: '#/components/schemas/JobVersionType'
          description: The type of job (sql or python).
          x-access-type: ReadOnly
          x-order: 5
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster the job will run on.
          x-access-type: ReadImmutable
          x-order: 6
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: ID of the member who created this job.
          x-access-type: ReadOnly
          x-order: 7
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: An optional description for this job.
          x-access-type: ReadWrite
          x-order: 8
        config:
          allOf:
            - $ref: '#/components/schemas/JobConfig'
          description: The job configuration for this version.
          x-access-type: ReadImmutable
          x-order: 9
        timeoutSeconds:
          type: integer
          description: An optional timeout applied to each run of this job. A value of 0 means no timeout.
          x-access-type: ReadImmutable
          x-order: 10
        sourceConfig:
          allOf:
            - $ref: '#/components/schemas/SourceConfig'
          description: An optional specification for a remote version control repository containing the source code used by jobs. If sourceConfig is set, these jobs retrieve the file from the remote repository by default. However, this behavior can be overridden by setting source to WORKSPACE on the job.
          x-access-type: ReadImmutable
          x-order: 11
        dependsOn:
          allOf:
            - $ref: '#/components/schemas/JobDependencies'
          description: An optional array of objects specifying the dependency graph of the job. All jobs specified in this field must complete before executing this job.
          x-access-type: ReadImmutable
          x-order: 12
        cronExpression:
          type: string
          description: A standard 5-field cron expression defining the schedule. Null means manual-only.
          maxLength: 100
          nullable: true
          x-access-type: ReadWrite
          x-order: 13
        cronTimezone:
          type: string
          description: IANA timezone for cron evaluation (e.g. 'America/New_York'). Defaults to UTC.
          maxLength: 64
          nullable: true
          x-access-type: ReadWrite
          x-order: 14
        concurrencyPolicy:
          allOf:
            - $ref: '#/components/schemas/ConcurrencyPolicy'
          description: The concurrency policy when a scheduled run overlaps a still-running run.
          x-access-type: ReadWrite
          x-order: 15
        maxConcurrentRuns:
          type: integer
          description: Maximum number of parallel runs when concurrencyPolicy is 'allow'. Minimum 1.
          minimum: 1
          x-access-type: ReadWrite
          x-order: 16
        missedSchedulePolicy:
          allOf:
            - $ref: '#/components/schemas/MissedSchedulePolicy'
          description: The behavior when the scheduler recovers after missing one or more cron ticks.
          x-access-type: ReadWrite
          x-order: 17
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this version was created.
          x-access-type: ReadOnly
          x-order: 18
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this version.
          x-access-type: ReadOnly
          x-order: 19
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this version was last updated.
          x-access-type: ReadOnly
          x-order: 20
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this version.
          x-access-type: ReadOnly
          x-order: 21
    JobVersionType:
      type: string
      description: The type of job execution engine.
      enum:
        - sql
        - python
    Jwt:
      type: string
      description: JWT token.
      pattern: ^[A-Za-z0-9_-]{2,}(?:\.[A-Za-z0-9_-]{2,}){2}$
    LoginList:
      type: object
      description: A list of active logins for the current user.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of active logins.
          items:
            $ref: '#/components/schemas/LoginSummary'
          x-order: 1
    LoginSummary:
      type: object
      description: An active user login.
      required:
        - id
        - deviceId
        - authTime
        - expiresAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The login identifier.
          x-access-type: ReadOnly
          x-order: 1
        deviceId:
          type: string
          description: The device identifier associated with this login.
          x-access-type: ReadOnly
          x-order: 2
        authTime:
          type: string
          format: date-time
          description: When the user authenticated to create this login.
          x-access-type: ReadOnly
          x-order: 3
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
          description: When this login was last used to make an API request.
          x-access-type: ReadOnly
          x-order: 4
        expiresAt:
          type: string
          format: date-time
          description: When this login expires.
          x-access-type: ReadOnly
          x-order: 5
        remoteIp:
          type: string
          description: The IP address the login was created from.
          x-access-type: ReadOnly
          x-order: 6
        userAgent:
          type: string
          description: The user agent string of the client that created this login.
          x-access-type: ReadOnly
          x-order: 7
        isCurrent:
          type: boolean
          description: Whether this login is the one used for the current request.
          x-access-type: ReadOnly
          x-order: 8
    Member:
      type: object
      description: An organization user.
      required:
        - id
        - organizationId
        - accountType
        - isEnabled
        - createdAt
        - updatedAt
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization user ID.
          x-access-type: ReadOnly
          x-order: 1
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadImmutable
          x-order: 2
        userId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The user ID.
          x-access-type: ReadOnly
          x-order: 3
        name:
          type: string
          minLength: 1
          maxLength: 127
          description: The user's name.
          x-access-type: ReadWrite
          x-order: 4
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The user's email address.
          x-access-type: ReadWrite
          x-order: 5
        preferences:
          type: object
          description: The user's preferences.
          x-access-type: ReadWrite
          x-order: 6
        invitationToken:
          allOf:
            - $ref: '#/components/schemas/InvitationToken'
          description: The invitation token (only present for pending invites).
          x-access-type: WriteOnly
          x-order: 7
        invitedByMemberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member ID of who invited this member.
          x-access-type: ReadOnly
          x-order: 8
        inviteExpiresAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the invitation expires.
          x-access-type: ReadOnly
          x-order: 9
        inviteAcceptedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the invitation was accepted.
          x-access-type: ReadOnly
          x-order: 10
        lastLoginAt:
          type: string
          format: date-time
          nullable: true
          description: The time of the user's last login.
          x-access-type: ReadOnly
          x-order: 11
        lastActiveAt:
          type: string
          format: date-time
          nullable: true
          description: The time of the user's last activity.
          x-access-type: ReadOnly
          x-order: 12
        isEnabled:
          type: boolean
          description: Whether the user is enabled in the organization.
          x-access-type: ReadWrite
          x-order: 13
        accountType:
          allOf:
            - $ref: '#/components/schemas/AccountType'
          description: The account type determines who can modify the user's profile.
          x-access-type: ReadImmutable
          x-order: 14
        createdAt:
          type: string
          format: date-time
          description: The time when the organization user was created.
          x-access-type: ReadOnly
          x-order: 15
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this organization user.
          x-access-type: ReadOnly
          x-order: 16
        updatedAt:
          type: string
          format: date-time
          description: The time when the organization user was last updated.
          x-access-type: ReadOnly
          x-order: 17
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this organization user.
          x-access-type: ReadOnly
          x-order: 18
    MemberFilter:
      type: object
      description: Filter criteria for searching organization members.
      properties:
        name:
          type: string
          description: Filter by member name (case-insensitive partial match).
          minLength: 1
          maxLength: 255
          example: Alice
    MemberNormalized:
      type: object
      description: A normalized response containing a single organization user with related entity data.
      required:
        - item
        - included
      properties:
        item:
          allOf:
            - $ref: '#/components/schemas/MemberSearchItem'
          description: The organization user search item with entity ID references.
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/MemberSearchIncluded'
          description: Related entities referenced by IDs.
          x-order: 2
    MemberRoleSummary:
      type: object
      description: A role assigned to a user within an organization.
      required:
        - memberId
        - organizationRoleId
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member ID.
          x-access-type: ReadImmutable
          x-order: 1
        organizationRoleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization role ID.
          x-access-type: ReadWrite
          x-order: 2
        createdAt:
          type: string
          format: date-time
          description: The time when the member was created.
          x-access-type: ReadOnly
          x-order: 3
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this member role.
          x-access-type: ReadOnly
          x-order: 4
        updatedAt:
          type: string
          format: date-time
          description: The time when the member was last updated.
          x-access-type: ReadOnly
          x-order: 5
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this member role.
          x-access-type: ReadOnly
          x-order: 6
    MemberRolesUpdate:
      type: object
      required:
        - roleIds
      properties:
        roleIds:
          type: array
          items:
            $ref: '#/components/schemas/ResourceId'
          minItems: 1
          description: Array of organization role IDs to assign to the user. Must contain at least one role ID.
          example:
            - ROLE123
            - ROLE456
    MemberSearch:
      type: object
      description: A normalized paginated response containing organization users with related entity data.
      required:
        - total
        - items
        - included
      properties:
        total:
          type: integer
          description: The total number of organization users found.
          x-order: 1
        items:
          type: array
          description: A page of organization user search results with ID references.
          items:
            $ref: '#/components/schemas/MemberSearchItem'
          x-order: 2
        included:
          allOf:
            - $ref: '#/components/schemas/MemberSearchIncluded'
          x-order: 3
    MemberSearchIncluded:
      type: object
      description: Related entities referenced by IDs in the search results.
      properties:
        members:
          type: array
          description: Array of member entities.
          items:
            $ref: '#/components/schemas/MemberSummary'
          x-order: 1
        users:
          type: array
          description: Array of user entities with emails.
          items:
            $ref: '#/components/schemas/UserExpanded'
          x-order: 2
        roles:
          type: array
          description: Array of organization role entities.
          items:
            $ref: '#/components/schemas/OrganizationRoleExpanded'
          x-order: 3
        teams:
          type: array
          description: Array of team entities with member counts.
          items:
            $ref: '#/components/schemas/TeamExpanded'
          x-order: 4
        teamRoles:
          type: array
          description: Array of team role entities.
          items:
            $ref: '#/components/schemas/TeamRoleExpanded'
          x-order: 5
        _entityRelations:
          description: Reserved for future use.
          allOf:
            - $ref: '#/components/schemas/MemberRoleSummary'
            - $ref: '#/components/schemas/MemberTeamSummary'
            - $ref: '#/components/schemas/MemberTeamRoleSummary'
          x-order: 99
    MemberSearchItem:
      type: object
      description: A single user search result item with entity ID references.
      required:
        - memberId
      properties:
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization member ID.
          x-order: 1
        userId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: The user ID if the member has accepted their invitation.
          x-order: 2
        roleIds:
          type: array
          nullable: true
          description: Organization role IDs assigned to this member.
          items:
            type: string
          x-order: 3
        teamRoleIds:
          type: object
          nullable: true
          description: Map of team ID to the role IDs this member has in that team.
          additionalProperties:
            type: array
            items:
              type: string
          x-order: 4
    MemberSummary:
      type: object
      description: An organization user.
      required:
        - id
        - organizationId
        - accountType
        - isEnabled
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization user ID.
          x-access-type: ReadOnly
          x-order: 1
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadImmutable
          x-order: 2
        userId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The user ID.
          x-access-type: ReadOnly
          x-order: 3
        name:
          type: string
          minLength: 1
          maxLength: 127
          description: The user's name.
          x-access-type: ReadWrite
          x-order: 4
          nullable: true
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The user's email address.
          x-access-type: ReadWrite
          x-order: 5
          type: string
          nullable: true
        preferences:
          type: object
          description: The user's preferences.
          x-access-type: ReadWrite
          x-order: 6
        invitedByMemberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member ID of who invited this member.
          x-access-type: ReadOnly
          x-order: 8
        inviteExpiresAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the invitation expires.
          x-access-type: ReadOnly
          x-order: 9
        inviteAcceptedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the invitation was accepted.
          x-access-type: ReadOnly
          x-order: 10
        lastLoginAt:
          type: string
          format: date-time
          nullable: true
          description: The time of the user's last login.
          x-access-type: ReadOnly
          x-order: 11
        lastActiveAt:
          type: string
          format: date-time
          nullable: true
          description: The time of the user's last activity.
          x-access-type: ReadOnly
          x-order: 12
        isEnabled:
          type: boolean
          description: Whether the user is enabled in the organization.
          x-access-type: ReadWrite
          x-order: 13
        accountType:
          allOf:
            - $ref: '#/components/schemas/AccountType'
          description: The account type determines who can modify the user's profile.
          x-access-type: ReadImmutable
          x-order: 14
        createdAt:
          type: string
          format: date-time
          description: The time when the organization user was created.
          x-access-type: ReadOnly
          x-order: 15
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this organization user.
          x-access-type: ReadOnly
          x-order: 16
        updatedAt:
          type: string
          format: date-time
          description: The time when the organization user was last updated.
          x-access-type: ReadOnly
          x-order: 17
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this organization user.
          x-access-type: ReadOnly
          x-order: 18
    MemberTeamRoleSummary:
      type: object
      description: A summary of an organization user membership to a team.
      required:
        - memberTeamId
        - teamRoleId
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        memberTeamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member team member.
          x-access-type: ReadOnly
          x-order: 1
        teamRoleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team role ID.
          x-access-type: ReadWrite
          x-order: 2
        createdAt:
          type: string
          format: date-time
          description: The time when the team membership was created.
          x-access-type: ReadOnly
          x-order: 3
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this team membership role.
          x-access-type: ReadOnly
          x-order: 4
        updatedAt:
          type: string
          format: date-time
          description: The time when the team membership was last updated.
          x-access-type: ReadOnly
          x-order: 5
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this team membership role.
          x-access-type: ReadOnly
          x-order: 6
    MemberTeamSummary:
      type: object
      description: A summary of an organization user membership to a team.
      required:
        - id
        - memberId
        - teamId
        - isAutomatic
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member team ID.
          x-access-type: ReadOnly
          x-order: 1
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member ID.
          x-access-type: ReadImmutable
          x-order: 2
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team ID.
          x-access-type: ReadImmutable
          x-order: 3
        isAutomatic:
          type: boolean
          description: Whether this membership was automatically created because the member holds an org role with all_teams=true.
          x-access-type: ReadOnly
          x-order: 4
        createdAt:
          type: string
          format: date-time
          description: The time when the team membership was created.
          x-access-type: ReadOnly
          x-order: 5
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this team membership.
          x-access-type: ReadOnly
          x-order: 6
        updatedAt:
          type: string
          format: date-time
          description: The time when the team membership was last updated.
          x-access-type: ReadOnly
          x-order: 7
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this team membership.
          x-access-type: ReadOnly
          x-order: 8
    MemberUpdate:
      type: object
      description: An update to an organization user.
      x-filter-group: Update
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 127
          description: The user's name.
          x-access-type: ReadWrite
          x-order: 4
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The user's email address.
          x-access-type: ReadWrite
          x-order: 5
        preferences:
          type: object
          description: The user's preferences.
          x-access-type: ReadWrite
          x-order: 6
        invitationToken:
          allOf:
            - $ref: '#/components/schemas/InvitationToken'
          description: The invitation token (only present for pending invites).
          x-access-type: WriteOnly
          x-order: 7
        isEnabled:
          type: boolean
          description: Whether the user is enabled in the organization.
          x-access-type: ReadWrite
          x-order: 13
    MetricDataPoint:
      type: object
      description: A single data point for a metric.
      required:
        - timestamp
        - value
      properties:
        timestamp:
          type: string
          format: date-time
          description: The timestamp of the data point.
          x-access-type: ReadOnly
        value:
          type: number
          description: The value of the data point.
          x-access-type: ReadOnly
    MissedSchedulePolicy:
      type: string
      enum:
        - latest
        - all
      description: |
        The behavior when the scheduler recovers after missing one or more cron ticks:
        - `latest`: Fire exactly once on recovery.
        - `all`: Fire once for each missed tick, with backdated dispatch times.
      example: latest
    MyUserUpdate:
      type: object
      description: An update to the current user's profile.
      x-filter-group: Update
      properties:
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The email address of the user.
          x-access-type: ReadWrite
          x-order: 2
        givenName:
          type: string
          minLength: 1
          maxLength: 63
          description: The given name of the user.
          x-access-type: ReadWrite
          x-order: 3
        familyName:
          type: string
          minLength: 1
          maxLength: 63
          description: The family name of the user.
          x-access-type: ReadWrite
          x-order: 4
        displayName:
          type: string
          minLength: 1
          maxLength: 127
          description: The display name of the user.
          x-access-type: ReadWrite
          x-order: 5
    NotificationChannel:
      type: object
      description: A notification channel.
      required:
        - id
        - type
        - name
        - config
        - status
        - createdAt
        - createdBy
        - updatedAt
        - updatedBy
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notification channel ID.
          x-access-type: ReadOnly
          x-order: 1
        type:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelType'
          description: The type of notification channel.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the channel.
          x-access-type: ReadWrite
          x-order: 3
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team that owns this channel. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 4
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member that owns this channel. Mutually exclusive with teamId.
          x-access-type: ReadImmutable
          x-order: 5
        config:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelConfigRead'
          description: Channel configuration (read view, secrets redacted).
          x-access-type: ReadOnly
          x-order: 6
        configWrite:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelConfigWrite'
          description: Channel configuration (write operations).
          x-access-type: WriteOnly
          x-order: 7
        status:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelStatus'
          description: The current status of the channel.
          x-access-type: ReadWrite
          x-order: 8
        statusMessage:
          type: string
          nullable: true
          description: Error details when the channel is in error state.
          x-access-type: ReadOnly
          x-order: 9
        verifiedAt:
          type: string
          format: date-time
          description: The time when the channel was last verified via a test notification.
          x-access-type: ReadOnly
          x-order: 10
        createdAt:
          type: string
          format: date-time
          description: The time when the channel was created.
          x-access-type: ReadOnly
          x-order: 11
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member who created this channel.
          x-access-type: ReadOnly
          x-order: 12
        updatedAt:
          type: string
          format: date-time
          description: The time when the channel was last updated.
          x-access-type: ReadOnly
          x-order: 13
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member who last updated this channel.
          x-access-type: ReadOnly
          x-order: 14
        supportsDigest:
          type: boolean
          description: Whether this channel type supports digest delivery modes (daily/weekly). When false, only immediate delivery is available for rules using this channel.
          x-access-type: ReadOnly
          x-order: 15
    NotificationChannelConfigEmail:
      type: object
      description: Configuration for an email notification channel. Exactly one of memberId or teamId must be set; providing both or neither is a validation error.
      oneOf:
        - $ref: '#/components/schemas/NotificationChannelConfigEmailMember'
        - $ref: '#/components/schemas/NotificationChannelConfigEmailTeam'
    NotificationChannelConfigEmailMember:
      type: object
      description: Configuration for an email notification channel targeting a member.
      required:
        - memberId
      properties:
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member to notify (their primary email address will be used).
    NotificationChannelConfigEmailTeam:
      type: object
      description: Configuration for an email notification channel targeting a team.
      required:
        - teamId
      properties:
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the team whose members will all receive notifications by email.
    NotificationChannelConfigPagerDuty:
      type: object
      description: Configuration for a PagerDuty notification channel.
      properties:
        routingKey:
          type: string
          format: password
          description: PagerDuty Events API v2 integration key. Omit to keep the existing value.
    NotificationChannelConfigPagerDutyRead:
      type: object
      description: Configuration for a PagerDuty notification channel (read view, secrets redacted).
      required:
        - routingKeyHint
      properties:
        routingKeyHint:
          type: string
          nullable: true
          description: Masked hint showing the last 4 characters of the configured routing key (e.g. "••••f1a2"), or null if no key is configured.
    NotificationChannelConfigRead:
      type: object
      description: Channel configuration for read operations (secrets redacted).
      anyOf:
        - $ref: '#/components/schemas/NotificationChannelConfigEmail'
        - $ref: '#/components/schemas/NotificationChannelConfigWebhookRead'
        - $ref: '#/components/schemas/NotificationChannelConfigSlackRead'
        - $ref: '#/components/schemas/NotificationChannelConfigPagerDutyRead'
        - $ref: '#/components/schemas/NotificationChannelConfigRootlyRead'
    NotificationChannelConfigRootly:
      type: object
      description: Configuration for a Rootly notification channel.
      properties:
        apiToken:
          type: string
          format: password
          description: Rootly API token. Omit to keep the existing value.
    NotificationChannelConfigRootlyRead:
      type: object
      description: Configuration for a Rootly notification channel (read view, secrets redacted).
      required:
        - apiTokenHint
      properties:
        apiTokenHint:
          type: string
          nullable: true
          description: Masked hint showing the last 4 characters of the configured API token (e.g. "••••a1b2"), or null if no token is configured.
    NotificationChannelConfigSlack:
      type: object
      description: Configuration for a Slack notification channel (incoming webhook).
      properties:
        url:
          type: string
          format: uri
          description: The Slack incoming webhook URL (e.g. https://hooks.slack.com/services/...). Omit to keep the existing value.
    NotificationChannelConfigSlackRead:
      type: object
      description: Configuration for a Slack notification channel (read view, secrets redacted).
      required:
        - urlHint
      properties:
        urlHint:
          type: string
          nullable: true
          description: Masked hint showing the last 4 characters of the configured webhook URL (e.g. "••••a1b2"), or null if no URL is configured.
    NotificationChannelConfigWebhook:
      type: object
      description: Configuration for a webhook notification channel.
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: The URL to send webhook notifications to.
        secret:
          type: string
          format: password
          description: An optional shared secret for HMAC-SHA256 request signing. Omit to keep the existing value.
    NotificationChannelConfigWebhookRead:
      type: object
      description: Configuration for a webhook notification channel (read view, secrets redacted).
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: The webhook URL.
        secretConfigured:
          type: boolean
          description: Whether a signing secret has been configured.
    NotificationChannelConfigWrite:
      type: object
      description: Channel configuration for write operations (create or update).
      anyOf:
        - $ref: '#/components/schemas/NotificationChannelConfigEmail'
        - $ref: '#/components/schemas/NotificationChannelConfigWebhook'
        - $ref: '#/components/schemas/NotificationChannelConfigSlack'
        - $ref: '#/components/schemas/NotificationChannelConfigPagerDuty'
        - $ref: '#/components/schemas/NotificationChannelConfigRootly'
    NotificationChannelList:
      type: object
      description: A list of notification channels.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of notification channels.
          items:
            $ref: '#/components/schemas/NotificationChannelSummary'
          x-order: 1
        marker:
          type: string
          description: The pagination token to request more items.
          x-order: 2
    NotificationChannelSpec:
      type: object
      description: The specification to create a notification channel.
      required:
        - type
        - name
        - configWrite
      oneOf:
        - required:
            - teamId
        - required:
            - memberId
      x-filter-group: Spec
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelType'
          description: The type of notification channel.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the channel.
          x-access-type: ReadWrite
          x-order: 3
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team that owns this channel. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 4
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member that owns this channel. Mutually exclusive with teamId.
          x-access-type: ReadImmutable
          x-order: 5
        configWrite:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelConfigWrite'
          description: Channel configuration (write operations).
          x-access-type: WriteOnly
          x-order: 7
        status:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelStatus'
          description: The current status of the channel.
          x-access-type: ReadWrite
          x-order: 8
    NotificationChannelStatus:
      type: string
      description: The status of a notification channel.
      enum:
        - active
        - disabled
        - error
      default: active
    NotificationChannelSummary:
      type: object
      description: A summary of a notification channel.
      required:
        - id
        - type
        - name
        - config
        - status
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notification channel ID.
          x-access-type: ReadOnly
          x-order: 1
        type:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelType'
          description: The type of notification channel.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the channel.
          x-access-type: ReadWrite
          x-order: 3
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team that owns this channel. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 4
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member that owns this channel. Mutually exclusive with teamId.
          x-access-type: ReadImmutable
          x-order: 5
        config:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelConfigRead'
          description: Channel configuration (read view, secrets redacted).
          x-access-type: ReadOnly
          x-order: 6
        status:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelStatus'
          description: The current status of the channel.
          x-access-type: ReadWrite
          x-order: 8
        statusMessage:
          type: string
          nullable: true
          description: Error details when the channel is in error state.
          x-access-type: ReadOnly
          x-order: 9
        verifiedAt:
          type: string
          format: date-time
          description: The time when the channel was last verified via a test notification.
          x-access-type: ReadOnly
          x-order: 10
        createdAt:
          type: string
          format: date-time
          description: The time when the channel was created.
          x-access-type: ReadOnly
          x-order: 11
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member who created this channel.
          x-access-type: ReadOnly
          x-order: 12
        updatedAt:
          type: string
          format: date-time
          description: The time when the channel was last updated.
          x-access-type: ReadOnly
          x-order: 13
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member who last updated this channel.
          x-access-type: ReadOnly
          x-order: 14
        supportsDigest:
          type: boolean
          description: Whether this channel type supports digest delivery modes (daily/weekly). When false, only immediate delivery is available for rules using this channel.
          x-access-type: ReadOnly
          x-order: 15
    NotificationChannelType:
      type: string
      description: The type of notification channel.
      enum:
        - email
        - webhook
        - slack
        - pager_duty
        - rootly
    NotificationChannelUpdate:
      type: object
      description: An update to a notification channel.
      x-filter-group: Update
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the channel.
          x-access-type: ReadWrite
          x-order: 3
        configWrite:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelConfigWrite'
          description: Channel configuration (write operations).
          x-access-type: WriteOnly
          x-order: 7
        status:
          allOf:
            - $ref: '#/components/schemas/NotificationChannelStatus'
          description: The current status of the channel.
          x-access-type: ReadWrite
          x-order: 8
    NotificationEventType:
      type: object
      description: A notification event type definition.
      required:
        - key
        - resourceType
        - label
        - description
      properties:
        key:
          type: string
          description: The event type key (e.g., 'job_run.status.failed').
          x-order: 1
        resourceType:
          type: string
          description: The resource type this event applies to (e.g., 'job_run').
          x-order: 2
        label:
          type: string
          description: A human-readable label for the event type.
          x-order: 3
        description:
          type: string
          description: A description of the event type.
          x-order: 4
        expandsTo:
          type: array
          items:
            type: string
          description: If present, this is a shortcut event type that expands into the listed concrete event types at rule creation time.
          x-order: 5
    NotificationEventTypeList:
      type: object
      description: A list of available notification event types.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of event types.
          items:
            $ref: '#/components/schemas/NotificationEventType'
          x-order: 1
    NotificationList:
      type: object
      description: A list of notification delivery log entries.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of notifications.
          items:
            $ref: '#/components/schemas/NotificationSummary'
          x-order: 1
        marker:
          type: string
          description: The pagination token to request more items.
          x-order: 2
    NotificationRule:
      type: object
      description: A notification rule.
      required:
        - id
        - name
        - resourceType
        - scopeType
        - eventTypes
        - deliveryMode
        - channelIds
        - enabled
        - createdAt
        - createdBy
        - updatedAt
        - updatedBy
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notification rule ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the rule.
          x-access-type: ReadWrite
          x-order: 2
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team that owns this rule. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 3
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member that owns this rule. Mutually exclusive with teamId.
          x-access-type: ReadImmutable
          x-order: 4
        resourceType:
          type: string
          maxLength: 64
          description: The resource type this rule applies to (e.g., 'job_run').
          x-access-type: ReadImmutable
          x-order: 5
        scopeType:
          allOf:
            - $ref: '#/components/schemas/NotificationRuleScopeType'
          description: The scope of resources this rule applies to.
          x-access-type: ReadImmutable
          x-order: 6
        scopeId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the scoped resource or team. Omitted for organization and own_resources scope.
          x-access-type: ReadImmutable
          x-order: 7
        eventTypes:
          type: array
          items:
            type: string
            maxLength: 64
          description: The event types this rule subscribes to.
          x-access-type: ReadWrite
          x-order: 8
        deliveryMode:
          allOf:
            - $ref: '#/components/schemas/NotificationRuleDeliveryMode'
          description: How notifications are delivered (immediate, daily digest, weekly digest).
          x-access-type: ReadWrite
          x-order: 9
        channelIds:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 20
            pattern: ^[A-Z0-9]{1,20}$
          description: The IDs of the notification channels to deliver to.
          x-access-type: ReadWrite
          x-order: 10
        enabled:
          type: boolean
          description: Whether the rule is currently active.
          default: true
          x-access-type: ReadWrite
          x-order: 11
        digestTime:
          type: string
          description: The time of day to send the digest (HH:MM, 24-hour clock). Must be set server-side when deliveryMode is daily_digest or weekly_digest.
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          example: '08:00'
          nullable: true
          x-access-type: ReadWrite
          x-order: 12
        digestTimezone:
          type: string
          minLength: 1
          maxLength: 64
          description: The IANA timezone for the digest time (e.g., 'America/New_York'). Must be set server-side when deliveryMode is daily_digest or weekly_digest.
          example: America/New_York
          nullable: true
          x-access-type: ReadWrite
          x-order: 13
        digestDayOfWeek:
          type: integer
          minimum: 0
          maximum: 6
          description: The day of the week to send the weekly digest (0=Sunday, 6=Saturday). Must be set server-side when deliveryMode is weekly_digest.
          nullable: true
          x-access-type: ReadWrite
          x-order: 14
        mutedUntil:
          type: string
          format: date-time
          description: Notifications are suppressed until this timestamp. Null means unmuted.
          nullable: true
          x-access-type: ReadWrite
          x-order: 15
        createdAt:
          type: string
          format: date-time
          description: The time when the rule was created.
          x-access-type: ReadOnly
          x-order: 16
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member who created this rule.
          x-access-type: ReadOnly
          x-order: 17
        updatedAt:
          type: string
          format: date-time
          description: The time when the rule was last updated.
          x-access-type: ReadOnly
          x-order: 18
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member who last updated this rule.
          x-access-type: ReadOnly
          x-order: 19
    NotificationRuleDeliveryMode:
      type: string
      description: The delivery mode of a notification rule.
      enum:
        - immediate
        - daily_digest
        - weekly_digest
    NotificationRuleList:
      type: object
      description: A list of notification rules.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of notification rules.
          items:
            $ref: '#/components/schemas/NotificationRuleSummary'
          x-order: 1
        marker:
          type: string
          description: The pagination token to request more items.
          x-order: 2
    NotificationRuleScopeType:
      type: string
      description: The scope type of a notification rule.
      enum:
        - resource
        - team
        - organization
        - own_resources
    NotificationRuleSpec:
      type: object
      description: The specification to create a notification rule.
      required:
        - name
        - resourceType
        - scopeType
        - eventTypes
        - deliveryMode
        - channelIds
      oneOf:
        - required:
            - teamId
        - required:
            - memberId
      x-filter-group: Spec
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the rule.
          x-access-type: ReadWrite
          x-order: 2
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team that owns this rule. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 3
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member that owns this rule. Mutually exclusive with teamId.
          x-access-type: ReadImmutable
          x-order: 4
        resourceType:
          type: string
          maxLength: 64
          description: The resource type this rule applies to (e.g., 'job_run').
          x-access-type: ReadImmutable
          x-order: 5
        scopeType:
          allOf:
            - $ref: '#/components/schemas/NotificationRuleScopeType'
          description: The scope of resources this rule applies to.
          x-access-type: ReadImmutable
          x-order: 6
        scopeId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the scoped resource or team. Omitted for organization and own_resources scope.
          x-access-type: ReadImmutable
          x-order: 7
        eventTypes:
          type: array
          items:
            type: string
            maxLength: 64
          description: The event types this rule subscribes to.
          x-access-type: ReadWrite
          x-order: 8
        deliveryMode:
          allOf:
            - $ref: '#/components/schemas/NotificationRuleDeliveryMode'
          description: How notifications are delivered (immediate, daily digest, weekly digest).
          x-access-type: ReadWrite
          x-order: 9
        channelIds:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 20
            pattern: ^[A-Z0-9]{1,20}$
          description: The IDs of the notification channels to deliver to.
          x-access-type: ReadWrite
          x-order: 10
        enabled:
          type: boolean
          description: Whether the rule is currently active.
          default: true
          x-access-type: ReadWrite
          x-order: 11
        digestTime:
          type: string
          description: The time of day to send the digest (HH:MM, 24-hour clock). Must be set server-side when deliveryMode is daily_digest or weekly_digest.
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          example: '08:00'
          nullable: true
          x-access-type: ReadWrite
          x-order: 12
        digestTimezone:
          type: string
          minLength: 1
          maxLength: 64
          description: The IANA timezone for the digest time (e.g., 'America/New_York'). Must be set server-side when deliveryMode is daily_digest or weekly_digest.
          example: America/New_York
          nullable: true
          x-access-type: ReadWrite
          x-order: 13
        digestDayOfWeek:
          type: integer
          minimum: 0
          maximum: 6
          description: The day of the week to send the weekly digest (0=Sunday, 6=Saturday). Must be set server-side when deliveryMode is weekly_digest.
          nullable: true
          x-access-type: ReadWrite
          x-order: 14
        mutedUntil:
          type: string
          format: date-time
          description: Notifications are suppressed until this timestamp. Null means unmuted.
          nullable: true
          x-access-type: ReadWrite
          x-order: 15
    NotificationRuleSummary:
      type: object
      description: A summary of a notification rule.
      required:
        - id
        - name
        - resourceType
        - scopeType
        - eventTypes
        - deliveryMode
        - enabled
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notification rule ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the rule.
          x-access-type: ReadWrite
          x-order: 2
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team that owns this rule. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 3
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member that owns this rule. Mutually exclusive with teamId.
          x-access-type: ReadImmutable
          x-order: 4
        resourceType:
          type: string
          maxLength: 64
          description: The resource type this rule applies to (e.g., 'job_run').
          x-access-type: ReadImmutable
          x-order: 5
        scopeType:
          allOf:
            - $ref: '#/components/schemas/NotificationRuleScopeType'
          description: The scope of resources this rule applies to.
          x-access-type: ReadImmutable
          x-order: 6
        scopeId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the scoped resource or team. Omitted for organization and own_resources scope.
          x-access-type: ReadImmutable
          x-order: 7
        eventTypes:
          type: array
          items:
            type: string
            maxLength: 64
          description: The event types this rule subscribes to.
          x-access-type: ReadWrite
          x-order: 8
        deliveryMode:
          allOf:
            - $ref: '#/components/schemas/NotificationRuleDeliveryMode'
          description: How notifications are delivered (immediate, daily digest, weekly digest).
          x-access-type: ReadWrite
          x-order: 9
        channelIds:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 20
            pattern: ^[A-Z0-9]{1,20}$
          description: The IDs of the notification channels to deliver to.
          x-access-type: ReadWrite
          x-order: 10
        enabled:
          type: boolean
          description: Whether the rule is currently active.
          default: true
          x-access-type: ReadWrite
          x-order: 11
        digestTime:
          type: string
          description: The time of day to send the digest (HH:MM, 24-hour clock). Must be set server-side when deliveryMode is daily_digest or weekly_digest.
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          example: '08:00'
          nullable: true
          x-access-type: ReadWrite
          x-order: 12
        digestTimezone:
          type: string
          minLength: 1
          maxLength: 64
          description: The IANA timezone for the digest time (e.g., 'America/New_York'). Must be set server-side when deliveryMode is daily_digest or weekly_digest.
          example: America/New_York
          nullable: true
          x-access-type: ReadWrite
          x-order: 13
        digestDayOfWeek:
          type: integer
          minimum: 0
          maximum: 6
          description: The day of the week to send the weekly digest (0=Sunday, 6=Saturday). Must be set server-side when deliveryMode is weekly_digest.
          nullable: true
          x-access-type: ReadWrite
          x-order: 14
        mutedUntil:
          type: string
          format: date-time
          description: Notifications are suppressed until this timestamp. Null means unmuted.
          nullable: true
          x-access-type: ReadWrite
          x-order: 15
        createdAt:
          type: string
          format: date-time
          description: The time when the rule was created.
          x-access-type: ReadOnly
          x-order: 16
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member who created this rule.
          x-access-type: ReadOnly
          x-order: 17
        updatedAt:
          type: string
          format: date-time
          description: The time when the rule was last updated.
          x-access-type: ReadOnly
          x-order: 18
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the member who last updated this rule.
          x-access-type: ReadOnly
          x-order: 19
    NotificationRuleUpdate:
      type: object
      description: An update to a notification rule.
      x-filter-group: Update
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the rule.
          x-access-type: ReadWrite
          x-order: 2
        eventTypes:
          type: array
          items:
            type: string
            maxLength: 64
          description: The event types this rule subscribes to.
          x-access-type: ReadWrite
          x-order: 8
        deliveryMode:
          allOf:
            - $ref: '#/components/schemas/NotificationRuleDeliveryMode'
          description: How notifications are delivered (immediate, daily digest, weekly digest).
          x-access-type: ReadWrite
          x-order: 9
        channelIds:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 20
            pattern: ^[A-Z0-9]{1,20}$
          description: The IDs of the notification channels to deliver to.
          x-access-type: ReadWrite
          x-order: 10
        enabled:
          type: boolean
          description: Whether the rule is currently active.
          default: true
          x-access-type: ReadWrite
          x-order: 11
        digestTime:
          type: string
          description: The time of day to send the digest (HH:MM, 24-hour clock). Must be set server-side when deliveryMode is daily_digest or weekly_digest.
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          example: '08:00'
          nullable: true
          x-access-type: ReadWrite
          x-order: 12
        digestTimezone:
          type: string
          minLength: 1
          maxLength: 64
          description: The IANA timezone for the digest time (e.g., 'America/New_York'). Must be set server-side when deliveryMode is daily_digest or weekly_digest.
          example: America/New_York
          nullable: true
          x-access-type: ReadWrite
          x-order: 13
        digestDayOfWeek:
          type: integer
          minimum: 0
          maximum: 6
          description: The day of the week to send the weekly digest (0=Sunday, 6=Saturday). Must be set server-side when deliveryMode is weekly_digest.
          nullable: true
          x-access-type: ReadWrite
          x-order: 14
        mutedUntil:
          type: string
          format: date-time
          description: Notifications are suppressed until this timestamp. Null means unmuted.
          nullable: true
          x-access-type: ReadWrite
          x-order: 15
    NotificationStatus:
      type: string
      description: The delivery status of a notification.
      enum:
        - pending
        - delivering
        - delivered
        - failed
        - skipped
    NotificationSummary:
      type: object
      description: A notification delivery log entry.
      required:
        - id
        - ruleId
        - channelId
        - eventId
        - targetSummary
        - status
        - attempts
        - createdAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notification ID.
          x-access-type: ReadOnly
          x-order: 1
        ruleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notification rule that triggered this notification.
          x-access-type: ReadOnly
          x-order: 2
        channelId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notification channel used for delivery.
          x-access-type: ReadOnly
          x-order: 3
        eventId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notification event that triggered this notification.
          x-access-type: ReadOnly
          x-order: 4
        targetSummary:
          type: string
          maxLength: 512
          description: A masked summary of the delivery target (e.g., "o***@acme.com").
          x-access-type: ReadOnly
          x-order: 5
        status:
          allOf:
            - $ref: '#/components/schemas/NotificationStatus'
          description: The delivery status of this notification.
          x-access-type: ReadOnly
          x-order: 6
        statusMessage:
          type: string
          nullable: true
          description: Error details for failed deliveries.
          x-access-type: ReadOnly
          x-order: 7
        attempts:
          type: integer
          minimum: 0
          maximum: 25
          description: The number of delivery attempts made.
          x-access-type: ReadOnly
          x-order: 8
        lastAttemptAt:
          type: string
          format: date-time
          description: The time of the last delivery attempt.
          x-access-type: ReadOnly
          x-order: 9
        deliveredAt:
          type: string
          format: date-time
          description: The time when the notification was successfully delivered.
          x-access-type: ReadOnly
          x-order: 10
        createdAt:
          type: string
          format: date-time
          description: The time when the notification was created.
          x-access-type: ReadOnly
          x-order: 11
    OperationErrorDetails:
      type: object
      description: Error-specific details based on error type.
      properties:
        retryable:
          type: boolean
          description: Whether the operation can be retried
        retryAfter:
          type: integer
          description: Recommended number of seconds to wait before retrying
        fieldErrors:
          type: object
          additionalProperties:
            type: string
          description: Field-level validation errors (for VALIDATION_ERROR)
        requestId:
          type: string
          description: Request ID for tracing/debugging
        causedBy:
          type: string
          description: Root cause or original error message if wrapped
    OperationErrorInfo:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code (e.g., CONNECTION_FAILED, TIMEOUT)
        message:
          type: string
          description: Human-readable error message
        errorType:
          type: string
          enum:
            - VALIDATION_ERROR
            - AUTHORIZATION_ERROR
            - RESOURCE_NOT_FOUND
            - TIMEOUT_ERROR
            - SERVICE_ERROR
            - INTERNAL_ERROR
          description: Classification of the error type for client-side handling
        details:
          $ref: '#/components/schemas/OperationErrorDetails'
    OperationProgress:
      type: object
      description: Progress information for a long-running operation. Shape depends on operation type.
      oneOf:
        - $ref: '#/components/schemas/OperationProgressInfrastructure'
    OperationProgressInfrastructure:
      type: object
      description: Infrastructure provisioning/destroy progress details.
      properties:
        stage:
          $ref: '#/components/schemas/OperationProgressInfrastructureStage'
        message:
          type: string
          description: Human-readable status message.
        resources:
          type: array
          items:
            $ref: '#/components/schemas/OperationProgressInfrastructureResource'
          description: List of resources being operated on.
        summary:
          $ref: '#/components/schemas/OperationProgressInfrastructureSummary'
    OperationProgressInfrastructureResource:
      type: object
      description: Resource status for tracking individual infrastructure resources.
      properties:
        urn:
          type: string
          description: Unique resource identifier (Pulumi URN).
        type:
          type: string
          description: Resource type (e.g., aws:ec2/vpc:Vpc).
        name:
          type: string
          description: Human-readable resource name.
        operation:
          type: string
          description: Operation being performed (create, update, delete, same).
        status:
          allOf:
            - $ref: '#/components/schemas/OperationProgressInfrastructureResourceStatus'
          description: Current status of the resource operation.
        duration:
          type: integer
          nullable: true
          description: Duration in seconds (when completed).
    OperationProgressInfrastructureResourceStatus:
      type: string
      enum:
        - pending
        - running
        - succeeded
        - failed
      description: The current status of an individual infrastructure resource operation.
    OperationProgressInfrastructureStage:
      type: string
      description: The current stage of an infrastructure operation workflow.
      enum:
        - preparing
        - refreshing
        - provisioning
        - destroying
    OperationProgressInfrastructureSummary:
      type: object
      description: Summary counts for infrastructure resource operations.
      properties:
        total:
          type: integer
          description: Total number of resources being tracked.
        pending:
          type: integer
          description: Resources not yet started.
        running:
          type: integer
          description: Resources currently being processed.
        succeeded:
          type: integer
          description: Resources completed successfully.
        failed:
          type: integer
          description: Resources that failed.
        unchanged:
          type: integer
          description: Resources with no changes needed.
    OperationResourceType:
      type: string
      enum:
        - ExternalConnection
        - ExternalNetwork
        - ExternalCluster
        - ExternalCatalog
        - JobRun
      description: |
        The type of resource this operation is associated with.
        Used to query all active operations for a given resource.
    OperationResult:
      type: object
      description: The raw result of a long-running operation. The actual type depends on the Operation field in OperationSummary.
      oneOf:
        - $ref: '#/components/schemas/ExternalInstanceTypeList'
    OperationStatus:
      type: string
      enum:
        - pending
        - waiting
        - running
        - completed
        - failed
      description: Current status of the operation.
    OperationSummary:
      type: object
      description: A long-running operation summary.
      required:
        - id
        - operation
        - status
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The unique identifier for the operation.
          x-access-type: ReadOnly
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID associated with the operation.
          x-access-type: ReadOnly
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member ID who initiated the operation.
          x-access-type: ReadOnly
        operation:
          type: string
          maxLength: 50
          description: The operation name being executed asynchronously (e.g., ListExternalInstanceTypes).
          x-access-type: ReadOnly
        status:
          allOf:
            - $ref: '#/components/schemas/OperationStatus'
          x-access-type: ReadOnly
        result:
          allOf:
            - $ref: '#/components/schemas/OperationResult'
          nullable: true
          description: The raw result of the completed operation. Type depends on operation. Null for pending or failed operations.
          x-access-type: ReadOnly
        error:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OperationErrorInfo'
          description: Error information if the operation failed.
          x-access-type: ReadOnly
        progress:
          allOf:
            - $ref: '#/components/schemas/OperationProgress'
          nullable: true
          description: Live progress information for long-running operations. Shape depends on operation type.
          x-access-type: ReadOnly
        resourceType:
          allOf:
            - $ref: '#/components/schemas/OperationResourceType'
          nullable: true
          description: The type of resource this operation is associated with. Null for operations not bound to a specific resource.
          x-access-type: ReadOnly
        resourceId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: The ID of the resource this operation is associated with. Null for operations not bound to a specific resource.
          x-access-type: ReadOnly
        createdAt:
          type: string
          format: date-time
          description: The time when the operation was created.
          x-access-type: ReadOnly
        updatedAt:
          type: string
          format: date-time
          description: The time when the operation was last updated.
          x-access-type: ReadOnly
        startedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the operation execution started. Null while pending.
          x-access-type: ReadOnly
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the operation execution completed (either succeeded or failed). Null while pending or running.
          x-access-type: ReadOnly
    OrganizationRoleExpanded:
      type: object
      description: An expanded organization role summary with aggregate data.
      required:
        - role
        - memberCount
        - permissionCount
      properties:
        role:
          allOf:
            - $ref: '#/components/schemas/OrganizationRoleSummary'
          description: The organization role summary.
          x-order: 1
        memberCount:
          type: integer
          description: The total number of members who have this role.
          x-order: 2
        permissionCount:
          type: integer
          description: The total number of permissions (including expanded bundles) in this role.
          x-order: 3
    OrganizationRoleIncluded:
      type: object
      description: Related entities referenced by IDs in the role detail.
      required:
        - roles
        - permissions
        - bundles
      properties:
        roles:
          type: array
          description: Array of organization role entities with expanded data.
          items:
            $ref: '#/components/schemas/OrganizationRoleExpanded'
          x-order: 1
        permissions:
          type: array
          description: Array of permission definition entities.
          items:
            $ref: '#/components/schemas/PermissionDefinition'
          x-order: 2
        bundles:
          type: array
          description: Array of permission bundle entities.
          items:
            $ref: '#/components/schemas/PermissionBundleSummary'
          x-order: 3
    OrganizationRoleItem:
      type: object
      description: Organization role detail with entity ID references only.
      required:
        - roleId
        - permissionIds
        - bundleIds
        - bundlePermissions
      properties:
        roleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization role ID.
          x-order: 1
        permissionIds:
          type: array
          description: Direct permission relations assigned to this role (not part of bundles).
          items:
            type: string
          x-order: 2
        bundleIds:
          type: array
          description: Permission bundle IDs assigned to this role.
          items:
            type: string
          x-order: 3
        bundlePermissions:
          type: object
          description: Map of bundle ID to the permission relations within that bundle for this role.
          additionalProperties:
            type: array
            items:
              type: string
          x-order: 4
    OrganizationRoleList:
      type: object
      description: A list of organization roles.
      required:
        - total
        - items
      properties:
        total:
          type: integer
          description: The total number of organization roles found.
          x-order: 1
        items:
          type: array
          description: A list of organization roles with aggregate data.
          items:
            $ref: '#/components/schemas/OrganizationRoleExpanded'
          x-order: 2
    OrganizationRoleNormalized:
      type: object
      description: Organization role detail with normalized entity references.
      required:
        - item
        - included
      properties:
        item:
          allOf:
            - $ref: '#/components/schemas/OrganizationRoleItem'
          description: Role detail with ID references only.
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/OrganizationRoleIncluded'
          description: Full entity data for referenced IDs.
          x-order: 2
    OrganizationRoleSummary:
      type: object
      description: A summary of an organization role.
      required:
        - id
        - organizationId
        - name
        - allTeams
        - breakGlass
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization role ID.
          x-access-type: ReadOnly
          x-order: 1
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name of the role.
          x-access-type: ReadWrite
          x-order: 3
        description:
          type: string
          minLength: 1
          maxLength: 1023
          description: The description of the role.
          x-access-type: ReadWrite
          x-order: 4
        allTeams:
          type: boolean
          description: When true, members holding this org role are automatically added to every team in the organization.
          x-access-type: ReadOnly
          x-order: 5
        breakGlass:
          type: boolean
          description: When true, members holding this org role may log in with a password even when the organization has disabled password login. Intended as an emergency access (break-glass) escape hatch to recover when the IDP is unavailable. Break-glass logins are always subject to MFA when the org has requireMfa enabled or all direct login methods are disabled.
          x-access-type: ReadOnly
          x-order: 6
        createdAt:
          type: string
          format: date-time
          description: The time when the role was created.
          x-access-type: ReadOnly
          x-order: 7
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this role.
          x-access-type: ReadOnly
          x-order: 8
        updatedAt:
          type: string
          format: date-time
          description: The time when the role was last updated.
          x-access-type: ReadOnly
          x-order: 9
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this role.
          x-access-type: ReadOnly
          x-order: 10
    OrganizationSettings:
      type: object
      description: Organization Settings
      properties:
        auth:
          $ref: '#/components/schemas/OrganizationSettingsAuth'
        sessions:
          $ref: '#/components/schemas/OrganizationSettingsSessions'
    OrganizationSettingsAuth:
      type: object
      description: Authentication Settings for Organization
      properties:
        requireEmailVerification:
          type: boolean
          description: If true users must verify their email before they can login
        allowLoginWithPassword:
          type: boolean
          default: true
          description: |
            If true users can login with a password. Defaults to true.
            Cannot be set to false when acr is set to 1fa:pwd, as that would make login impossible.
        allowLoginWithEmail:
          type: boolean
          description: If true any user in the organization can login with just their email
        requireDpop:
          type: boolean
          description: |
            If true, all access tokens must use DPoP (Demonstrating Proof-of-Possession) for enhanced security.
            DPoP cryptographically binds tokens to the client device, preventing token theft and replay attacks.
            When enabled, all users in the organization must sign out and sign in again to receive DPoP-bound tokens.
            Recommended for organizations handling sensitive data (healthcare, financial services, PII).
        checkBreachedPasswords:
          type: boolean
          description: |
            If true, new and changed passwords are checked against the Have I Been Pwned database
            to prevent the use of passwords known to be compromised in data breaches.
            Uses k-anonymity to ensure passwords are never sent to external services.
        acr:
          $ref: '#/components/schemas/AcrValue'
    OrganizationSettingsSessions:
      type: object
      description: Session settings for the organization.
      properties:
        maxRunningWorkloads:
          type: integer
          nullable: true
          minimum: 1
          description: Maximum number of concurrently running workloads (compute pods) across the entire organization. Null means no org-level limit is enforced.
        maxConcurrentClients:
          type: integer
          nullable: true
          minimum: 1
          description: Maximum number of concurrently active sessions across the entire organization. Null means no org-level limit is enforced.
        maxConcurrentSessionsPerMember:
          type: integer
          nullable: true
          minimum: 1
          description: Maximum number of concurrently active sessions a single member may own. Null means no per-member limit is enforced.
        endpointFallback:
          $ref: '#/components/schemas/OrganizationSettingsSessionsEndpointConfig'
        endpointDefaults:
          type: object
          description: Per-endpoint timeout defaults and maximums. Absent endpoint means platform defaults apply.
          properties:
            spark_connect:
              $ref: '#/components/schemas/OrganizationSettingsSessionsEndpointConfig'
    OrganizationSettingsSessionsEndpointConfig:
      type: object
      description: Organization-level configuration for a specific session endpoint. Controls the default timeout values applied to new sessions on this endpoint and the maximum values members are permitted to request.
      properties:
        defaults:
          $ref: '#/components/schemas/OrganizationSettingsSessionsTimeoutConfig'
        maximums:
          $ref: '#/components/schemas/OrganizationSettingsSessionsTimeoutConfig'
    OrganizationSettingsSessionsTimeoutConfig:
      type: object
      description: Timeout configuration for a session endpoint. All fields are optional; null means the platform default applies.
      properties:
        idleTimeoutSeconds:
          type: integer
          nullable: true
          minimum: 60
          description: Seconds of inactivity before a session transitions to idle. Null means use the platform default.
        idleCloseDelaySeconds:
          type: integer
          nullable: true
          minimum: 0
          description: Seconds an idle session may remain before it is automatically closed. Null means use the platform default.
        maxDurationSeconds:
          type: integer
          nullable: true
          minimum: 300
          description: Maximum lifetime of a session regardless of activity. Null means there is no enforced maximum duration.
    OrganizationSlug:
      type: string
      description: The slug of an organization.
      minLength: 2
      maxLength: 63
      pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]{2,63}$
      example: acme-corp
    OrganizationSummary:
      type: object
      description: An organization.
      required:
        - id
        - slug
        - name
        - settings
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadOnly
          x-order: 1
        slug:
          allOf:
            - $ref: '#/components/schemas/OrganizationSlug'
          description: The organization slug.
          x-access-type: ReadWrite
          x-order: 2
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The organization name.
          x-access-type: ReadWrite
          x-order: 3
        settings:
          allOf:
            - $ref: '#/components/schemas/OrganizationSettings'
          description: The settings for the organization.
          x-access-type: ReadWrite
          x-order: 4
        defaultTeamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: The ID of the default team for this organization.
          x-access-type: ReadWrite
          x-order: 9
        defaultOrgRoleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: The ID of the default organization role assigned to new members when invited.
          x-access-type: ReadWrite
          x-order: 10
    OtaCodeHash:
      type: string
      description: The one time authentication code hash.
      pattern: ^[a-zA-Z0-9_\-=]{7,}$
    Password:
      type: string
      description: A password.
      minLength: 8
      maxLength: 256
    PermissionBundleSummary:
      type: object
      description: Permission bundle summary for list views.
      required:
        - id
        - code
        - name
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The permission bundle ID.
          x-access-type: ReadOnly
          x-order: 1
        code:
          type: string
          description: The immutable identifier key of the bundle (e.g., "user_management_full"). Must be lowercase alphanumeric with underscores.
          minLength: 2
          maxLength: 64
          pattern: ^[a-z0-9_]+$
          x-access-type: ReadImmutable
          x-order: 2
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID (NULL for system bundles).
          x-access-type: ReadImmutable
          x-order: 3
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The display name of the bundle.
          x-access-type: ReadWrite
          x-order: 4
        description:
          type: string
          minLength: 1
          maxLength: 1023
          description: The description of the bundle.
          x-access-type: ReadWrite
          x-order: 5
        createdAt:
          type: string
          format: date-time
          description: The time when the bundle was created.
          x-access-type: ReadOnly
          x-order: 6
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this bundle.
          x-access-type: ReadOnly
          x-order: 7
        updatedAt:
          type: string
          format: date-time
          description: The time when the bundle was last updated.
          x-access-type: ReadOnly
          x-order: 8
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this bundle.
          x-access-type: ReadOnly
          x-order: 9
    PermissionDefinition:
      type: object
      description: A permission definition with metadata
      required:
        - relation
        - description
        - systemOnly
      properties:
        relation:
          type: string
          description: The permission relation identifier (e.g., "CanManageUsers")
          example: CanManageUsers
        description:
          type: string
          description: Human-readable description of what this permission allows
          example: Manage user resources
        validObjectTypes:
          type: array
          items:
            type: string
          description: List of resource types this permission can be applied to
          example:
            - organization
            - team
        systemOnly:
          type: boolean
          description: Whether this permission is restricted to system operations only
          default: false
    PermissionDefinitionList:
      type: object
      description: List of permission definitions
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PermissionDefinition'
    Policy:
      type: object
      description: A resource policy.
      required:
        - principal
        - permissions
        - createdAt
        - updatedAt
      properties:
        principal:
          allOf:
            - $ref: '#/components/schemas/ResourceDescriptor'
          description: The principal to which the resource permissions are granted.
          x-order: 1
        permissions:
          type: array
          description: A list of resource permissions.
          items:
            allOf:
              - $ref: '#/components/schemas/ResourceRelation'
            description: A resource permission granted to the principal.
          minItems: 1
          x-order: 2
        createdAt:
          type: string
          format: date-time
          description: The time when the earliest permission was granted.
          x-order: 3
        updatedAt:
          type: string
          format: date-time
          description: The time when the latest permission was granted.
          x-order: 4
    PolicyList:
      type: object
      description: A list of resource policies.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of resource policies.
          items:
            $ref: '#/components/schemas/Policy'
          x-order: 1
        marker:
          allOf:
            - $ref: '#/components/schemas/ResourceDescriptorString'
          description: The pagination token to request more items.
          x-order: 2
    PolicySpec:
      type: object
      description: The specification of a resource policy.
      required:
        - permissions
      properties:
        permissions:
          type: array
          description: A list of resource permissions.
          items:
            allOf:
              - $ref: '#/components/schemas/ResourceRelation'
            description: A resource permission to grant.
          minItems: 1
          x-order: 1
    ProviderCapabilities:
      type: object
      description: Capabilities and features supported by the identity provider
      required:
        - dcr
      properties:
        dcr:
          $ref: '#/components/schemas/DCRCapability'
        requiresClientSecret:
          type: boolean
          description: |
            Whether this provider requires a client_secret during the OAuth authorization code → token exchange. When true, the exchange cannot be performed safely in the browser and must be proxied through a backend/BFF. True for confidential OAuth clients (e.g. Google) that do not support PKCE-only public client flows.
    ProviderMetadata:
      type: object
      description: Metadata about the identity provider for UI display and documentation
      properties:
        documentationUrl:
          type: string
          format: uri
          description: URL to the provider's documentation
        logoUrl:
          type: string
          format: uri
          description: URL to the provider's logo
        setupComplexity:
          allOf:
            - $ref: '#/components/schemas/ProviderSetupComplexity'
          description: Complexity level of setting up this provider
        vendorType:
          allOf:
            - $ref: '#/components/schemas/ProviderVendorType'
          description: Type of vendor deployment model
        defaultIssuer:
          type: string
          format: uri
          description: |
            Fixed issuer URL for providers with a single well-known issuer (e.g. Google). When present, the manual setup form pre-fills the issuer field with this value.
        issuerTemplate:
          type: string
          description: |
            Template string showing the issuer URL pattern for providers where the URL contains tenant- or account-specific components (e.g. Azure, Cognito). Used as the issuer field placeholder in the manual setup form. Example: "https://login.microsoftonline.com/{tenant-id}/v2.0"
    ProviderNetwork:
      type: object
      description: |
        A virtual network available in a cloud provider.
        This is a cloud-provider-agnostic parent type that can be extended
        with provider-specific implementations.
      oneOf:
        - $ref: '#/components/schemas/ProviderNetworkAws'
    ProviderNetworkAws:
      type: object
      description: AWS VPC information for cluster networking
      required:
        - provider
        - vpcId
        - cidr
        - name
        - azCount
        - state
      properties:
        provider:
          allOf:
            - $ref: '#/components/schemas/CloudProvider'
            - enum:
                - AWS
          x-order: 1
        vpcId:
          type: string
          description: The AWS VPC ID (e.g., vpc-0123456789abcdef0)
          example: vpc-0123456789abcdef0
          x-access-type: ReadOnly
          x-order: 2
        cidr:
          type: string
          description: The VPC CIDR block (e.g., 10.0.0.0/16)
          example: 10.0.0.0/16
          x-access-type: ReadOnly
          x-order: 3
        name:
          type: string
          description: The VPC name (friendly identifier)
          example: Production VPC
          x-access-type: ReadOnly
          x-order: 4
        azCount:
          type: integer
          minimum: 1
          description: Number of Availability Zones in this VPC
          example: 3
          x-access-type: ReadOnly
          x-order: 5
        state:
          allOf:
            - $ref: '#/components/schemas/ProviderNetworkAwsState'
          description: The VPC state (e.g., available, pending)
          example: available
          x-access-type: ReadOnly
          x-order: 6
        tags:
          type: object
          description: AWS tags on the VPC for identification and filtering
          additionalProperties:
            type: string
          x-access-type: ReadOnly
          x-order: 7
    ProviderNetworkAwsState:
      type: string
      enum:
        - available
        - pending
        - deleting
        - deleted
      description: The state of an AWS VPC.
    ProviderSetupComplexity:
      type: string
      enum:
        - easy
        - medium
        - hard
      description: Complexity level of setting up an identity provider.
    ProviderType:
      type: string
      description: The identity provider type, which determines protocol behavior and available features.
      enum:
        - generic
        - okta
        - auth0
    ProviderVendorType:
      type: string
      enum:
        - saas
        - self-hosted
        - hybrid
      description: Type of vendor deployment model for an identity provider.
    QueryIncluded:
      type: object
      description: |
        Included entities for query responses.
      properties:
        queries:
          type: array
          description: Array of query entities
          items:
            $ref: '#/components/schemas/QuerySummary'
        catalogs:
          type: array
          description: Array of catalog summaries linked to this query.
          items:
            $ref: '#/components/schemas/CatalogSummary'
        teams:
          type: array
          description: Array of expanded team objects associated with queries; each item contains a `team` summary and a `memberCount`.
          items:
            $ref: '#/components/schemas/TeamExpanded'
        jobs:
          type: array
          description: Array of job summaries that reference this query.
          items:
            $ref: '#/components/schemas/JobSummary'
    QueryItem:
      type: object
      description: A query reference containing only IDs for related entities.
      required:
        - queryId
      properties:
        queryId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The query ID
        teamIds:
          type: array
          description: Array of team IDs associated with this query
          items:
            allOf:
              - $ref: '#/components/schemas/ResourceId'
        catalogId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: ID of the linked managed catalog, if any.
        jobIds:
          type: array
          description: Array of IDs of jobs that reference this query
          items:
            allOf:
              - $ref: '#/components/schemas/ResourceId'
    QueryList:
      type: object
      description: A list of LakeSail queries.
      required:
        - total
        - items
        - included
      properties:
        total:
          type: integer
          description: The total number of queries accessible to the member.
          x-order: 1
        items:
          type: array
          description: Query list items with ID references only.
          items:
            $ref: '#/components/schemas/QueryItem'
          x-order: 2
        included:
          allOf:
            - $ref: '#/components/schemas/QueryIncluded'
          description: Related entities referenced by IDs in the list items.
          x-order: 3
    QueryNormalized:
      type: object
      description: A single query with related entities included.
      required:
        - item
        - included
      properties:
        item:
          allOf:
            - $ref: '#/components/schemas/QueryItem'
          description: Query with ID references only.
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/QueryIncluded'
          description: Full entity data for referenced IDs.
          x-order: 2
    QuerySpec:
      type: object
      description: The specification to create a query
      required:
        - teamIds
        - name
        - queryText
      x-filter-group: Spec
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Display name of the query that appears in list views, widget headings, and on the query page.
          example: Daily Sales Summary
          x-access-type: ReadWrite
          x-order: 3
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: General description that conveys additional information about this query such as usage notes.
          x-access-type: ReadWrite
          x-order: 4
        catalog_schema:
          type: string
          maxLength: 255
          description: Name of the schema where this query will be executed.
          example: analytics
          x-access-type: ReadWrite
          x-order: 5
        catalogId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: |
            ID of a managed catalog to use for this query. When set, the catalog's provider configuration is used for execution. Set to null to use catalog_schema directly.
          x-access-type: ReadWrite
          x-order: 6
        queryText:
          type: string
          minLength: 1
          maxLength: 8191
          description: Text of the query to be run.
          example: SELECT region, SUM(amount) FROM sales GROUP BY region
          x-access-type: ReadWrite
          x-order: 7
        tags:
          type: array
          description: Tags for categorizing and organizing queries.
          items:
            type: string
          example:
            - etl
            - sales
            - daily
          x-access-type: ReadWrite
          x-order: 8
        teamIds:
          type: array
          description: The team IDs that will have access to this query.
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/ResourceId'
    QuerySummary:
      type: object
      description: A summary of a LakeSail query.
      required:
        - id
        - memberId
        - name
        - queryText
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The query ID.
          x-access-type: ReadOnly
          x-order: 1
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: ID of the member who created this query.
          x-access-type: ReadOnly
          x-order: 2
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Display name of the query that appears in list views, widget headings, and on the query page.
          example: Daily Sales Summary
          x-access-type: ReadWrite
          x-order: 3
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: General description that conveys additional information about this query such as usage notes.
          x-access-type: ReadWrite
          x-order: 4
        catalog_schema:
          type: string
          maxLength: 255
          description: Name of the schema where this query will be executed.
          example: analytics
          x-access-type: ReadWrite
          x-order: 5
        catalogId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: |
            ID of a managed catalog to use for this query. When set, the catalog's provider configuration is used for execution. Set to null to use catalog_schema directly.
          x-access-type: ReadWrite
          x-order: 6
        queryText:
          type: string
          minLength: 1
          maxLength: 8191
          description: Text of the query to be run.
          example: SELECT region, SUM(amount) FROM sales GROUP BY region
          x-access-type: ReadWrite
          x-order: 7
        tags:
          type: array
          description: Tags for categorizing and organizing queries.
          items:
            type: string
          example:
            - etl
            - sales
            - daily
          x-access-type: ReadWrite
          x-order: 8
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this query was created.
          x-access-type: ReadOnly
          x-order: 9
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this query.
          x-access-type: ReadOnly
          x-order: 10
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this query was last updated.
          x-access-type: ReadOnly
          x-order: 11
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this query.
          x-access-type: ReadOnly
          x-order: 12
    QueryTeamList:
      type: object
      description: A list of teams associated with a query.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of query-team associations.
          items:
            $ref: '#/components/schemas/QueryTeamSummary'
          x-order: 1
    QueryTeamSummary:
      type: object
      description: A summary of a query-team association.
      required:
        - queryId
        - teamId
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        queryId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The query ID.
          x-access-type: ReadImmutable
          x-order: 1
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team ID.
          x-access-type: ReadImmutable
          x-order: 2
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this association was created.
          x-access-type: ReadOnly
          x-order: 3
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this association.
          x-access-type: ReadOnly
          x-order: 4
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this association was last updated.
          x-access-type: ReadOnly
          x-order: 5
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this association.
          x-access-type: ReadOnly
          x-order: 6
    QueryUpdate:
      type: object
      description: An update to a query.
      x-filter-group: Update
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Display name of the query that appears in list views, widget headings, and on the query page.
          example: Daily Sales Summary
          x-access-type: ReadWrite
          x-order: 3
        description:
          allOf:
            - $ref: '#/components/schemas/ResourceDescription'
          description: General description that conveys additional information about this query such as usage notes.
          x-access-type: ReadWrite
          x-order: 4
        catalog_schema:
          type: string
          maxLength: 255
          description: Name of the schema where this query will be executed.
          example: analytics
          x-access-type: ReadWrite
          x-order: 5
        catalogId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: |
            ID of a managed catalog to use for this query. When set, the catalog's provider configuration is used for execution. Set to null to use catalog_schema directly.
          x-access-type: ReadWrite
          x-order: 6
        queryText:
          type: string
          minLength: 1
          maxLength: 8191
          description: Text of the query to be run.
          example: SELECT region, SUM(amount) FROM sales GROUP BY region
          x-access-type: ReadWrite
          x-order: 7
        tags:
          type: array
          description: Tags for categorizing and organizing queries.
          items:
            type: string
          example:
            - etl
            - sales
            - daily
          x-access-type: ReadWrite
          x-order: 8
    ResetPassword:
      type: object
      description: The result of a password reset.
      required:
        - password
      properties:
        password:
          allOf:
            - $ref: '#/components/schemas/Password'
          description: The new password after the reset.
          x-order: 1
    ResourceCode:
      type: string
      description: A human-readable resource code/identifier. Must be lowercase alphanumeric with optional hyphens and underscores.
      pattern: ^[a-z0-9][a-z0-9_-]{0,31}$
      minLength: 1
      maxLength: 32
      example: keycloak
    ResourceDescription:
      type: string
      description: The description of a resource.
      minLength: 1
      maxLength: 1000
      example: Daily ETL pipeline for sales data
    ResourceDescriptor:
      type: object
      description: |
        An identifier that uniquely identifies a resource with its type.
        where `<id>` is the resource ID for an organization, a service account, or a user, respectively.
      required:
        - type
        - id
      properties:
        type:
          $ref: '#/components/schemas/ResourceType'
        id:
          $ref: '#/components/schemas/ResourceId'
    ResourceDescriptorString:
      type: string
      description: |
        An identifier that uniquely identifies a resource with its type.
        Valid values include `organization:<id>`, `service-account:<id>`, and `user:<id>`,
        where `<id>` is the resource ID for an organization, a service account, or a user, respectively.
      minLength: 6
      maxLength: 36
      pattern: ^(organization|service-account|user|):[A-Z0-9]{1,20}$
    ResourceId:
      type: string
      description: The unique identifier of a resource.
      minLength: 1
      maxLength: 20
      pattern: ^[A-Z0-9]{1,20}$
      example: A1B2C3D4E5
    ResourceName:
      type: string
      description: The name of a resource.
      minLength: 1
      maxLength: 255
      example: Production Cluster
    ResourceRelation:
      type: string
      description: |
        The relation between two resources.
        Relations are used to specify permissions in resource policies,
        where the allowed relations depend on the resource type.
      enum:
        - CanManageOrganization
        - CanManageServiceAccount
        - CanEditLakeSailResources
        - CanViewLakeSailResources
    ResourceType:
      type: string
      description: Known policy resources
      enum:
        - organization
        - user
        - service-account
    RetryJobRunSpec:
      type: object
      description: |
        Options for retrying a job run.
        If hold is true, the run transitions to `pending` instead of `ready`.
      properties:
        hold:
          type: boolean
          description: |
            When true, the retried run transitions to `pending` instead of `ready`,
            requiring an explicit Release call before the worker picks it up.
            Defaults to false.
    RotateSecretSpec:
      type: object
      description: The specification to rotate an identity provider's client secret.
      required:
        - clientSecret
      properties:
        clientSecret:
          type: string
          description: The new client secret obtained from the identity provider.
          minLength: 1
          format: password
    ServiceAccount:
      type: object
      description: A service account.
      required:
        - id
        - username
        - description
        - createdAt
        - updatedAt
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The service account ID.
          x-access-type: ReadOnly
          x-order: 1
        username:
          allOf:
            - $ref: '#/components/schemas/Username'
          description: The username of the service account.
          x-access-type: ReadWrite
          x-order: 2
        description:
          type: string
          minLength: 1
          maxLength: 1023
          description: The description of the service account.
          x-access-type: ReadWrite
          x-order: 3
        createdAt:
          type: string
          format: date-time
          description: The time when the service account was created.
          x-access-type: ReadOnly
          x-order: 4
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this service account.
          x-access-type: ReadOnly
          x-order: 5
        updatedAt:
          type: string
          format: date-time
          description: The time when the service account was last updated.
          x-access-type: ReadOnly
          x-order: 6
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this service account.
          x-access-type: ReadOnly
          x-order: 7
    ServiceAccountSummary:
      type: object
      description: A summary of a service account.
      required:
        - id
        - username
        - description
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The service account ID.
          x-access-type: ReadOnly
          x-order: 1
        username:
          allOf:
            - $ref: '#/components/schemas/Username'
          description: The username of the service account.
          x-access-type: ReadWrite
          x-order: 2
        description:
          type: string
          minLength: 1
          maxLength: 1023
          description: The description of the service account.
          x-access-type: ReadWrite
          x-order: 3
        createdAt:
          type: string
          format: date-time
          description: The time when the service account was created.
          x-access-type: ReadOnly
          x-order: 4
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this service account.
          x-access-type: ReadOnly
          x-order: 5
        updatedAt:
          type: string
          format: date-time
          description: The time when the service account was last updated.
          x-access-type: ReadOnly
          x-order: 6
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this service account.
          x-access-type: ReadOnly
          x-order: 7
    Session:
      type: object
      description: A session with full detail.
      required:
        - id
        - endpointType
        - name
        - status
        - teamId
        - createdAt
        - updatedAt
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The session ID.
          x-access-type: ReadOnly
          x-order: 1
        endpointType:
          allOf:
            - $ref: '#/components/schemas/SessionEndpoint'
          description: The endpoint protocol this session uses (e.g. spark_connect). Determines transport and proxy routing.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the session.
          x-access-type: ReadImmutable
          x-order: 3
        status:
          allOf:
            - $ref: '#/components/schemas/SessionStatus'
          description: The current lifecycle status of the session.
          x-access-type: ReadOnly
          x-order: 4
        workloadId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The workload this session is connected to.
          x-access-type: ReadOnly
          x-order: 5
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team this session belongs to.
          x-access-type: ReadImmutable
          x-order: 6
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member who owns this session. Mutually exclusive with serviceAccountId.
          x-access-type: ReadImmutable
          x-order: 7
        serviceAccountId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The service account that owns this session. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 8
        notebookId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notebook associated with this session, if any.
          x-access-type: ReadImmutable
          x-order: 9
        terminationReason:
          allOf:
            - $ref: '#/components/schemas/SessionTerminationReason'
          description: The reason this session was terminated, if applicable.
          x-access-type: ReadOnly
          x-order: 10
        statusMessage:
          type: string
          nullable: true
          description: Error details when the session is in the failed state.
          x-access-type: ReadOnly
          x-order: 11
        connectionInfo:
          allOf:
            - $ref: '#/components/schemas/SessionConnectionInfo'
          description: Connection details for accessing the session. Only returned to the session owner.
          x-access-type: ReadOnly
          x-order: 12
        lastActivityAt:
          type: string
          format: date-time
          description: The time of the last proxy request to this session.
          x-access-type: ReadOnly
          x-order: 13
        idleSince:
          type: string
          format: date-time
          description: The time when the session entered the idle state.
          x-access-type: ReadOnly
          x-order: 14
        closedAt:
          type: string
          format: date-time
          description: The time when the session was closed.
          x-access-type: ReadOnly
          x-order: 15
        timeoutAt:
          type: string
          format: date-time
          description: The absolute time when this session will be force-closed due to max duration. Set at creation (created_at + config.maxDurationSeconds).
          x-access-type: ReadOnly
          x-order: 16
        config:
          allOf:
            - $ref: '#/components/schemas/SessionConfig'
          description: Session timeout configuration. Resolved from request + org defaults at creation.
          x-access-type: ReadImmutable
          x-order: 17
        metadata:
          type: object
          description: Arbitrary key-value metadata for orchestrator correlation. Maximum 20 keys, each value up to 1KB.
          maxProperties: 20
          additionalProperties:
            type: string
            maxLength: 1024
          x-access-type: ReadImmutable
          x-order: 18
        createdAt:
          type: string
          format: date-time
          description: The time when the session was created.
          x-access-type: ReadOnly
          x-order: 19
        updatedAt:
          type: string
          format: date-time
          description: The time when the session was last updated.
          x-access-type: ReadOnly
          x-order: 20
    SessionConfig:
      type: object
      description: Configuration for a session. Controls timeout behavior. If not provided, organization defaults are used.
      properties:
        idleTimeoutSeconds:
          type: integer
          nullable: true
          minimum: 60
          description: Seconds of inactivity before transitioning to idle.
        idleCloseDelaySeconds:
          type: integer
          nullable: true
          minimum: 30
          description: Seconds a session may remain idle before automatic close.
        maxDurationSeconds:
          type: integer
          nullable: true
          minimum: 300
          description: Maximum lifetime of the session regardless of activity.
    SessionConnectionInfo:
      type: object
      description: Connection information for accessing a session. Which fields are populated depends on the endpoint's transport (HTTP → proxyAuthUrl, gRPC → grpcEndpoint).
      properties:
        proxyAuthUrl:
          type: string
          description: URL for authenticating an iframe connection to this session. Contains a short-lived signed token. Only present for HTTP-transport endpoints (e.g. marimo) owned by the requesting member.
          x-access-type: ReadOnly
          x-order: 1
        grpcEndpoint:
          type: string
          description: gRPC endpoint (host:port) for connecting via sc:// or Arrow Flight SQL. Only present for gRPC-transport endpoints (e.g. spark_connect, arrow_flight) and only for the session owner.
          x-access-type: ReadOnly
          x-order: 2
    SessionEndpoint:
      type: string
      description: The endpoint protocol this session uses. Determines the transport (HTTP or gRPC) and which address the proxy resolves. Engine-defined values validated in service layer.
      enum:
        - spark_connect
    SessionIncluded:
      type: object
      description: Related entities for session list responses.
      required:
        - sessions
        - members
        - serviceAccounts
        - workloads
        - workloadConfigs
      properties:
        sessions:
          type: array
          description: Session summaries referenced by items.
          items:
            $ref: '#/components/schemas/SessionSummary'
          x-order: 1
        members:
          type: array
          description: Members who own sessions in this response.
          items:
            $ref: '#/components/schemas/MemberSummary'
          x-order: 2
        serviceAccounts:
          type: array
          description: Service accounts that own sessions in this response.
          items:
            $ref: '#/components/schemas/ServiceAccountSummary'
          x-order: 3
        workloads:
          type: array
          description: Workloads referenced by sessions in this response.
          items:
            $ref: '#/components/schemas/WorkloadSummary'
          x-order: 4
        workloadConfigs:
          type: array
          description: Workload configs (compute profiles) referenced by workloads in this response.
          items:
            $ref: '#/components/schemas/WorkloadConfigSummary'
          x-order: 5
    SessionItem:
      type: object
      description: Session reference with ID and relationship IDs for normalized responses.
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The session ID.
          x-order: 1
        computeInstanceId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The compute instance this session is connected to.
          x-order: 2
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member who owns this session. Mutually exclusive with serviceAccountId.
          x-order: 3
        serviceAccountId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The service account that owns this session. Mutually exclusive with memberId.
          x-order: 4
    SessionList:
      type: object
      description: A list of sessions.
      required:
        - items
        - included
      properties:
        total:
          type: integer
          description: The total number of sessions.
          nullable: true
          x-order: 1
        items:
          type: array
          description: Session references with relationship IDs.
          items:
            $ref: '#/components/schemas/SessionItem'
          x-order: 2
        included:
          allOf:
            - $ref: '#/components/schemas/SessionIncluded'
          x-order: 3
        marker:
          type: string
          description: The pagination token to request more items.
          x-order: 4
    SessionSpec:
      type: object
      description: The specification to create a session.
      required:
        - endpointType
        - name
        - teamId
        - workloadConfigId
      x-filter-group: Spec
      properties:
        endpointType:
          allOf:
            - $ref: '#/components/schemas/SessionEndpoint'
          description: The endpoint protocol this session uses (e.g. spark_connect). Determines transport and proxy routing.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the session.
          x-access-type: ReadImmutable
          x-order: 3
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team this session belongs to.
          x-access-type: ReadImmutable
          x-order: 6
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member who owns this session. Mutually exclusive with serviceAccountId.
          x-access-type: ReadImmutable
          x-order: 7
        serviceAccountId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The service account that owns this session. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 8
        notebookId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notebook associated with this session, if any.
          x-access-type: ReadImmutable
          x-order: 9
        config:
          allOf:
            - $ref: '#/components/schemas/SessionConfig'
          description: Session timeout configuration. Resolved from request + org defaults at creation.
          x-access-type: ReadImmutable
          x-order: 17
        metadata:
          type: object
          description: Arbitrary key-value metadata for orchestrator correlation. Maximum 20 keys, each value up to 1KB.
          maxProperties: 20
          additionalProperties:
            type: string
            maxLength: 1024
          x-access-type: ReadImmutable
          x-order: 18
        workloadConfigId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: ID of a named workload config (compute profile) to use for this session.
          x-order: 21
        allowShared:
          type: boolean
          description: When true, allow reusing an existing workload with available capacity for this endpoint. When false (default), always provision a new workload.
          default: false
          x-order: 22
    SessionStatus:
      type: string
      description: The lifecycle status of a session.
      enum:
        - pending
        - active
        - idle
        - closed
        - failed
    SessionSummary:
      type: object
      description: A summary of a session.
      required:
        - id
        - endpointType
        - name
        - status
        - teamId
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The session ID.
          x-access-type: ReadOnly
          x-order: 1
        endpointType:
          allOf:
            - $ref: '#/components/schemas/SessionEndpoint'
          description: The endpoint protocol this session uses (e.g. spark_connect). Determines transport and proxy routing.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the session.
          x-access-type: ReadImmutable
          x-order: 3
        status:
          allOf:
            - $ref: '#/components/schemas/SessionStatus'
          description: The current lifecycle status of the session.
          x-access-type: ReadOnly
          x-order: 4
        workloadId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The workload this session is connected to.
          x-access-type: ReadOnly
          x-order: 5
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team this session belongs to.
          x-access-type: ReadImmutable
          x-order: 6
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member who owns this session. Mutually exclusive with serviceAccountId.
          x-access-type: ReadImmutable
          x-order: 7
        serviceAccountId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The service account that owns this session. Mutually exclusive with memberId.
          x-access-type: ReadImmutable
          x-order: 8
        notebookId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The notebook associated with this session, if any.
          x-access-type: ReadImmutable
          x-order: 9
        terminationReason:
          allOf:
            - $ref: '#/components/schemas/SessionTerminationReason'
          description: The reason this session was terminated, if applicable.
          x-access-type: ReadOnly
          x-order: 10
        statusMessage:
          type: string
          nullable: true
          description: Error details when the session is in the failed state.
          x-access-type: ReadOnly
          x-order: 11
        connectionInfo:
          allOf:
            - $ref: '#/components/schemas/SessionConnectionInfo'
          description: Connection details for accessing the session. Only returned to the session owner.
          x-access-type: ReadOnly
          x-order: 12
        lastActivityAt:
          type: string
          format: date-time
          description: The time of the last proxy request to this session.
          x-access-type: ReadOnly
          x-order: 13
        idleSince:
          type: string
          format: date-time
          description: The time when the session entered the idle state.
          x-access-type: ReadOnly
          x-order: 14
        closedAt:
          type: string
          format: date-time
          description: The time when the session was closed.
          x-access-type: ReadOnly
          x-order: 15
        timeoutAt:
          type: string
          format: date-time
          description: The absolute time when this session will be force-closed due to max duration. Set at creation (created_at + config.maxDurationSeconds).
          x-access-type: ReadOnly
          x-order: 16
        config:
          allOf:
            - $ref: '#/components/schemas/SessionConfig'
          description: Session timeout configuration. Resolved from request + org defaults at creation.
          x-access-type: ReadImmutable
          x-order: 17
        metadata:
          type: object
          description: Arbitrary key-value metadata for orchestrator correlation. Maximum 20 keys, each value up to 1KB.
          maxProperties: 20
          additionalProperties:
            type: string
            maxLength: 1024
          x-access-type: ReadImmutable
          x-order: 18
        createdAt:
          type: string
          format: date-time
          description: The time when the session was created.
          x-access-type: ReadOnly
          x-order: 19
        updatedAt:
          type: string
          format: date-time
          description: The time when the session was last updated.
          x-access-type: ReadOnly
          x-order: 20
    SessionTerminationReason:
      type: string
      description: The reason a session was terminated or failed.
      enum:
        - user_closed
        - admin_closed
        - idle_timeout
        - max_duration
        - provision_failed
    SessionToken:
      type: object
      description: A short-lived bearer token for authenticating with the session gRPC proxy.
      required:
        - token
        - expiresAt
      properties:
        token:
          allOf:
            - $ref: '#/components/schemas/Jwt'
          description: "A signed bearer JWT for authenticating with the gRPC proxy. Use the grpcEndpoint from the session's connectionInfo as the dial address and pass this token as the Authorization gRPC metadata: Bearer <token>. The session ID and routing target are embedded in the token claims."
          x-order: 1
        expiresAt:
          type: string
          format: date-time
          description: The UTC timestamp at which the token expires.
          x-order: 2
    ShutdownPolicy:
      type: string
      description: The shutdown policy for a workload.
      enum:
        - last_client_disconnects
        - explicit_stop
    SignupNextStep:
      type: string
      description: The next step in the organization setup process.
      enum:
        - setup_mfa
        - verify_email
        - completed
    SignupSummary:
      type: object
      description: The summary after signing up for an organization and user.
      required:
        - organization
        - user
        - nextStep
      properties:
        organization:
          allOf:
            - $ref: '#/components/schemas/OrganizationSummary'
        user:
          allOf:
            - $ref: '#/components/schemas/UserSummary'
        otaCode:
          allOf:
            - $ref: '#/components/schemas/OtaCodeHash'
        nextStep:
          allOf:
            - $ref: '#/components/schemas/SignupNextStep'
    SourceConfig:
      type: object
      description: Version control system repository configuration for source files.
      required:
        - url
        - provider
      properties:
        url:
          type: string
          description: Repository URL (supports Git, SVN, Mercurial, etc.)
          example: https://github.com/acme/data-pipelines.git
          x-order: 1
        provider:
          allOf:
            - $ref: '#/components/schemas/VcsProvider'
          description: VCS provider type
          x-order: 2
        reference:
          allOf:
            - $ref: '#/components/schemas/VcsReference'
          description: VCS reference to checkout (branch, tag, revision, etc.)
          x-order: 3
        snapshotCommit:
          type: string
          description: Read-only snapshot of the repository state at runtime. This field is only included on job runs.
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
          x-access-type: ReadOnly
          x-order: 4
    TeamAssignment:
      type: object
      description: A team assignment for an invited member. Both teamId and roleId are required.
      required:
        - teamId
        - roleId
      properties:
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team ID to assign the member to.
        roleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team role ID to assign to the member within this team.
    TeamExpanded:
      type: object
      description: An expanded team summary with member count.
      required:
        - team
        - memberCount
      properties:
        team:
          allOf:
            - $ref: '#/components/schemas/TeamSummary'
          description: The team summary.
          x-order: 1
        memberCount:
          type: integer
          description: The total number of members in the team.
          x-order: 2
    TeamList:
      type: object
      description: A list of teams.
      required:
        - total
        - items
      properties:
        total:
          type: integer
          description: The total number of teams found.
          x-order: 1
        items:
          type: array
          description: A list of teams.
          items:
            $ref: '#/components/schemas/TeamExpanded'
          x-order: 2
    TeamMemberList:
      type: object
      description: A normalized paginated response containing team members with related entity data.
      required:
        - total
        - items
        - included
      properties:
        total:
          type: integer
          description: The total number of team members.
          x-order: 1
        items:
          type: array
          description: A page of team member results with ID references.
          items:
            $ref: '#/components/schemas/TeamMemberSearchItem'
          x-order: 2
        included:
          allOf:
            - $ref: '#/components/schemas/TeamMemberSearchIncluded'
          x-order: 3
    TeamMemberRolesUpdate:
      type: object
      required:
        - roleIds
      properties:
        roleIds:
          type: array
          items:
            $ref: '#/components/schemas/ResourceId'
          minItems: 1
          description: Array of team role IDs to assign to the team member. Must contain at least one role ID.
          example:
            - ROLE123
            - ROLE456
    TeamMemberSearchIncluded:
      type: object
      description: Related entities referenced by IDs in the team member results.
      properties:
        members:
          type: array
          description: Array of member entities.
          items:
            $ref: '#/components/schemas/MemberSummary'
          x-order: 1
        users:
          type: array
          description: Array of user entities with emails.
          items:
            $ref: '#/components/schemas/UserExpanded'
          x-order: 2
        roles:
          type: array
          description: Array of organization role entities.
          items:
            $ref: '#/components/schemas/OrganizationRoleExpanded'
          x-order: 3
        teamRoles:
          type: array
          description: Array of team role entities.
          items:
            $ref: '#/components/schemas/TeamRoleExpanded'
          x-order: 4
    TeamMemberSearchItem:
      type: object
      description: A single team member item with entity ID references.
      required:
        - memberId
        - isAutomatic
      properties:
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization member ID.
          x-order: 1
        userId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          nullable: true
          description: The user ID if the member has accepted their invitation.
          x-order: 2
        roleIds:
          type: array
          nullable: true
          description: Organization role IDs assigned to this member.
          items:
            type: string
          x-order: 3
        teamRoleIds:
          type: array
          nullable: true
          description: Team role IDs assigned to this member in this team.
          items:
            type: string
          x-order: 4
        isAutomatic:
          type: boolean
          description: Whether this membership was automatically created because the member holds an org role with all_teams=true.
          x-order: 5
    TeamMembership:
      type: object
      description: A team membership record.
      required:
        - id
        - memberId
        - teamId
        - isAutomatic
        - createdAt
        - updatedAt
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member team ID.
          x-access-type: ReadOnly
          x-order: 1
        memberId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The member ID.
          x-access-type: ReadImmutable
          x-order: 2
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team ID.
          x-access-type: ReadImmutable
          x-order: 3
        isAutomatic:
          type: boolean
          description: Whether this membership was automatically created because the member holds an org role with all_teams=true.
          x-access-type: ReadOnly
          x-order: 4
        createdAt:
          type: string
          format: date-time
          description: The time when the team membership was created.
          x-access-type: ReadOnly
          x-order: 5
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this team membership.
          x-access-type: ReadOnly
          x-order: 6
        updatedAt:
          type: string
          format: date-time
          description: The time when the team membership was last updated.
          x-access-type: ReadOnly
          x-order: 7
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this team membership.
          x-access-type: ReadOnly
          x-order: 8
    TeamRoleExpanded:
      type: object
      description: An expanded team role summary with aggregate data.
      required:
        - role
        - memberCount
        - permissionCount
      properties:
        role:
          allOf:
            - $ref: '#/components/schemas/TeamRoleSummary'
          description: The team role summary.
          x-order: 1
        memberCount:
          type: integer
          description: The total number of team members who have this role.
          x-order: 2
        permissionCount:
          type: integer
          description: The total number of permissions (including expanded bundles) in this role.
          x-order: 3
    TeamRoleIncluded:
      type: object
      description: Related entities referenced by IDs in the role detail.
      required:
        - roles
        - permissions
        - bundles
      properties:
        roles:
          type: array
          description: Array of team role entities with expanded data.
          items:
            $ref: '#/components/schemas/TeamRoleExpanded'
          x-order: 1
        permissions:
          type: array
          description: Array of permission definition entities.
          items:
            $ref: '#/components/schemas/PermissionDefinition'
          x-order: 2
        bundles:
          type: array
          description: Array of permission bundle entities.
          items:
            $ref: '#/components/schemas/PermissionBundleSummary'
          x-order: 3
    TeamRoleItem:
      type: object
      description: Team role detail with entity ID references only.
      required:
        - roleId
        - permissionIds
        - bundleIds
        - bundlePermissions
      properties:
        roleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team role ID.
          x-order: 1
        permissionIds:
          type: array
          description: Direct permission relations assigned to this role (not part of bundles).
          items:
            type: string
          x-order: 2
        bundleIds:
          type: array
          description: Permission bundle IDs assigned to this role.
          items:
            type: string
          x-order: 3
        bundlePermissions:
          type: object
          description: Map of bundle ID to the permission relations within that bundle for this role.
          additionalProperties:
            type: array
            items:
              type: string
          x-order: 4
    TeamRoleList:
      type: object
      description: A list of team roles.
      required:
        - total
        - items
      properties:
        total:
          type: integer
          description: The total number of organization roles found.
          x-order: 1
        items:
          type: array
          description: A list of team roles with aggregate data.
          items:
            $ref: '#/components/schemas/TeamRoleExpanded'
          x-order: 2
    TeamRoleNormalized:
      type: object
      description: Team role detail with normalized entity references.
      required:
        - item
        - included
      properties:
        item:
          allOf:
            - $ref: '#/components/schemas/TeamRoleItem'
          description: Role detail with ID references only.
          x-order: 1
        included:
          allOf:
            - $ref: '#/components/schemas/TeamRoleIncluded'
          description: Full entity data for referenced IDs.
          x-order: 2
    TeamRoleSummary:
      type: object
      description: A summary of a team role.
      required:
        - id
        - organizationId
        - name
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team role ID.
          x-access-type: ReadOnly
          x-order: 1
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name of the team role.
          x-access-type: ReadWrite
          x-order: 3
        description:
          type: string
          minLength: 1
          maxLength: 1023
          description: The description of the role.
          x-access-type: ReadWrite
          x-order: 4
        createdAt:
          type: string
          format: date-time
          description: The time when the team role was created.
          x-access-type: ReadOnly
          x-order: 5
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this team role.
          x-access-type: ReadOnly
          x-order: 6
        updatedAt:
          type: string
          format: date-time
          description: The time when the team role was last updated.
          x-access-type: ReadOnly
          x-order: 7
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this team role.
          x-access-type: ReadOnly
          x-order: 8
    TeamSpec:
      type: object
      description: The specification to create a team.
      required:
        - name
        - defaultRoleId
      x-filter-group: Spec
      properties:
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name of the team.
          x-access-type: ReadWrite
          x-order: 3
        defaultRoleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the default role assigned to new members of this team.
          x-access-type: ReadWrite
          x-order: 8
    TeamSummary:
      type: object
      description: A summary of a team.
      required:
        - id
        - organizationId
        - name
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team ID.
          x-access-type: ReadOnly
          x-order: 1
        organizationId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The organization ID.
          x-access-type: ReadImmutable
          x-order: 2
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name of the team.
          x-access-type: ReadWrite
          x-order: 3
        createdAt:
          type: string
          format: date-time
          description: The time when the team was created.
          x-access-type: ReadOnly
          x-order: 4
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this team.
          x-access-type: ReadOnly
          x-order: 5
        updatedAt:
          type: string
          format: date-time
          description: The time when the team was last updated.
          x-access-type: ReadOnly
          x-order: 6
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this team.
          x-access-type: ReadOnly
          x-order: 7
        defaultRoleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the default role assigned to new members of this team.
          x-access-type: ReadWrite
          x-order: 8
    TeamUpdate:
      type: object
      description: An update to a team.
      x-filter-group: Update
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name of the team.
          x-access-type: ReadWrite
          x-order: 3
        defaultRoleId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the default role assigned to new members of this team.
          x-access-type: ReadWrite
          x-order: 8
    TestConnectionResponse:
      type: object
      description: The result of testing an identity provider connection.
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: Whether the connection test was successful.
        message:
          type: string
          description: A message describing the test result.
        details:
          type: object
          description: Additional details about the test result.
          properties:
            issuer:
              type: string
              description: The discovered issuer URL.
            endpoints:
              type: object
              description: Discovered OIDC endpoints.
              properties:
                authorization:
                  type: string
                token:
                  type: string
                userinfo:
                  type: string
                jwks:
                  type: string
                endSession:
                  type: string
                  description: Front-channel logout endpoint (RP-initiated logout).
            backchannelLogoutSupported:
              type: boolean
              description: Whether the provider supports OIDC Back-Channel Logout.
            backchannelLogoutSessionSupported:
              type: boolean
              description: Whether the provider supports session-specific back-channel logout (sid claim).
            frontchannelLogoutSupported:
              type: boolean
              description: Whether the provider supports OIDC Front-Channel Logout.
            scopesSupported:
              type: array
              items:
                type: string
              description: OAuth scopes supported by the provider.
            claimsSupported:
              type: array
              items:
                type: string
              description: Claims supported by the provider in ID tokens.
    TrustedDeviceList:
      type: object
      description: A list of trusted devices for the current user.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of trusted devices.
          items:
            $ref: '#/components/schemas/TrustedDeviceSummary'
          x-order: 1
    TrustedDeviceSummary:
      type: object
      description: A trusted device summary.
      required:
        - id
        - deviceId
        - expiresAt
        - createdAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The trusted device identifier.
          x-access-type: ReadOnly
          x-order: 1
        deviceId:
          type: string
          description: The device identifier.
          x-access-type: ReadOnly
          x-order: 2
        expiresAt:
          type: string
          format: date-time
          description: When this trusted device record expires.
          x-access-type: ReadOnly
          x-order: 3
        createdAt:
          type: string
          format: date-time
          description: When this device was trusted.
          x-access-type: ReadOnly
          x-order: 4
        remoteIp:
          type: string
          nullable: true
          description: The IP address from which the device was trusted.
          x-access-type: ReadOnly
          x-order: 5
        userAgent:
          type: string
          nullable: true
          description: The user agent string of the trusted device.
          x-access-type: ReadOnly
          x-order: 6
    User:
      type: object
      description: A user.
      required:
        - id
        - email
        - givenName
        - familyName
        - displayName
        - createdAt
        - updatedAt
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The user ID.
          x-access-type: ReadOnly
          x-order: 1
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The email address of the user.
          x-access-type: ReadWrite
          x-order: 2
          type: string
          nullable: true
        givenName:
          type: string
          minLength: 1
          maxLength: 63
          description: The given name of the user.
          x-access-type: ReadWrite
          x-order: 3
        familyName:
          type: string
          minLength: 1
          maxLength: 63
          description: The family name of the user.
          x-access-type: ReadWrite
          x-order: 4
        displayName:
          type: string
          minLength: 1
          maxLength: 127
          description: The display name of the user.
          x-access-type: ReadWrite
          x-order: 5
        createdAt:
          type: string
          format: date-time
          description: The time when the user was created.
          x-access-type: ReadOnly
          x-order: 6
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this user.
          x-access-type: ReadOnly
          x-order: 7
        updatedAt:
          type: string
          format: date-time
          description: The time when the user was last updated.
          x-access-type: ReadOnly
          x-order: 8
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this user.
          x-access-type: ReadOnly
          x-order: 9
    UserAuthExpanded:
      type: object
      description: Auth properties associated with the user.
      required:
        - has2FA
        - hasPassword
        - hasRecovery
      properties:
        has2FA:
          type: boolean
          description: Indicates if the user has two-factor authentication enabled.
          x-order: 1
        hasPassword:
          type: boolean
          description: Indicates if the user has a password set.
          x-order: 2
        hasRecovery:
          type: boolean
          description: Indicates if the user has MFA recovery codes configured.
          x-order: 3
    UserEmailList:
      type: object
      description: A list of user email addresses.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of user email addresses.
          items:
            $ref: '#/components/schemas/UserEmailSummary'
          x-order: 1
        marker:
          type: string
          description: The pagination token to request more items.
          x-order: 2
    UserEmailSummary:
      type: object
      description: A user email address.
      required:
        - userId
        - email
        - verifiedAt
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        userId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The user ID.
          x-access-type: ReadOnly
          x-order: 1
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The email address of the user.
          x-access-type: ReadWrite
          x-order: 2
        verifiedAt:
          type: string
          format: date-time
          nullable: true
          description: The time when the email address was verified.
          x-access-type: ReadOnly
          x-order: 4
        createdAt:
          type: string
          format: date-time
          description: The time when the email address was created.
          x-access-type: ReadOnly
          x-order: 5
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this email address.
          x-access-type: ReadOnly
          x-order: 6
        updatedAt:
          type: string
          format: date-time
          description: The time when the email address was last updated.
          x-access-type: ReadOnly
          x-order: 7
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this email address.
          x-access-type: ReadOnly
          x-order: 8
    UserExpanded:
      type: object
      description: An expanded user with associated relationships.
      required:
        - user
        - auth
      properties:
        user:
          allOf:
            - $ref: '#/components/schemas/User'
          description: The user details.
          x-order: 1
        emails:
          type: array
          nullable: true
          description: All email addresses associated with the user.
          items:
            $ref: '#/components/schemas/UserEmailSummary'
          x-order: 2
        auth:
          allOf:
            - $ref: '#/components/schemas/UserAuthExpanded'
          description: Authentication properties associated with the user.
          x-order: 3
    UserList:
      type: object
      description: A list of users.
      required:
        - items
      properties:
        items:
          type: array
          description: A list of users.
          items:
            $ref: '#/components/schemas/User'
          x-order: 1
        marker:
          type: string
          description: The pagination token to request more items.
          x-order: 2
    UserSignupSpec:
      type: object
      required:
        - email
        - givenName
        - familyName
        - password
      properties:
        email:
          type: string
          format: email
          description: The email address of the user.
        givenName:
          type: string
          description: The given name of the user.
        familyName:
          type: string
          description: The family name of the user.
        password:
          allOf:
            - $ref: '#/components/schemas/Password'
          description: The password for the user.
    UserSpec:
      type: object
      description: The specification to create a user.
      required:
        - email
        - givenName
        - familyName
        - displayName
      x-filter-group: Spec
      properties:
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The email address of the user.
          x-access-type: ReadWrite
          x-order: 2
        givenName:
          type: string
          minLength: 1
          maxLength: 63
          description: The given name of the user.
          x-access-type: ReadWrite
          x-order: 3
        familyName:
          type: string
          minLength: 1
          maxLength: 63
          description: The family name of the user.
          x-access-type: ReadWrite
          x-order: 4
        displayName:
          type: string
          minLength: 1
          maxLength: 127
          description: The display name of the user.
          x-access-type: ReadWrite
          x-order: 5
    UserSummary:
      type: object
      description: A summary of a user.
      required:
        - id
        - givenName
        - familyName
        - displayName
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The user ID.
          x-access-type: ReadOnly
          x-order: 1
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The email address of the user.
          x-access-type: ReadWrite
          x-order: 2
        givenName:
          type: string
          minLength: 1
          maxLength: 63
          description: The given name of the user.
          x-access-type: ReadWrite
          x-order: 3
        familyName:
          type: string
          minLength: 1
          maxLength: 63
          description: The family name of the user.
          x-access-type: ReadWrite
          x-order: 4
        displayName:
          type: string
          minLength: 1
          maxLength: 127
          description: The display name of the user.
          x-access-type: ReadWrite
          x-order: 5
        createdAt:
          type: string
          format: date-time
          description: The time when the user was created.
          x-access-type: ReadOnly
          x-order: 6
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this user.
          x-access-type: ReadOnly
          x-order: 7
        updatedAt:
          type: string
          format: date-time
          description: The time when the user was last updated.
          x-access-type: ReadOnly
          x-order: 8
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this user.
          x-access-type: ReadOnly
          x-order: 9
    UserUpdate:
      type: object
      description: An update to a user.
      x-filter-group: Update
      properties:
        email:
          allOf:
            - $ref: '#/components/schemas/EmailAddress'
          description: The email address of the user.
          x-access-type: ReadWrite
          x-order: 2
        givenName:
          type: string
          minLength: 1
          maxLength: 63
          description: The given name of the user.
          x-access-type: ReadWrite
          x-order: 3
        familyName:
          type: string
          minLength: 1
          maxLength: 63
          description: The family name of the user.
          x-access-type: ReadWrite
          x-order: 4
        displayName:
          type: string
          minLength: 1
          maxLength: 127
          description: The display name of the user.
          x-access-type: ReadWrite
          x-order: 5
    Username:
      type: string
      description: The username of a user.
      minLength: 2
      maxLength: 253
      pattern: ^[a-zA-Z0-9.-]+$
      example: ci-deploy-bot
    VcsProvider:
      type: string
      description: Version control system provider type
      enum:
        - GITHUB
        - GITLAB
        - BITBUCKET_CLOUD
        - BITBUCKET_SERVER
        - AZURE_DEV_OPS_SERVICES
        - AWS_CODE_COMMIT
        - GITHUB_ENTERPRISE
        - GITLAB_ENTERPRISE_EDITION
        - SVN
        - MERCURIAL
        - PERFORCE
        - OTHER
    VcsReference:
      type: object
      description: VCS reference to checkout (branch, tag, revision, commit, etc.)
      required:
        - type
        - value
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/VcsReferenceType'
          description: Type of VCS reference
          x-order: 1
        value:
          type: string
          description: Value of the reference (branch name, tag name, commit hash, revision number, etc.)
          example: main
          x-order: 2
    VcsReferenceType:
      type: string
      description: Type of version control reference
      enum:
        - branch
        - tag
        - commit
        - revision
    WorkloadConfig:
      type: object
      description: A workload config with full detail.
      required:
        - id
        - workloadType
        - clusterId
        - teamId
        - config
        - endpointLimits
        - createdAt
        - createdBy
        - updatedAt
        - updatedBy
      x-filter-group: Full
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The compute config ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the workload config. NULL for anonymous (ephemeral) configs auto-generated from session creation.
          x-access-type: ReadWrite
          x-order: 2
        workloadType:
          allOf:
            - $ref: '#/components/schemas/WorkloadType'
          description: The workload type.
          x-access-type: ReadImmutable
          x-order: 3
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster this workload config targets.
          x-access-type: ReadImmutable
          x-order: 4
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team this workload config belongs to.
          x-access-type: ReadImmutable
          x-order: 5
        config:
          allOf:
            - $ref: '#/components/schemas/WorkloadConfigConfig'
          x-access-type: ReadWrite
          x-order: 6
        endpointLimits:
          allOf:
            - $ref: '#/components/schemas/WorkloadConfigEndpointLimits'
          x-access-type: ReadWrite
          x-order: 7
        createdAt:
          type: string
          format: date-time
          description: The time when the workload config was created.
          x-access-type: ReadOnly
          x-order: 8
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this workload config.
          x-access-type: ReadOnly
          x-order: 9
        updatedAt:
          type: string
          format: date-time
          description: The time when the workload config was last updated.
          x-access-type: ReadOnly
          x-order: 10
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this workload config.
          x-access-type: ReadOnly
          x-order: 11
    WorkloadConfigConfig:
      type: object
      description: Workload-specific configuration. The key corresponds to the workloadType (e.g., "sail"). Exactly one engine key must be present.
      properties:
        sail:
          allOf:
            - $ref: '#/components/schemas/WorkloadConfigSailConfig'
          description: Configuration for the Sail engine.
          x-order: 1
      additionalProperties: false
      minProperties: 1
      maxProperties: 1
    WorkloadConfigEndpointLimits:
      type: object
      description: Per-endpoint session concurrency cap. Keys are endpoint names, values are max concurrent sessions. Absent key defaults to 1.
      properties:
        spark_connect:
          type: integer
          minimum: 1
          description: Max concurrent sessions on the Spark Connect (gRPC) endpoint.
      additionalProperties: false
    WorkloadConfigList:
      type: object
      description: A list of workload configs.
      required:
        - items
      properties:
        items:
          type: array
          description: Workload config summaries.
          items:
            $ref: '#/components/schemas/WorkloadConfigSummary'
          x-order: 1
        marker:
          type: string
          description: The pagination token to request more items.
          x-order: 2
    WorkloadConfigSailConfig:
      type: object
      description: Configuration for the Sail engine.
      required:
        - executionMode
      properties:
        executionMode:
          allOf:
            - $ref: '#/components/schemas/JobConfigLakeSailExecutionMode'
          description: Execution mode for the Sail engine.
          x-order: 1
        compute:
          allOf:
            - $ref: '#/components/schemas/JobConfigCompute'
          description: Compute configuration for the Sail engine. If not specified, the platform default compute configuration is used.
          x-order: 2
        lakesailImageUri:
          type: string
          description: Optional container image URI for the Sail engine. If not specified, the platform default image is used.
          x-order: 3
        libraries:
          type: array
          description: Optional list of libraries to install before execution.
          items:
            $ref: '#/components/schemas/JobConfigLakeSailLibrary'
          x-order: 4
        extraEnv:
          type: object
          description: Additional environment variables to pass to the Sail engine. See LakeSail Configuration for supported keys.
          additionalProperties:
            type: string
          x-order: 5
    WorkloadConfigSpec:
      type: object
      description: The specification to create a workload config.
      required:
        - workloadType
        - clusterId
        - teamId
      x-filter-group: Spec
      properties:
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the workload config. NULL for anonymous (ephemeral) configs auto-generated from session creation.
          x-access-type: ReadWrite
          x-order: 2
        workloadType:
          allOf:
            - $ref: '#/components/schemas/WorkloadType'
          description: The workload type.
          x-access-type: ReadImmutable
          x-order: 3
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster this workload config targets.
          x-access-type: ReadImmutable
          x-order: 4
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team this workload config belongs to.
          x-access-type: ReadImmutable
          x-order: 5
        config:
          allOf:
            - $ref: '#/components/schemas/WorkloadConfigConfig'
          x-access-type: ReadWrite
          x-order: 6
        endpointLimits:
          allOf:
            - $ref: '#/components/schemas/WorkloadConfigEndpointLimits'
          x-access-type: ReadWrite
          x-order: 7
    WorkloadConfigSummary:
      type: object
      description: A summary of a workload config.
      required:
        - id
        - workloadType
        - clusterId
        - teamId
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The compute config ID.
          x-access-type: ReadOnly
          x-order: 1
        name:
          allOf:
            - $ref: '#/components/schemas/ResourceName'
          description: A human-readable name for the workload config. NULL for anonymous (ephemeral) configs auto-generated from session creation.
          x-access-type: ReadWrite
          x-order: 2
        workloadType:
          allOf:
            - $ref: '#/components/schemas/WorkloadType'
          description: The workload type.
          x-access-type: ReadImmutable
          x-order: 3
        clusterId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The cluster this workload config targets.
          x-access-type: ReadImmutable
          x-order: 4
        teamId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The team this workload config belongs to.
          x-access-type: ReadImmutable
          x-order: 5
        config:
          allOf:
            - $ref: '#/components/schemas/WorkloadConfigConfig'
          x-access-type: ReadWrite
          x-order: 6
        endpointLimits:
          allOf:
            - $ref: '#/components/schemas/WorkloadConfigEndpointLimits'
          x-access-type: ReadWrite
          x-order: 7
        createdAt:
          type: string
          format: date-time
          description: The time when the workload config was created.
          x-access-type: ReadOnly
          x-order: 8
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this workload config.
          x-access-type: ReadOnly
          x-order: 9
        updatedAt:
          type: string
          format: date-time
          description: The time when the workload config was last updated.
          x-access-type: ReadOnly
          x-order: 10
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this workload config.
          x-access-type: ReadOnly
          x-order: 11
    WorkloadSummary:
      type: object
      description: A summary of a workload.
      required:
        - id
        - workloadConfigId
        - infraStatus
        - shutdownPolicy
        - createdAt
        - updatedAt
      x-filter-group: Summary
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The workload ID.
          x-access-type: ReadOnly
          x-order: 1
        workloadConfigId:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The workload config this workload was created from.
          x-access-type: ReadOnly
          x-order: 2
        infraStatus:
          allOf:
            - $ref: '#/components/schemas/InfraStatus'
          description: The current infrastructure status.
          x-access-type: ReadOnly
          x-order: 3
        shutdownPolicy:
          allOf:
            - $ref: '#/components/schemas/ShutdownPolicy'
          description: When to tear down this workload.
          x-access-type: ReadOnly
          x-order: 4
        endpoints:
          type: object
          description: Available endpoints on this instance, keyed by service name. Values are ClusterIP:port strings. Set during provisioning.
          additionalProperties:
            type: string
          x-access-type: ReadOnly
          x-order: 5
        provisionedAt:
          type: string
          format: date-time
          description: The time when the workload became provisioned.
          x-access-type: ReadOnly
          x-order: 6
        cleanedAt:
          type: string
          format: date-time
          description: The time when the workload was cleaned up.
          x-access-type: ReadOnly
          x-order: 7
        lastActivityAt:
          type: string
          format: date-time
          description: The time of the last activity across all connected sessions.
          x-access-type: ReadOnly
          x-order: 8
        statusMessage:
          type: string
          nullable: true
          description: Status or error details for the current infrastructure state.
          x-access-type: ReadOnly
          x-order: 9
        createdAt:
          type: string
          format: date-time
          description: The time when the workload was created.
          x-access-type: ReadOnly
          x-order: 10
        createdBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who created this workload.
          x-access-type: ReadOnly
          x-order: 11
        updatedAt:
          type: string
          format: date-time
          description: The time when the workload was last updated.
          x-access-type: ReadOnly
          x-order: 12
        updatedBy:
          allOf:
            - $ref: '#/components/schemas/ResourceId'
          description: The ID of the actor who last updated this workload.
          x-access-type: ReadOnly
          x-order: 13
    WorkloadType:
      type: string
      description: The workload type.
      enum:
        - sail
  responses:
    AcceptInviteResponse:
      description: The invite was accepted successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignupSummary'
    ActivateJobVersionResponse:
      description: The specified version was activated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobSummary'
    AddMyEmailResponse:
      description: The email address was added and a verification email has been sent.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserEmailSummary'
    AddTeamMemberResponse:
      description: The member was added to the team successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamMembership'
    AddTeamsToCatalogResponse:
      description: The teams were added to the catalog successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogTeamList'
    AddTeamsToJobResponse:
      description: The teams were added to the job successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobTeamList'
    AddTeamsToQueryResponse:
      description: The teams were added to the query successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryTeamList'
    AutoSetupIdentityProviderResponse:
      description: Identity provider was successfully auto-configured.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderSummary'
    CreateCatalogResponse:
      description: The catalog was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogSummary'
    CreateExternalClusterResponse:
      description: External cluster created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterSummary'
    CreateExternalConnectionResponse:
      description: External connection created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnectionSummary'
    CreateExternalNetworkResponse:
      description: Managed external network created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalNetworkSummary'
    CreateIdentityProviderResponse:
      description: The identity provider was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProvider'
    CreateInviteResponse:
      description: The invite was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InviteSummary'
    CreateJobDraftResponse:
      description: A new draft version was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobVersionSummary'
    CreateJobResponse:
      description: The LakeSail job was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobSummary'
    CreateJobRunResponse:
      description: The LakeSail job run was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobRunSummary'
    CreateJobVersionResponse:
      description: The job version was created and published successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobVersionSummary'
    CreateNotificationChannelResponse:
      description: The notification channel was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationChannel'
    CreateNotificationRuleResponse:
      description: The notification rule was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationRule'
    CreateQueryResponse:
      description: The query was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QuerySummary'
    CreateSessionResponse:
      description: The session was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Session'
    CreateTeamResponse:
      description: Successfully created team.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamExpanded'
    CreateUserResponse:
      description: The user was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
    CreateWorkloadConfigResponse:
      description: The workload config was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WorkloadConfig'
    DescribeCatalogResponse:
      description: The catalog details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Catalog'
    DescribeCurrentIdentityResponse:
      description: The information about the current identity is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CurrentIdentity'
    DescribeExternalClusterByConnectionResponse:
      description: External cluster details with connection information.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterNormalized'
    DescribeExternalClusterResponse:
      description: External cluster details with connection information.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterNormalized'
    DescribeExternalConnectionResponse:
      description: External connection details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnection'
    DescribeExternalNetworkByConnectionResponse:
      description: Managed external network details with connection information.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalNetworkNormalized'
    DescribeIdentityProviderResponse:
      description: The information about the identity provider is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProvider'
    DescribeInviteResponse:
      description: The invite details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InviteSummary'
    DescribeJobDraftResponse:
      description: The draft version details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobVersionSummary'
    DescribeJobResponse:
      description: Job details with normalized entity references
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobNormalized'
    DescribeJobRunResponse:
      description: The LakeSail job run is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobRun'
    DescribeJobVersionResponse:
      description: Job details for the specified version, with normalized entity references
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobNormalized'
    DescribeMemberResponse:
      description: Organization user details retrieved successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MemberNormalized'
    DescribeMyClusterResponse:
      description: The cluster accessible by the current user is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClusterNormalized'
    DescribeNotificationChannelResponse:
      description: The notification channel details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationChannel'
    DescribeNotificationRuleResponse:
      description: The notification rule details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationRule'
    DescribePolicyResponse:
      description: The information about the resource policy is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Policy'
    DescribeQueryResponse:
      description: Query details with normalized entity references.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryNormalized'
    DescribeSessionResponse:
      description: The session was retrieved successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Session'
    DescribeTeamResponse:
      description: The team response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamExpanded'
    DescribeUserResponse:
      description: The information about the user is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
    DescribeWorkloadConfigResponse:
      description: The workload config was retrieved successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WorkloadConfig'
    DestroyExternalClusterByConnectionResponse:
      description: Destruction operation initiated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationSummary'
    DestroyExternalNetworkByConnectionResponse:
      description: Destruction operation initiated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationSummary'
    EmptyResponse:
      description: The requested operation was done successfully.
    ErrorBadRequestResponse:
      description: |
        The requested operation cannot be performed because the request is malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: The request body is invalid.
    ErrorConflictResponse:
      description: |
        The requested operation cannot be performed because of a conflict with the current state of the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: A resource with this name already exists.
    ErrorForbiddenResponse:
      description: |
        The identity is not allowed to perform the requested operation
        for the resource involved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: You do not have permission to perform this action.
    ErrorNotFoundResponse:
      description: |
        The resource or dependent resources involved in the requested operation
        do not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: The requested resource was not found.
    ErrorResponse:
      description: The requested operation failed with an error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ErrorUnauthorizedResponse:
      description: |
        The requested operation cannot be performed
        because the request lacks valid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Authentication credentials are missing or invalid.
    ErrorUnprocessableEntityResponse:
      description: |
        The requested operation cannot be performed because the request, while
        well-formed, contains semantically invalid data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: The request could not be processed.
    GetExternalClusterHealthByConnectionResponse:
      description: External cluster health status
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterHealth'
    GetExternalClusterKubeconfigByConnectionResponse:
      description: Kubeconfig for the External cluster.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterKubeconfig'
    GetExternalClusterMetricsByConnectionResponse:
      description: External cluster metrics.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterMetrics'
    GetExternalConnectionTemplateDownloadResponse:
      description: CloudFormation template with defaults injected.
      content:
        text/yaml:
          schema:
            type: string
            format: binary
    GetExternalConnectionTemplateResponse:
      description: CloudFormation template information.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnectionTemplate'
    GetOperationResponse:
      description: Operation status and results.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationSummary'
    IssueSessionTokenResponse:
      description: A bearer token for gRPC proxy access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionToken'
    ListCatalogQueriesResponse:
      description: A list of queries using this catalog is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryList'
    ListCatalogTeamsResponse:
      description: A list of catalog teams is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogTeamList'
    ListClusterJobsResponse:
      description: The list of LakeSail jobs configured to run on the cluster is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobList'
    ListCurrentIdentityEmailsResponse:
      description: The email addresses of the current identity are returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserEmailList'
    ListCurrentIdentityTeamsResponse:
      description: The teams of the current identity are returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CurrentIdentityTeamList'
    ListExternalClustersResponse:
      description: List of External clusters with connection information.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterList'
    ListExternalConnectionsResponse:
      description: List of External connections.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnectionList'
    ListExternalInstanceTypesResponse:
      description: List of available instance types for the cloud provider.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalInstanceTypeList'
    ListExternalNetworksForConnectionResponse:
      description: List of available networks
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalNetworkList'
    ListExternalNetworksResponse:
      description: List of managed external networks
      content:
        application/json:
          schema:
            type: object
            required:
              - items
              - included
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/ExternalNetworkSummary'
              included:
                allOf:
                  - $ref: '#/components/schemas/ExternalNetworkIncluded'
              marker:
                type: string
                description: Pagination token for the next page
                nullable: true
    ListExternalRegionsResponse:
      description: List of available cloud provider regions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalRegionList'
    ListIdentityProviderTypesResponse:
      description: A list of identity provider types is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderTypeList'
    ListIdentityProvidersResponse:
      description: A list of identity providers is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderList'
    ListJobRunsResponse:
      description: The list of LakeSail job runs is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobRunList'
    ListJobTeamsResponse:
      description: The list of teams associated with the job is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamList'
    ListJobVersionsResponse:
      description: The list of LakeSail job versions is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobVersionList'
    ListMyCatalogsResponse:
      description: A list of catalogs the current user can access is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogList'
    ListMyClustersResponse:
      description: A list of clusters the current user can access is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClusterExpandedList'
    ListMyJobRunsResponse:
      description: The list of job runs accessible by the current user is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobRunList'
    ListMyJobsResponse:
      description: A list of jobs the current user can access is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobList'
    ListMyLoginsResponse:
      description: The logins of the current user are returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LoginList'
    ListMyQueriesResponse:
      description: A list of queries the current user can access is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryList'
    ListMyTrustedDevicesResponse:
      description: The trusted devices of the current user are returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TrustedDeviceList'
    ListNotificationChannelsResponse:
      description: A list of notification channels.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationChannelList'
    ListNotificationEventTypesResponse:
      description: A list of available notification event types.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationEventTypeList'
    ListNotificationRulesResponse:
      description: A list of notification rules.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationRuleList'
    ListNotificationsResponse:
      description: A list of notification delivery log entries.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationList'
    ListOrgCatalogsResponse:
      description: A list of catalogs is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogList'
    ListOrgJobsResponse:
      description: The list of LakeSail jobs is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobList'
    ListOrgQueriesResponse:
      description: A list of queries is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryList'
    ListOrgWorkloadConfigsResponse:
      description: The list of workload configs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WorkloadConfigList'
    ListOrganizationRolesResponse:
      description: A list of organization roles is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationRoleList'
    ListPermissionsResponse:
      description: List of permission definitions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PermissionDefinitionList'
    ListPoliciesResponse:
      description: A list of resource policies is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyList'
    ListQueryTeamsResponse:
      description: The list of teams associated with the query is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamList'
    ListSessionsResponse:
      description: The list of sessions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionList'
    ListTeamCatalogsResponse:
      description: A list of team catalogs is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogList'
    ListTeamJobsResponse:
      description: The list of LakeSail jobs accessible to the team is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobList'
    ListTeamMembersResponse:
      description: A list of team members is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamMemberList'
    ListTeamQueriesResponse:
      description: A list of queries accessible to the team is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryList'
    ListTeamRolesResponse:
      description: A list of team roles is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamRoleList'
    ListTeamsResponse:
      description: A list of teams is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamList'
    ListUsersResponse:
      description: A list of users is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserList'
    ProvisionExternalClusterByConnectionResponse:
      description: Provisioning operation initiated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationSummary'
    ProvisionExternalNetworkByConnectionResponse:
      description: Provisioning operation initiated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationSummary'
    PublishJobDraftResponse:
      description: The draft version was published successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobSummary'
    PutExistingPolicyResponse:
      description: The existing resource policy was modified successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Policy'
    PutNewPolicyResponse:
      description: The resource policy was created successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Policy'
    RelaunchSessionResponse:
      description: The session was relaunched successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Session'
    ReleaseJobRunResponse:
      description: The job run has been released and is now in `ready` status.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobRunSummary'
    ResetPasswordResponse:
      description: The password was reset successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResetPassword'
    RetryJobRunResponse:
      description: The job run has been reset. Its status is `ready` (eligible for execution) or `pending` (held until released) depending on the `hold` flag in the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobRunSummary'
    RotateSecretResponse:
      description: The client secret was rotated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderSummary'
    SearchMembersResponse:
      description: A paginated list of organization users with details is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MemberSearch'
    SyncExternalConnectionTemplateResponse:
      description: Template sync operation initiated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationSummary'
    TestConnectionResponse:
      description: The connection test result.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TestConnectionResponse'
    UpdateCatalogResponse:
      description: The catalog was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogSummary'
    UpdateExternalClusterByConnectionResponse:
      description: External cluster upgrade started
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterSummary'
    UpdateExternalConnectionResponse:
      description: Updated external connection.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnectionSummary'
    UpdateExternalNetworkByConnectionResponse:
      description: Updated external network.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalNetworkSummary'
    UpdateIdentityProviderResponse:
      description: The identity provider was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderSummary'
    UpdateJobDraftResponse:
      description: The draft version was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobVersionSummary'
    UpdateJobResponse:
      description: The LakeSail job was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobSummary'
    UpdateMemberResponse:
      description: The updated organization user.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Member'
    UpdateMyUserResponse:
      description: The user profile was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CurrentIdentity'
    UpdateNotificationChannelResponse:
      description: The notification channel was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationChannel'
    UpdateNotificationRuleResponse:
      description: The notification rule was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationRule'
    UpdateQueryResponse:
      description: The query was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QuerySummary'
    UpdateTeamResponse:
      description: Successfully updated team.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamExpanded'
    UpdateUserResponse:
      description: The user was updated successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
    VerifyExternalConnectionResponse:
      description: External connection verification result.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnectionSummary'
  parameters:
    CatalogId:
      name: catalog
      in: path
      description: A catalog ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: Catalogs
    CatalogSortBy:
      name: sortBy
      in: query
      description: The field to sort by.
      required: false
      schema:
        type: string
        enum:
          - name
          - updatedAt
        default: name
    ClusterId:
      name: cluster
      in: path
      description: A Kubernetes cluster ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
    ClusterSortBy:
      name: sortBy
      in: query
      description: The field to sort by.
      required: false
      schema:
        type: string
        enum:
          - name
        default: name
    ExternalClusterId:
      name: cluster
      in: path
      required: true
      description: The unique identifier of an external cluster.
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: ExternalClusters
    ExternalConnectionId:
      name: connection
      in: path
      required: true
      description: The unique identifier of an external connection.
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: ExternalConnections
    ExternalNetworkId:
      name: network
      in: path
      required: true
      description: The unique identifier of a managed external network.
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: ExternalNetworks
    FilterByChannelId:
      name: channelId
      in: query
      description: Filter by channel ID.
      required: false
      schema:
        $ref: '#/components/schemas/ResourceId'
    FilterByMemberId:
      name: memberId
      in: query
      description: Filter by member ID.
      required: false
      schema:
        $ref: '#/components/schemas/ResourceId'
    FilterByResourceType:
      name: resourceType
      in: query
      description: Filter rules by resource type.
      required: false
      schema:
        type: string
    FilterByRuleId:
      name: ruleId
      in: query
      description: Filter by rule ID.
      required: false
      schema:
        $ref: '#/components/schemas/ResourceId'
    FilterByScopeType:
      name: scopeType
      in: query
      description: Filter rules by scope type.
      required: false
      schema:
        $ref: '#/components/schemas/NotificationRuleScopeType'
    FilterBySessionEndpoint:
      name: endpoint_type
      in: query
      description: Filter sessions by endpoint type.
      required: false
      schema:
        $ref: '#/components/schemas/SessionEndpoint'
    FilterBySessionStatus:
      name: status
      in: query
      description: Filter sessions by status.
      required: false
      schema:
        $ref: '#/components/schemas/SessionStatus'
    FilterBySessionTeamId:
      name: teamId
      in: query
      description: Filter sessions by team.
      required: false
      schema:
        $ref: '#/components/schemas/ResourceId'
    FilterByStatus:
      name: status
      in: query
      description: Filter by delivery status.
      required: false
      schema:
        $ref: '#/components/schemas/NotificationStatus'
    FilterByTeamId:
      name: teamId
      in: query
      description: Filter by team ID.
      required: false
      schema:
        $ref: '#/components/schemas/ResourceId'
    FilterByWorkloadConfigTeamId:
      name: teamId
      in: query
      description: Filter workload configs by team.
      required: false
      schema:
        $ref: '#/components/schemas/ResourceId'
    IdentityProviderId:
      name: idp
      in: path
      description: An identity provider ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: IdentityProviders
    InvitationToken:
      name: token
      in: path
      description: An invitation token.
      required: true
      schema:
        $ref: '#/components/schemas/InvitationToken'
      x-entity: OrganizationUserInvites
    JobId:
      name: job
      in: path
      description: A LakeSail job ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: Jobs
    JobRunId:
      name: jobRun
      in: path
      description: A LakeSail job run ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
    JobSortBy:
      name: sortBy
      in: query
      description: The field to sort by.
      required: false
      schema:
        type: string
        enum:
          - jobKey
          - createdAt
        default: createdAt
    JobVersionNumber:
      name: jobVersionNumber
      in: path
      description: A LakeSail job version.
      required: true
      schema:
        type: integer
        format: int32
        minimum: 1
      x-entity: JobVersions
    Limit:
      name: limit
      in: query
      description: The maximum number of items to list.
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 100
        default: 100
    LoginId:
      name: loginId
      in: path
      required: true
      description: The login ID.
      schema:
        $ref: '#/components/schemas/ResourceId'
    Marker:
      name: marker
      in: query
      description: The pagination token returned from the previous list operation.
      schema:
        type: string
    MemberFilter:
      name: filter
      in: query
      description: Filter criteria for members
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/MemberFilter'
    MemberId:
      name: member
      in: path
      description: The organization user ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
    NotificationChannelId:
      name: channel
      in: path
      description: A notification channel ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: NotificationChannels
    NotificationRuleId:
      name: rule
      in: path
      description: A notification rule ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: NotificationRules
    OperationId:
      name: operationId
      in: path
      required: true
      description: The operation ID to retrieve.
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: Operations
    OrgRoleSortBy:
      name: sortBy
      in: query
      description: The field to sort by.
      required: false
      schema:
        type: string
        enum:
          - name
        default: name
    OrganizationRoleId:
      name: role
      in: path
      description: The organization role ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
    Page:
      name: page
      in: query
      description: The page number to retrieve (1-indexed). Used with limit to support offset-based pagination.
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 1
    Principal:
      name: principal
      in: path
      description: A principal that is granted permissions to access resources.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceDescriptor'
    QueryId:
      name: query
      in: path
      description: A query ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: Queries
    QuerySortBy:
      name: sortBy
      in: query
      description: The field to sort by.
      required: false
      schema:
        type: string
        enum:
          - name
          - updatedAt
        default: updatedAt
    Search:
      name: search
      in: query
      description: Search term to filter results. Searches across relevant text fields like names and descriptions.
      required: false
      schema:
        type: string
        default: ''
    SessionId:
      name: session
      in: path
      description: A session ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: Sessions
    SortBy:
      name: sortBy
      in: query
      description: The field to sort by.
      schema:
        type: string
        enum:
          - name
          - email
        default: name
    SortDirection:
      name: sortDirection
      in: query
      description: The direction to sort (ascending or descending).
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc
    TeamId:
      name: team
      in: path
      required: true
      description: The team ID.
      schema:
        $ref: '#/components/schemas/ResourceId'
    TeamRoleId:
      name: role
      in: path
      required: true
      schema:
        type: string
      description: The ID of the team role.
    TeamRoleSortBy:
      name: sortBy
      in: query
      description: The field to sort by.
      required: false
      schema:
        type: string
        enum:
          - name
        default: name
    TrustedDeviceId:
      name: trustedDeviceId
      in: path
      required: true
      description: The trusted device ID.
      schema:
        $ref: '#/components/schemas/ResourceId'
    UserId:
      name: user
      in: path
      description: A user ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: Users
    WorkloadConfigId:
      name: workloadConfig
      in: path
      description: A workload config ID.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceId'
      x-entity: WorkloadConfigs
  requestBodies:
    AcceptInviteRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AcceptInvite'
    ActivateJobVersionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActivateJobVersionSpec'
    AddMyEmailRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddMyEmailSpec'
    AddTeamMemberRequest:
      required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddTeamMember'
    AddTeamsToCatalogRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddTeamsToCatalog'
    AddTeamsToJobRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - teamIds
            properties:
              teamIds:
                type: array
                description: The team IDs to add to the job.
                minItems: 1
                items:
                  $ref: '#/components/schemas/ResourceId'
    AddTeamsToQueryRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - teamIds
            properties:
              teamIds:
                type: array
                description: The team IDs to add to the query.
                minItems: 1
                items:
                  $ref: '#/components/schemas/ResourceId'
    AutoSetupIdentityProviderRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AutoSetupIdentityProviderSpec'
    ChangePasswordRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ChangePasswordSpec'
    CreateCatalogRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogSpec'
    CreateExternalClusterRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterSpec'
    CreateExternalConnectionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnectionSpec'
    CreateExternalNetworkRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalNetworkSpec'
    CreateIdentityProviderRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderSpec'
    CreateInviteRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InviteSpec'
    CreateJobDraftRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobDraftSpec'
    CreateJobRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobSpec'
    CreateJobRunRequest:
      required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobRunSpec'
    CreateJobVersionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobVersionSpec'
    CreateNotificationChannelRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationChannelSpec'
    CreateNotificationRuleRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationRuleSpec'
    CreateQueryRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QuerySpec'
    CreateSessionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionSpec'
    CreateTeamRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamSpec'
    CreateUserRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserSpec'
    CreateWorkloadConfigRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WorkloadConfigSpec'
    IssueSessionTokenRequest:
      required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IssueSessionTokenRequestSpec'
    PutPolicyRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicySpec'
    RetryJobRunRequest:
      required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RetryJobRunSpec'
    RotateSecretRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RotateSecretSpec'
    UpdateCatalogRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogUpdate'
    UpdateExternalClusterByConnectionRequest:
      description: Upgrade External cluster request
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalClusterUpdate'
    UpdateExternalConnectionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnectionUpdate'
    UpdateExternalNetworkByConnectionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalNetworkUpdate'
    UpdateIdentityProviderRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderUpdate'
    UpdateJobDraftRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobDraftSpec'
    UpdateJobRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobUpdate'
    UpdateMemberRequest:
      description: The update specification for an organization user.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MemberUpdate'
    UpdateMemberRolesRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MemberRolesUpdate'
    UpdateMyUserRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MyUserUpdate'
    UpdateNotificationChannelRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationChannelUpdate'
    UpdateNotificationRuleRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationRuleUpdate'
    UpdateQueryRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryUpdate'
    UpdateTeamMemberRolesRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamMemberRolesUpdate'
    UpdateTeamRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamUpdate'
    UpdateUserRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserUpdate'
    VerifyExternalConnectionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalConnectionVerifySpec'
x-tagGroups:
  - name: API Guide
    tags:
      - pagination
      - response-format
      - errors
      - long-running-operations
  - name: Authentication & Identity
    tags:
      - authentication
      - mfa
      - identity-providers
      - users
  - name: Organization & Access
    tags:
      - organizations
      - teams
      - roles
      - invitations
      - members
      - service-accounts
      - authorization-policies
  - name: Infrastructure
    tags:
      - connections
      - networks
      - clusters
  - name: Workloads
    tags:
      - catalogs
      - queries
      - jobs
      - job-runs
      - sessions
  - name: System
    tags:
      - notifications
      - marketplace
      - operations
      - webhook
      - system-admin
