openapi: 3.0.3
info:
  title: Api Gateway
  description: Firefly Platform API Gateway
  version: 1.0.166
servers:
  - url: https://api.firefly.ai/v2
    description: Firefly API Server
tags:
  - name: Workspaces
    x-displayName: Workspaces
    description: Endpoints for managing CI workspaces and their runs
  - name: Guardrails
    x-displayName: Guardrails
    description: Endpoints for managing guardrail rules and notifications
  - name: Workspace State
    x-displayName: Workspace State
    description: >-
      Endpoints for managing workspace state versions and state-related
      operations.
  - name: Authentication
    x-displayName: Authentication
  - name: VCS
    x-displayName: VCS
    description: Endpoints for managing VCS tokens and integrations
  - name: VCS Events
    x-displayName: VCS Events
    description: Endpoints for managing VCS events
  - name: Projects
    x-displayName: Projects
    description: Endpoints for managing projects
  - name: projectVariable_other
    x-displayName: other
  - name: workspaceVariable_other
    x-displayName: other
  - name: Variable Sets
    x-displayName: Variable Sets
  - name: Variable Set Operations
    x-displayName: Variable Set Operations
  - name: Runners Workspaces
    x-displayName: Runners Workspaces
    description: Endpoints for managing Runners workspaces and infrastructure operations
  - name: Self-Hosted Runners
    x-displayName: Self-Hosted Runners
    description: Endpoints for managing self-hosted runner pools
  - name: self-hosted_other
    x-displayName: other
  - name: OIDC Discovery
    x-displayName: OIDC Discovery
    description: Endpoints for OpenID Connect Discovery
  - name: openId-connect_other
    x-displayName: other
  - name: Governance
    x-displayName: Governance
  - name: Codification
    x-displayName: Codification
  - name: Integrations
    x-displayName: Integrations
  - name: Config
    x-displayName: Config
  - name: Infrastructure
    x-displayName: Infrastructure
  - name: User Service
    x-displayName: User Service
  - name: Audit Log
    x-displayName: Audit Log
  - name: Backup and DR
    x-displayName: Backup and DR
  - name: api_other
    x-displayName: other
  - name: Event Center
    x-displayName: Event Center
  - name: Terraform Remote Backend
    x-displayName: Terraform Remote Backend
    description: >-
      Endpoints for Terraform remote backend operations (state management,
      locking, workspace operations)
  - name: Relationships
    x-displayName: Relationships
  - name: IaC Stacks
    x-displayName: IaC Stacks
  - name: Terralist
    x-displayName: Terralist
paths:
  /workspaces/search:
    servers: []
    post:
      summary: List Workspaces
      description: >-
        Lists all Workspaces with Filtering and Sorting Options. Supports VCS
        Providers Integration.
      operationId: list-workspaces
      tags:
        - Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListWorkspacesRequest'
      responses:
        '200':
          description: List of Workspaces Retrieved Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkspacesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}:
    servers: []
    parameters:
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
    delete:
      summary: Delete a workspace
      description: Deletes a specific workspace and its associated data
      operationId: delete-workspace
      tags:
        - Workspaces
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Workspace deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteWorkspaceResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}/labels:
    servers: []
    parameters:
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
    put:
      summary: Update Workspace Labels
      description: Updates Labels for a specific Workspace
      operationId: update-workspace-labels
      tags:
        - Workspaces
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceLabelsRequest'
      responses:
        '200':
          description: Workspace Labels Updated Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateWorkspaceLabelsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}/runs/search:
    servers: []
    parameters:
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
    post:
      summary: List Workspace Runs
      description: Lists all Runs for a specific Workspace
      operationId: list-workspace-runs
      tags:
        - Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListWorkspaceRunsRequest'
      responses:
        '200':
          description: List of Workspace Runs Retrieved Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkspaceRunsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}/runs/{runId}/resources/search:
    servers: []
    parameters:
      - name: runId
        in: path
        required: true
        description: Unique identifier of the Run (use runId from list runs response)
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 60a097c0-d44c-4dea-af1b-1abdc5f2eea7
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the Workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
    post:
      summary: List Run Resources
      description: Lists Resources Affected by a Run
      operationId: list-run-resources
      tags:
        - Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRunResourcesRequest'
      responses:
        '200':
          description: Run resources retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRunResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}/runs/{runId}/changed-files-code/search:
    servers: []
    parameters:
      - name: runId
        in: path
        required: true
        description: Unique identifier of the run (use runId from list runs response)
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 60a097c0-d44c-4dea-af1b-1abdc5f2eea7
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the Workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
    post:
      summary: List run changed code
      description: Lists code changes grouped by folders with file metadata
      operationId: list-run-changed-code
      tags:
        - Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRunChangedCodeRequest'
      responses:
        '200':
          description: Run changed code retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRunChangedCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}/runs/{runId}/tasks/environments:
    servers: []
    parameters:
      - name: runId
        in: path
        required: true
        description: Unique identifier of the Run
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: e99a01bc-b2fe-4629-ac42-2277be721470
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the Workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
    get:
      summary: List Workspace Tasks Environments
      description: Lists all environments for tasks in a specific workspace run
      operationId: list-workspace-tasks-environments
      tags:
        - Workspaces
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Workspace tasks environments retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkspaceTasksEnvironmentsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}/runs/{runId}/tasks/environment/{environmentName}:
    servers: []
    parameters:
      - name: runId
        in: path
        required: true
        description: Unique identifier of the Run
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: e99a01bc-b2fe-4629-ac42-2277be721470
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the Workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
      - name: environmentName
        in: path
        required: true
        description: Name of the environment
        schema:
          type: string
          example: production
    get:
      summary: Get Workspace Tasks for Environment
      description: Gets all tasks for a specific environment in a workspace run
      operationId: get-workspace-tasks-for-environment
      tags:
        - Workspaces
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Workspace tasks for environment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWorkspaceTasksForEnvironmentResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /guardrails/search:
    servers: []
    post:
      summary: List Guardrail Rules
      description: Returns a list of guardrails rules based on filter criteria
      operationId: list-guardrails
      security:
        - JWTAuth: []
      tags:
        - Guardrails
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListGuardrailsRequest'
      responses:
        '200':
          description: List of guardrail rules retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GuardrailRule'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /guardrails:
    servers: []
    post:
      summary: Create a new Guardrail Rule
      description: Creates a new guardrail rule with optional notification setup
      operationId: create-guardrail-rule
      security:
        - JWTAuth: []
      tags:
        - Guardrails
      requestBody:
        required: true
        description: Guardrail Rule Configuration and Notification Settings
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGuardrailRequest'
      responses:
        '200':
          description: Guardrail Rule Created Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGuardrailResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /guardrails/{ruleId}:
    servers: []
    parameters:
      - name: ruleId
        in: path
        required: true
        description: Unique identifier of the Guardrail Rule
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          example: 684aac91c3f9b3880d3ece51
    patch:
      summary: Update a Guardrail Rule
      description: Updates an existing Guardrail Rule and its Notifications
      operationId: update-guardrail-rule
      security:
        - JWTAuth: []
      tags:
        - Guardrails
      requestBody:
        required: true
        description: Updated Guardrail Rule Configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGuardrailRequest'
      responses:
        '200':
          description: Guardrail Rule Updated Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateGuardrailResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete a Guardrail Rule
      description: Deletes a Guardrail Rule and its Associated Notification
      operationId: delete-guardrail-rule
      security:
        - JWTAuth: []
      tags:
        - Guardrails
      responses:
        '200':
          description: Guardrail Rule Deleted Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteGuardrailResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}/state-versions:
    servers: []
    parameters:
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
    get:
      summary: List state versions
      description: Retrieves a list of state versions for a workspace
      operationId: list-state-versions
      tags:
        - Workspace State
      security:
        - JWTAuth: []
      responses:
        '200':
          description: List of state versions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StateVersion'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /workspaces/{workspaceId}/state-versions/{stateVersionId}/actions/restore:
    servers: []
    parameters:
      - name: workspaceId
        in: path
        required: true
        description: Unique identifier of the workspace
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8
      - name: stateVersionId
        in: path
        required: true
        description: Unique identifier of the state version
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
    post:
      summary: Restore state version
      description: Restores a specific state version as the current state for the workspace
      operationId: restore-state-version
      tags:
        - Workspace State
      security:
        - JWTAuth: []
      responses:
        '200':
          description: State version restored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateVersion'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /login:
    servers: []
    post:
      tags:
        - Authentication
      summary: Login with access key
      description: Authenticate user using access key and secret key
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accessKey
                - secretKey
              properties:
                accessKey:
                  type: string
                  description: User's access key
                secretKey:
                  type: string
                  description: User's secret key
                duration:
                  type: string
                  description: >
                    Custom token validity duration. Defaults to 24h if not
                    provided.

                    Format: <number><unit> where unit is h (hours), d (days), w
                    (weeks), m (months), y (years).

                    Maximum allowed duration is 1 year. Examples: 1h, 12h, 7d,
                    2w, 6m, 1y.
                  example: 24h
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                    description: JWT access token
                  expiresAt:
                    type: integer
                    description: Token expiration time in seconds
                  tokenType:
                    type: string
                    description: Type of token (e.g., "Bearer")
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /vcs/token:
    servers: []
    get:
      summary: Get VCS Token
      description: Retrieves a VCS token for the specified Account Id and VCS Id
      operationId: get-vcs-token
      security:
        - JWTAuth: []
      tags:
        - VCS
      parameters:
        - name: accountId
          in: query
          required: true
          description: Unique identifier of the Account
          schema:
            type: string
            example: 66169dfaf49923c0aab04510
        - name: vcsId
          in: query
          required: true
          description: Unique identifier of the VCS
          schema:
            type: string
            example: 36169d52f49f2fc01ab04510
      responses:
        '200':
          description: VCS token retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: The VCS token
                required:
                  - token
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/integrations/global/vcs:
    servers: []
    get:
      summary: Get all VCS integrations
      description: >-
        Retrieves all VCS integrations grouped by type (github, gitlab,
        bitbucket, etc.)
      operationId: get-all-vcs
      tags:
        - VCS
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successfully retrieved VCS integrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllVcsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/vcs/{type}/{id}/repos:
    servers: []
    get:
      summary: Get repositories for a VCS integration
      description: Retrieves repositories from a specific VCS integration
      operationId: get-vcs-repos
      tags:
        - VCS
      security:
        - JWTAuth: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - github
              - gitlab
              - bitbucket
              - codecommit
              - azuredevops
          description: The VCS provider type
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The VCS integration ID
        - name: public
          in: query
          required: false
          schema:
            type: string
          description: Filter for public/private repos
        - name: repoName
          in: query
          required: false
          schema:
            type: string
          description: Search term to filter repositories by name
        - name: size
          in: query
          required: false
          schema:
            type: integer
            default: 200
          description: Maximum number of repositories to return
      responses:
        '200':
          description: Successfully retrieved repositories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Repository'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/vcs/{type}/branch:
    servers: []
    post:
      summary: Get branches for a repository
      description: Retrieves branches for a specific repository in a VCS integration
      operationId: get-vcs-branches
      tags:
        - VCS
      security:
        - JWTAuth: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - github
              - gitlab
              - bitbucket
              - codecommit
              - azuredevops
          description: The VCS provider type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetBranchesRequest'
      responses:
        '200':
          description: Successfully retrieved branches
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Branch'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/vcs/{type}/{id}/directory-tree:
    servers: []
    get:
      summary: Get directory tree for a repository
      description: >-
        Retrieves the directory tree structure for a specific repository and
        branch
      operationId: get-vcs-directory-tree
      tags:
        - VCS
      security:
        - JWTAuth: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - github
              - gitlab
              - bitbucket
              - codecommit
              - azuredevops
              - bitbucketdc
          description: The VCS provider type
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The VCS integration ID
        - name: repo
          in: query
          required: true
          schema:
            type: string
          description: Full repository name (org/repo)
        - name: branch
          in: query
          required: true
          schema:
            type: string
          description: Branch name to get directory tree from
        - name: includeFiles
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Whether to include files in the tree or only directories
      responses:
        '200':
          description: Successfully retrieved directory tree
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryNode'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/vcs/clone-url:
    servers: []
    post:
      summary: Get authenticated clone URL for a repository
      description: >
        Generates an authenticated git clone URL with embedded credentials for
        the specified repository.

        Supports all VCS providers: GitHub, GitLab, Bitbucket, Bitbucket Data
        Center, Azure DevOps, and AWS CodeCommit.
      operationId: get-clone-url
      tags:
        - VCS
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloneUrlRequest'
      responses:
        '200':
          description: Successfully generated clone URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloneUrlResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/vcs/modules/import:
    servers: []
    post:
      summary: Import Terraform module from GitHub repository
      description: >
        Imports a module to the private registry using backend-managed VCS
        credential resolution.

        The frontend sends metadata only and the backend builds the
        authenticated download URL.
      operationId: import-vcs-module
      tags:
        - VCS
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportVcsModuleRequest'
      responses:
        '200':
          description: Module imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportVcsModuleResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportVcsModuleErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Integration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportVcsModuleErrorResponse'
        '422':
          description: Registry could not download module from repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportVcsModuleErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportVcsModuleErrorResponse'
        '502':
          description: Upstream VCS or registry service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportVcsModuleErrorResponse'
  /vcs-events/{vcs_type}:
    servers: []
    post:
      summary: Create a VCS Event
      description: Creates a new VCS event
      operationId: create-vcs-event
      tags:
        - VCS Events
      parameters:
        - name: vcs_type
          in: path
          required: true
          description: VCS provider type
          schema:
            type: string
            enum:
              - github
              - gitlab
              - bitbucket
              - azuredevops
      responses:
        '201':
          description: VCS event received successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/projects:
    servers: []
    post:
      summary: Create a project
      description: Creates a new project
      operationId: create-project
      tags:
        - Projects
      security:
        - JWTAuth: []
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/projects/{projectId}:
    servers: []
    patch:
      summary: Update a project
      description: Updates an existing project
      operationId: update-project
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the project to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200':
          description: Project updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete a project
      description: Deletes a project and all its associated workspaces
      operationId: delete-project
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the project to delete
      responses:
        '204':
          description: Project successfully deleted
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      summary: Get a project
      description: Retrieves a single project by ID
      operationId: get-project
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the project to retrieve
      responses:
        '200':
          description: Project retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/projects/list:
    servers: []
    get:
      summary: List projects in flat structure
      description: Retrieves all projects with pagination support
      operationId: list-projects-flat
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Offset'
        - name: maxDepth
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 5
            description: Maximum depth of the project tree to return
        - name: poolId
          in: query
          required: false
          schema:
            type: string
          description: Filter projects by runner pool ID
      responses:
        '200':
          description: Projects retrieved successfully in flat list format
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  totalCount:
                    type: integer
                    description: Total count of projects
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/projects/tree:
    servers: []
    get:
      summary: List projects in tree structure
      description: Retrieves all projects in a hierarchical tree format
      operationId: list-projects-tree
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/SearchQuery'
        - name: variableSetId
          in: query
          required: false
          schema:
            type: string
            description: Filter projects by variable set ID
        - name: consumedOnly
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              When used with variableSetId, only return projects that consume
              the variable set
      responses:
        '200':
          description: Projects retrieved successfully in tree format
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectTree'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/projects/{projectId}/members:
    servers: []
    get:
      summary: List members of a project
      description: Retrieves all members of a specified project
      operationId: list-project-members
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the project
      responses:
        '200':
          description: Members retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Member'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Add members to a project
      description: Adds new members to a specified project
      operationId: add-project-members
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Member'
      responses:
        '201':
          description: Members added successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Member'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Remove members from a project
      description: Deletes specified members from a project
      operationId: delete-project-members
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                description: User IDs of the members to remove
      responses:
        '204':
          description: Members removed successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/projects/{projectId}/workspaces:
    servers: []
    get:
      summary: List workspaces of a project
      description: Retrieves all workspaces of a specified project
      operationId: list-project-workspaces
      tags:
        - Projects
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the project
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Offset'
        - name: poolId
          in: query
          required: false
          schema:
            type: string
          description: Filter workspaces by runner pool ID
        - name: variableSetId
          in: query
          required: false
          schema:
            type: string
          description: >-
            If provided, only workspaces that consume the variable set will be
            returned
        - name: explicitConsumption
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            If true, only workspaces that have an explicit consumption of the
            variable set will be returned. Must be used in conjunction with
            variableSetId
      responses:
        '200':
          description: Workspaces retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RunnersWorkspace'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/projects/labels:
    servers: []
    get:
      summary: List all project labels
      description: Retrieves all available project labels for the account
      operationId: list-project-labels
      tags:
        - Projects
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Project labels retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: List of project labels
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/variables/projects/{projectId}:
    servers: []
    get:
      operationId: list_project_variables
      summary: List variables for a project
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of project variables
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VariableWithOrigin'
      tags:
        - projectVariable_other
  /runners/variables/projects/{projectId}/variables:
    servers: []
    post:
      operationId: upsert_variables_in_project
      summary: Upsert variables within a project (create or update)
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertProjectVariablesRequest'
      responses:
        '204':
          description: Variables upserted within project
      tags:
        - projectVariable_other
    delete:
      operationId: delete_variables_from_project
      summary: Delete variables from a project
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteProjectVariablesRequest'
      responses:
        '204':
          description: Variables deleted from project
      tags:
        - projectVariable_other
  /runners/variables/projects/{projectId}/variable-sets/variables:
    servers: []
    get:
      operationId: list_project_variable_sets_variables
      summary: List variables from variable sets attached to a project
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
        - name: variableAssociation
          in: query
          required: false
          schema:
            type: string
            enum:
              - consumed
              - non-consumed
              - all
          description: >-
            Filter variable sets by consumption status. Defaults to 'consumed'
            for backward compatibility.
      responses:
        '200':
          description: A list of variables from variable sets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VariableWithOrigin'
      tags:
        - projectVariable_other
  /runners/variables/workspaces/{workspaceId}/variables:
    servers: []
    get:
      operationId: list_workspace_variables
      summary: List variables for a workspace
      security:
        - JWTAuth: []
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: List of workspace variables
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VariableWithOrigin'
      tags:
        - workspaceVariable_other
    post:
      operationId: upsert_workspace_variables
      summary: Upsert variables within a workspace (create or update)
      security:
        - JWTAuth: []
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertVariablesRequest'
      responses:
        '204':
          description: Variables upserted within workspace
      tags:
        - workspaceVariable_other
    delete:
      operationId: delete_workspace_variables
      summary: Delete variables from a workspace
      security:
        - JWTAuth: []
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteVariablesRequest'
      responses:
        '204':
          description: Variables deleted from workspace
      tags:
        - workspaceVariable_other
  /runners/variables/variable-sets:
    servers: []
    get:
      operationId: list_variable_sets
      summary: List variable sets
      tags:
        - Variable Sets
      security:
        - JWTAuth: []
      parameters:
        - name: searchQuery
          in: query
          required: false
          schema:
            type: string
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: List of variable sets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VariableSet'
    post:
      operationId: create_variable_set
      summary: Create a new variable set
      tags:
        - Variable Sets
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVariableSetRequest'
      responses:
        '201':
          description: Variable set created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVariableSetResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/variables/variable-sets/{variableSetId}/variables:
    servers: []
    get:
      operationId: list_variable_set_variables
      summary: List variables in a variable set
      tags:
        - Variable Sets
      security:
        - JWTAuth: []
      parameters:
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: List of variables in variable set
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VariableWithOrigin'
    post:
      operationId: upsert_variables_in_set
      summary: Upsert variables within a variable set (create or update)
      tags:
        - Variable Sets
      security:
        - JWTAuth: []
      parameters:
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertVariableSetVariablesRequest'
      responses:
        '204':
          description: Variables upserted within variable set
    delete:
      operationId: delete_variables_from_set
      summary: Delete variables from a variable set
      tags:
        - Variable Sets
      security:
        - JWTAuth: []
      parameters:
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteVariablesRequest'
      responses:
        '204':
          description: Variables deleted from variable set
  /runners/variables/variable-sets/{variableSetId}:
    servers: []
    get:
      operationId: get_variable_set
      summary: Get a variable set
      tags:
        - Variable Sets
      security:
        - JWTAuth: []
      parameters:
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Variable set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariableSetWithAssociation'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: update_variable_set
      summary: Update a variable set
      tags:
        - Variable Sets
      security:
        - JWTAuth: []
      parameters:
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVariableSetRequest'
      responses:
        '204':
          description: Variable set updated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: delete_variable_set
      summary: Delete a variable set
      tags:
        - Variable Sets
      security:
        - JWTAuth: []
      parameters:
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Variable set deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/variables/projects/{projectId}/variable-sets/{variableSetId}/attach:
    servers: []
    post:
      operationId: attach_variable_set_to_project
      summary: Attach a variable set to a project
      tags:
        - Variable Set Operations
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                consume:
                  type: boolean
                  description: Whether to consume the variable set values
                  default: true
              required:
                - consume
      responses:
        '204':
          description: Variable set attached to project
  /runners/variables/projects/{projectId}/variable-sets/{variableSetId}/detach:
    servers: []
    post:
      operationId: detach_variable_set_from_project
      summary: Detach a variable set from a project
      tags:
        - Variable Set Operations
      security:
        - JWTAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Variable set detached from project
  /runners/variables/workspaces/{workspaceId}/variable-sets/{variableSetId}/bind:
    servers: []
    post:
      operationId: bind_variable_set_to_workspace
      summary: Bind a variable set to a workspace
      tags:
        - Variable Set Operations
      security:
        - JWTAuth: []
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Variable set bound to workspace
  /runners/variables/workspaces/{workspaceId}/variable-sets/{variableSetId}/unbind:
    servers: []
    post:
      operationId: unbind_variable_set_from_workspace
      summary: Unbind a variable set from a workspace
      tags:
        - Variable Set Operations
      security:
        - JWTAuth: []
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
        - name: variableSetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Variable set unbound from workspace
  /runners/workspaces:
    servers: []
    post:
      summary: Create a new workspace
      description: Creates a new workspace with the provided configuration
      operationId: create-workspace
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspaceRequest'
      responses:
        '201':
          description: Workspace created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnersWorkspace'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/workspaces/labels:
    servers: []
    get:
      summary: List all workspace labels
      description: Retrieves all available workspace labels for the account
      operationId: list-workspace-labels
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Workspace labels retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: List of workspace labels
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/workspaces/{workspaceId}/tasks/destroy:
    servers: []
    post:
      summary: Destroy workspace infrastructure resources
      description: >-
        Initiates a destroy task to clean up cloud infrastructure resources
        managed by this workspace. This does not delete the workspace entity
        itself.
      operationId: destroy-workspace-resources
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunTaskRequest'
      responses:
        '200':
          description: Destroy task initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/workspaces/{workspaceId}:
    servers: []
    get:
      summary: Get workspace details
      description: Retrieves details for a specific workspace
      operationId: get-workspace
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: Workspace details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnersWorkspace'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Deploy workspace
      description: >-
        Deploys a workspace by running plan or apply tasks based on the provided
        task type
      operationId: deploy-workspace
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                taskType:
                  type: string
                  enum:
                    - plan
                    - apply
                  description: The type of task to run (plan or apply)
                vcs:
                  type: object
                  properties:
                    reference:
                      type: string
                      description: The branch to deploy from
                    type:
                      type: string
                      enum:
                        - branch
                        - tag
                        - commit
                trigger:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - manual
                        - scheduled
                  description: Trigger configuration for the deployment
                cmdArguments:
                  type: string
                  description: Additional command line arguments
              required:
                - taskType
                - vcs
                - trigger
      responses:
        '200':
          description: Workspace deployed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Workspace deployed successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      summary: Update a workspace
      description: Updates an existing workspace with the provided configuration
      operationId: edit-workspace
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditWorkspaceRequest'
      responses:
        '200':
          description: Workspace updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnersWorkspace'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete a workspace
      description: >-
        Deletes a specific workspace and optionally destroys its infrastructure
        resources
      operationId: delete-runners-workspace
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: destroy
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >-
            Whether to destroy infrastructure resources before deleting the
            workspace
        - name: description
          in: query
          required: false
          schema:
            type: string
          description: Optional description for the deletion operation
      responses:
        '200':
          description: Workspace deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Workspace deleted successfully
                  workspaceId:
                    type: string
                    description: The ID of the deleted workspace
                  resourcesDestroyed:
                    type: boolean
                    description: Whether resources were destroyed
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/workspaces/{workspaceId}/tasks/{taskId}/apply:
    servers: []
    post:
      summary: Manually trigger a apply on a task
      description: >-
        Manually triggers a terraform apply for the specified task within the
        workspace
      operationId: run-manual-apply-task
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                taskType:
                  type: string
                  enum:
                    - apply
                  description: The type of task to run apply
                vcs:
                  type: object
                  properties:
                    reference:
                      type: string
                      description: The branch to run apply from
                    type:
                      type: string
                      enum:
                        - branch
                        - tag
                        - commit
                trigger:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - manual
                  description: Trigger configuration for the deployment
                cmdArguments:
                  type: string
                  description: Additional command line arguments
              required:
                - taskType
                - vcs
                - trigger
      responses:
        '200':
          description: Manual apply triggered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Manual apply triggered successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/workspaces/{workspaceId}/tasks/{taskId}/discard:
    servers: []
    post:
      summary: Discard a task
      description: Discards the specified task within the workspace
      operationId: discard-workspace-task
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/TaskId'
      responses:
        '202':
          description: Task discard operation has initiated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/workspaces/{workspaceId}/tasks/{taskId}/resources/search:
    servers: []
    post:
      summary: List Task Resources
      description: Lists resources for a specific task within the workspace
      operationId: list-task-resources
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/TaskId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRunResourcesRequest'
      responses:
        '200':
          description: Task resources retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRunResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/workspaces/{workspaceId}/run/{runId}/status:
    servers: []
    get:
      summary: Get specific run status
      description: Retrieves the status of a specific run within the workspace
      operationId: get-workspace-run-status
      tags:
        - Runners Workspaces
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/RunId'
      responses:
        '200':
          description: Run status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: >-
                      Current status of the run (e.g., pending, running,
                      completed, failed, etc)
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools:
    servers: []
    get:
      summary: List runner pools
      description: Retrieves all runner pools for the account
      operationId: list_runner_pools
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Offset'
        - name: status
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PoolHealthStatus'
          description: Filter pools by health status
        - name: labels
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: Filter pools by labels
        - name: sort
          in: query
          required: false
          schema:
            type: object
            properties:
              field:
                type: string
                enum:
                  - name
                  - createdAt
                  - updatedAt
                  - runnersCount
                  - assignedProjectsCount
                  - assignedWorkspaceCount
                  - poolStatus
              direction:
                type: string
                enum:
                  - asc
                  - desc
          description: Sort criteria for runner pools
      responses:
        '200':
          description: Runner pools retrieved successfully
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RunnerPool'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create a runner pool
      description: Creates a new self-hosted runner pool
      operationId: create_runner_pool
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunnerPoolRequest'
      responses:
        '201':
          description: Runner pool created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRunnerPoolResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/vcs/{vcsId}/token:
    servers: []
    get:
      summary: Get VCS token
      description: >-
        Retrieves a VCS token for the specified Account Id and VCS Id
        (self-hosted)
      operationId: self_hosted_get_vcs_token
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/VcsId'
      responses:
        '200':
          description: VCS token retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VcsTokenResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/search:
    servers: []
    post:
      summary: Search runner pools
      description: Search runner pools with advanced filtering, sorting, and text search
      operationId: search_runner_pools
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Offset'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRunnerPoolsRequest'
      responses:
        '200':
          description: Runner pools matching search criteria retrieved successfully
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RunnerPool'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/assignable-tree:
    servers: []
    get:
      summary: Get assignable tree
      description: >-
        Retrieves a hierarchical tree of projects and workspaces that can be
        assigned to runner pools, with pool assignment information
      operationId: get_assignable_tree
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      parameters:
        - name: poolId
          in: query
          required: false
          schema:
            type: string
          description: Optional pool ID to include in metadata
      responses:
        '200':
          description: Assignable tree retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignableTreeResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/{poolId}:
    servers: []
    get:
      summary: Get runner pool details
      description: Retrieves details for a specific runner pool
      operationId: get_runner_pool
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
      responses:
        '200':
          description: Runner pool details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnerPool'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      summary: Update a runner pool
      description: Updates an existing runner pool
      operationId: update_runner_pool
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRunnerPoolRequest'
      responses:
        '200':
          description: Runner pool updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnerPool'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete a runner pool
      description: Deletes a runner pool
      operationId: delete_runner_pool
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
      responses:
        '204':
          description: Runner pool deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/{poolId}/deployment-instructions:
    servers: []
    post:
      summary: Get runner deployment instructions
      description: Retrieves deployment instructions for setting up runners in a pool
      operationId: get_runner_deployment_instructions
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRunnerDeploymentInstructionsRequest'
      responses:
        '200':
          description: Runner deployment instructions retrieved successfully
          content:
            application/json:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/{poolId}/runners:
    servers: []
    get:
      summary: List runners in pool
      description: Retrieves all runners in a specific runner pool
      operationId: list_runners
      tags:
        - Self-Hosted Runners
      security:
        - JWTAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Offset'
        - name: status
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RunnerHealthStatus'
          description: Filter runners by health status
      responses:
        '200':
          description: Runners retrieved successfully
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Runner'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/workspaces/{workspaceId}:
    servers: []
    get:
      summary: Get a workspace (self-hosted)
      description: >-
        Retrieves details for a specific workspace by account and workspace ids
        (self-hosted)
      operationId: self_hosted_get_workspace
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: Workspace details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnersWorkspace'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      summary: Update a workspace (self-hosted)
      operationId: self_hosted_update_workspace
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceRequest'
      responses:
        '200':
          description: Workspace updated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/tasks/{taskId}:
    servers: []
    get:
      summary: Get task (self-hosted)
      description: Retrieves task details by ID (self-hosted)
      operationId: self_hosted_get_task
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Task retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      summary: Update task status (self-hosted)
      description: Updates task status, error and current step for a task (self-hosted)
      operationId: self_hosted_update_task
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskStatusRequest'
      responses:
        '200':
          description: Task status updated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/tasks/run:
    servers: []
    post:
      summary: Run a task
      description: Initiates a new task execution (self-hosted)
      operationId: self_hosted_run_task
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfHostedRunTaskRequest'
      responses:
        '200':
          description: Task initiated successfully
          content:
            application/json:
              schema:
                type: string
                description: Task ID
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/tasks/run/v2:
    servers: []
    post:
      summary: Run a task v2 (self-hosted)
      description: Initiates a new task execution with enhanced response (self-hosted)
      operationId: self_hosted_run_task_v2
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfHostedRunTaskRequest'
      responses:
        '200':
          description: Task initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfHostedRunTaskV2Response'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/tasks/{taskId}/blob:
    servers: []
    get:
      summary: Get task blob (self-hosted)
      description: Retrieves task blob data by task ID (self-hosted)
      operationId: self_hosted_get_task_blob
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Task blob retrieved successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  format: byte
                  nullable: true
                description: >-
                  Map of sub-task types to blob content (base64-encoded byte
                  arrays)
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/tasks/invalid-artifacts:
    servers: []
    post:
      summary: Save invalid artifacts (self-hosted)
      description: Saves invalid artifacts for a task (self-hosted)
      operationId: self_hosted_save_invalid_artifacts
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfHostedSaveInvalidArtifactsRequest'
      responses:
        '200':
          description: Invalid artifacts saved successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/tasks/logs:
    servers: []
    post:
      summary: Save logs (self-hosted)
      description: Saves logs for a task (self-hosted)
      operationId: self_hosted_save_logs
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfHostedSaveLogsRequest'
      responses:
        '200':
          description: Logs saved successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/workspaces/{workspaceId}/tasks/{taskId}/check-run:
    servers: []
    patch:
      summary: Update a check run (self-hosted)
      description: Updates the status of a VCS check run for a task (self-hosted)
      operationId: self_hosted_update_check_run
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCheckRunRequest'
      responses:
        '200':
          description: Check run updated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/terraform/plans/{key}/output:
    servers: []
    put:
      summary: Upload Terraform plan output (self-hosted)
      description: |
        Uploads a Terraform plan output in raw bytes (`[]byte`) to S3.  
        The request body must be sent as `application/octet-stream`.
      operationId: self_hosted_upload_plan_output
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - name: key
          in: path
          required: true
          description: S3 key or unique identifier for the plan output.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
            examples:
              samplePlan:
                summary: Raw Terraform plan output
                value: ''
      responses:
        '200':
          description: Plan output uploaded successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      summary: Get Terraform plan output (self-hosted)
      description: |
        Gets a Terraform plan output in raw bytes (`[]byte`) from S3.  
        The response body is sent as `application/octet-stream`.
      operationId: self_hosted_get_plan_output
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - name: key
          in: path
          required: true
          description: S3 key or unique identifier for the plan output.
          schema:
            type: string
      responses:
        '200':
          description: Plan output retrieved successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete Terraform plan output (self-hosted)
      operationId: self_hosted_delete_plan_output
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - name: key
          in: path
          required: true
          description: S3 key or unique identifier for the plan output.
          schema:
            type: string
      responses:
        '204':
          description: Plan output deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/workspace/{workspaceId}/task/{taskId}/check-pending-task:
    servers: []
    post:
      summary: Check for pending tasks (self-hosted)
      operationId: self_hosted_check_pending_task
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: No pending tasks exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckPendingTasksResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/{accountId}/workspaces/{workspaceId}/runs:
    servers: []
    post:
      summary: Add a workspace run (self-hosted)
      operationId: self_hosted_add_workspace_run
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddWorkspaceRunRequest'
      responses:
        '200':
          description: Workspace run added successfully
        '201':
          description: Workspace run created successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      summary: Update a workspace run status and error (self-hosted)
      operationId: self_hosted_update_workspace_run
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceRunRequest'
      responses:
        '200':
          description: Workspace run updated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - self-hosted_other
  /self-hosted/{accountId}/workspaces/{workspaceId}/runs/last:
    servers: []
    get:
      summary: Get the last workspace run (self-hosted)
      operationId: self_hosted_get_last_workspace_run
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: Last workspace run retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceRun'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/{poolId}/runners/register:
    servers: []
    post:
      summary: Register runner
      description: Registers a new runner with the system (used by runners themselves)
      operationId: register_runner
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRunnerRequest'
      responses:
        '201':
          description: Runner registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnerCredentialsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/{poolId}/runners/{runnerName}/deregister:
    servers: []
    post:
      summary: Deregister runner
      description: Deregisters a runner from the system (used by runners themselves)
      operationId: deregister_runner
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
        - $ref: '#/components/parameters/RunnerName'
      responses:
        '204':
          description: Runner deregistered successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/{poolId}/runners/{runnerName}/heartbeat:
    servers: []
    post:
      summary: Report runner health
      description: Reports runner health status (used by runners themselves)
      operationId: report_runner_health
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
        - $ref: '#/components/parameters/RunnerName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunnerHeartbeatRequest'
      responses:
        '204':
          description: Runner health reported successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /runners/runner-pools/{poolId}/runners/{runnerName}/renew-credentials:
    servers: []
    post:
      summary: Renew runner credentials
      description: Renews runner authentication credentials (used by runners themselves)
      operationId: renew_runner_credentials
      tags:
        - Self-Hosted Runners
      security:
        - RunnerPoolAuth: []
      parameters:
        - $ref: '#/components/parameters/PoolId'
        - $ref: '#/components/parameters/RunnerName'
      responses:
        '200':
          description: Runner credentials renewed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnerCredentialsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /self-hosted/oauth/token:
    servers: []
    post:
      summary: Token generation endpoint
      operationId: self_hosted_oidc_oauth_token
      security:
        - RunnerPoolAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: OAuth 2.0 grant type (must be "client_credentials")
                  example: client_credentials
                client_id:
                  type: string
                  description: >-
                    Client identifier (not validated, included for OAuth 2.0
                    spec compliance)
                  example: iac-runner
                client_secret:
                  type: string
                  description: >-
                    Client secret (not validated, included for OAuth 2.0 spec
                    compliance)
                scope:
                  type: string
                  description: Requested scope (should include "openid")
                  example: openid
                account_id:
                  type: string
                  description: Account ID for token claims
              required:
                - grant_type
                - scope
                - account_id
      responses:
        '200':
          description: Successfully generated OIDC token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - self-hosted_other
  /.well-known/openid-configuration:
    servers: []
    get:
      summary: OIDC Discovery endpoint
      operationId: oidc-discovery
      responses:
        '200':
          description: OIDC configuration document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCConfiguration'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
      tags:
        - openId-connect_other
  /.well-known/jwks.json:
    servers: []
    get:
      summary: JWKS endpoint
      operationId: oidc-jwks
      responses:
        '200':
          description: JSON Web Key Set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWKSet'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
      tags:
        - openId-connect_other
  /governance/insights:
    servers: []
    post:
      summary: Get Insights by Account
      description: >-
        Retrieves insights for a specific account with optional filtering and
        field projection
      operationId: get_insights
      tags:
        - Governance
      security:
        - JWTAuth: []
      parameters:
        - name: fields
          in: query
          description: Comma-separated list of fields to include in the response
          required: false
          schema:
            type: string
            example: id,name,description,status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Search query string
                  example: ''
                labels:
                  oneOf:
                    - type: string
                      description: Comma-separated labels
                      example: security,compliance
                    - type: array
                      items:
                        type: string
                      description: Array of labels
                      example:
                        - security
                        - compliance
                  description: Labels for filtering insights
                frameworks:
                  type: array
                  items:
                    type: string
                  description: Array of framework filters
                  example: []
                category:
                  type: string
                  description: Category filter
                  example: ''
                isDefault:
                  type: boolean
                  nullable: true
                  description: Default filter flag
                  example: null
                onlySubscribed:
                  type: boolean
                  description: Filter for subscribed insights only
                  example: false
                onlyProduction:
                  type: boolean
                  description: Filter for production insights only
                  example: false
                onlyMatchingAssets:
                  type: boolean
                  description: Filter for insights with matching assets
                  example: false
                onlyEnabled:
                  type: boolean
                  description: Filter for enabled insights only
                  example: false
                onlyAvailableProviders:
                  type: boolean
                  description: Filter for available providers only
                  example: true
                showExclusion:
                  type: boolean
                  description: Show exclusion rules
                  example: false
                type:
                  type: array
                  items:
                    type: string
                  description: Array of type filters
                  example: []
                providers:
                  type: array
                  items:
                    type: string
                  description: Array of provider filters
                  example: []
                integrations:
                  type: array
                  items:
                    type: string
                  description: Array of integration filters
                  example: []
                severity:
                  type: array
                  items:
                    oneOf:
                      - type: string
                      - type: integer
                  description: Array of severity filters
                id:
                  oneOf:
                    - type: array
                      items:
                        type: string
                      description: Array of specific insight ID filters
                      example:
                        - 665088e83438d32bdda77193
                        - 661bf411f3a3638decfea721
                    - type: string
                      nullable: true
                      description: No ID filter applied
                  description: Array of specific insight ID filters or null
                page:
                  type: integer
                  description: Page number for pagination
                  minimum: 1
                  example: 1
                page_size:
                  type: integer
                  description: Number of items per page
                  minimum: 1
                  example: 50
                sorting:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                      sort:
                        type: string
                        enum:
                          - asc
                          - desc
                  description: Array of sorting criteria
                  example:
                    - field: name
                      sort: asc
                    - field: createdAt
                      sort: desc
                providersAccounts:
                  type: array
                  items:
                    type: string
                  description: Array of provider account filters
                  example:
                    - awsobjects
                    - k8sobjects
                    - akamaiobjects
                    - datadogobjects
                    - oktaobjects
                    - githubobjects
                    - newrelicobjects
                    - cloudflareobjects
                    - gcpobjects
                    - pagerdutyobjects
                    - mongodbatlasobjects
                    - azurermobjects
                    - aws
                    - kubernetes
                    - akamai
                    - datadog
                    - okta
                    - github
                    - newrelic
                    - cloudflare
                    - google
                    - pagerduty
                    - mongodbatlas
                    - azurerm
              required: []
      responses:
        '200':
          description: Insights retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
                    description: Total number of insights
                  page:
                    type: integer
                    description: Current page number
                  page_size:
                    type: integer
                    description: Number of items per page
        '400':
          description: Bad request - missing required parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /governance/insights/create:
    servers: []
    post:
      summary: Create a new Insight
      description: >-
        Creates a new insight with the provided configuration. The endpoint
        validates required fields (name, code, type, providerIds, category) and
        tests the Rego code for validity before creation.
      operationId: create_insight
      tags:
        - Governance
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the insight
                description:
                  type: string
                  description: Description of the insight
                code:
                  type: string
                  description: Rego code for the insight rule (can be base64 encoded)
                  example: >-
                    ZmlyZWZseSB7CiAgICBtYXRjaAp9CgptYXRjaCB7CiAgICBpbnB1dC5iYXRjaF90YXJnZXQgPT0gInRlc3QiCn0=
                type:
                  type: array
                  items:
                    type: string
                  description: Array of insight types
                  example:
                    - aws_cloudwatch_event_target
                providerIds:
                  type: array
                  items:
                    type: string
                  description: Array of provider IDs this insight applies to
                  example:
                    - aws_all
                    - 6616a2dbf4992fc0bab0463f
                labels:
                  oneOf:
                    - type: string
                      description: Comma-separated labels
                      example: security,compliance
                    - type: array
                      items:
                        type: string
                      description: Array of labels
                      example:
                        - security
                        - compliance
                  description: Labels for the insight
                severity:
                  type: integer
                  description: Severity level of the insight
                category:
                  type: string
                  description: Category of the insight
                  example: Misconfiguration
                frameworks:
                  type: array
                  items:
                    type: string
                  description: Array of compliance frameworks this insight relates to
                  example:
                    - SOC2
                    - ISO27001
              required:
                - name
                - code
                - type
                - providerIds
                - category
      responses:
        '200':
          description: Insight created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the created insight
                  name:
                    type: string
                    description: Name of the insight
                  description:
                    type: string
                    description: Description of the insight
                  code:
                    type: string
                    description: Rego code for the insight rule
                  type:
                    type: array
                    items:
                      type: string
                    description: Array of insight types
                  providerIds:
                    type: array
                    items:
                      type: string
                    description: Array of provider IDs
                  labels:
                    oneOf:
                      - type: string
                        description: Comma-separated labels
                        example: security,compliance
                      - type: array
                        items:
                          type: string
                        description: Array of labels
                        example:
                          - security
                          - compliance
                    description: Labels
                  severity:
                    type: string
                    description: Severity level
                  category:
                    type: string
                    description: Category
                  frameworks:
                    type: array
                    items:
                      type: string
                    description: Array of compliance frameworks
        '400':
          description: >-
            Bad request - missing required parameters (name, code, type,
            providerIds, category), empty field values, or invalid Rego rule
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /governance/insights/{id}:
    servers: []
    put:
      summary: Update an Insight
      description: >-
        Updates an existing insight with the provided configuration. The
        endpoint validates required fields (name, code, type, providerIds,
        category) and tests the Rego code for validity before updating.
      operationId: update_insight
      tags:
        - Governance
      security:
        - JWTAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the insight to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the insight
                description:
                  type: string
                  description: Description of the insight
                code:
                  type: string
                  description: Rego code for the insight rule (can be base64 encoded)
                  example: >-
                    ZmlyZWZseSB7CiAgICBtYXRjaAp9CgptYXRjaCB7CiAgICBpbnB1dC5iYXRjaF90YXJnZXQgPT0gInRlc3QiCn0=
                type:
                  type: array
                  items:
                    type: string
                  description: Array of insight types
                  example:
                    - aws_cloudwatch_event_target
                providerIds:
                  type: array
                  items:
                    type: string
                  description: Array of provider IDs this insight applies to
                  example:
                    - aws_all
                    - 6616a2dbf4992fc0bab0463f
                labels:
                  oneOf:
                    - type: string
                      description: Comma-separated labels
                      example: security,compliance
                    - type: array
                      items:
                        type: string
                      description: Array of labels
                      example:
                        - security
                        - compliance
                  description: Labels for the insight
                severity:
                  type: integer
                  description: Severity level of the insight
                category:
                  type: string
                  description: Category of the insight
                  example: Misconfiguration
                frameworks:
                  type: array
                  items:
                    type: string
                  description: Array of compliance frameworks this insight relates to
                  example:
                    - SOC2
                    - ISO27001
              required:
                - name
                - code
                - type
                - providerIds
                - category
      responses:
        '200':
          description: Insight updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the updated insight
                  name:
                    type: string
                    description: Name of the insight
                  description:
                    type: string
                    description: Description of the insight
                  code:
                    type: string
                    description: Rego code for the insight rule
                  type:
                    type: array
                    items:
                      type: string
                    description: Array of insight types
                  providerIds:
                    type: array
                    items:
                      type: string
                    description: Array of provider IDs
                  labels:
                    oneOf:
                      - type: string
                        description: Comma-separated labels
                        example: security,compliance
                      - type: array
                        items:
                          type: string
                        description: Array of labels
                        example:
                          - security
                          - compliance
                    description: Labels
                  severity:
                    type: string
                    description: Severity level
                  category:
                    type: string
                    description: Category
                  frameworks:
                    type: array
                    items:
                      type: string
                    description: Array of compliance frameworks
        '400':
          description: >-
            Bad request - missing required parameters (name, code, type,
            providerIds, category), empty field values, or invalid Rego rule
        '401':
          description: Unauthorized
        '404':
          description: Insight not found
        '500':
          description: Internal server error
    delete:
      summary: Delete an Insight
      description: Deletes a specific insight by ID
      operationId: delete_insight
      tags:
        - Governance
      security:
        - JWTAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the insight to delete
          schema:
            type: string
      responses:
        '204':
          description: Insight deleted successfully
        '400':
          description: Bad request - missing required parameters
        '401':
          description: Unauthorized
        '404':
          description: Insight not found
        '500':
          description: Internal server error
  /api/codify:
    servers: []
    post:
      summary: Codify a single cloud asset to Infrastructure as Code
      description: Generate IaC code (Terraform HCL) for a specific cloud asset
      operationId: codify-asset
      tags:
        - Codification
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodifyAssetRequest'
      responses:
        '200':
          description: Successfully codified asset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodifyAssetResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/codify/repos:
    servers: []
    get:
      summary: Fetches repositories
      description: Fetches repositories that contain terraform modules
      operationId: list-module-repos
      tags:
        - Codification
      security:
        - JWTAuth: []
      parameters:
        - name: resourceTypes
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successfully retrieved module repos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModuleReposResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/codify/repos/modules:
    servers: []
    get:
      summary: Fetches modules from a given repository
      description: Fetches modules available in a repository
      operationId: list-modules
      tags:
        - Codification
      security:
        - JWTAuth: []
      parameters:
        - name: repository
          in: query
          required: true
          description: Full repository path (e.g., owner/name/subdirectory)
          schema:
            type: string
        - name: resourceTypes
          in: query
          required: true
          description: List of resource types to filter modules by, separated by commas
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successfully fetched modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModulesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/codify/module:
    servers: []
    post:
      summary: Create a module call
      description: >-
        Create a module call using the provided resource along with its
        dependencies
      operationId: codify-module
      tags:
        - Codification
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodifyModuleRequest'
      responses:
        '200':
          description: Successful module call
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodifyModuleResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/codify/module/create:
    servers: []
    post:
      summary: Create a new module
      description: Create a new module using the provided resource
      operationId: create-module
      tags:
        - Codification
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModuleRequest'
      responses:
        '200':
          description: Successfully created module
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateModuleResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/codify/pullRequest:
    servers: []
    post:
      summary: Create a pull request with codified assets
      description: >-
        Creates a pull request containing Infrastructure as Code for specified
        cloud resources
      operationId: create-pull-request
      tags:
        - Codification
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePullRequestRequest'
      responses:
        '200':
          description: Successfully created pull request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePullRequestResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/integrations/{providerType}:
    servers: []
    get:
      summary: Get integrations by provider type
      description: Retrieves all integrations for a specific cloud provider
      operationId: list-integrations
      tags:
        - Integrations
      security:
        - JWTAuth: []
      parameters:
        - name: providerType
          in: path
          required: true
          schema:
            type: string
            enum:
              - aws
              - gcp
              - azurerm
              - k8s
          description: The cloud provider type
      responses:
        '200':
          description: Successfully retrieved integrations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IntegrationResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create a new integration
      description: Creates a new cloud integration (AWS or K8s)
      operationId: create-integration
      tags:
        - Integrations
      security:
        - JWTAuth: []
      parameters:
        - name: providerType
          in: path
          required: true
          schema:
            type: string
            enum:
              - aws
              - k8s
          description: The cloud provider type (aws or k8s)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CreateAwsIntegrationRequest'
                - $ref: '#/components/schemas/CreateK8sIntegrationRequest'
      responses:
        '200':
          description: Successfully created integration
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CreateAwsIntegrationResponse'
                  - $ref: '#/components/schemas/CreateK8sIntegrationResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Integration already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/integrations/{providerType}/{clusterId}:
    servers: []
    delete:
      summary: Delete a K8s integration
      description: Deletes an existing K8s integration by cluster ID
      operationId: delete-integration
      tags:
        - Integrations
      security:
        - JWTAuth: []
      parameters:
        - name: providerType
          in: path
          required: true
          schema:
            type: string
            enum:
              - k8s
          description: The provider type (only k8s supported for delete)
        - name: clusterId
          in: path
          required: true
          schema:
            type: string
          description: The cluster ID to delete
      responses:
        '200':
          description: Successfully deleted integration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteIntegrationResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/integrations/aws/external-id:
    servers: []
    get:
      summary: Get AWS external ID
      description: >-
        Retrieves the AWS external ID for the account, used in IAM role trust
        policies
      operationId: get-aws-external-id
      tags:
        - Integrations
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successfully retrieved external ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalIdResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/config/aws/cft-config:
    servers: []
    get:
      summary: Get AWS CloudFormation template configuration
      description: >-
        Returns the S3 bucket URL and default AWS region for CloudFormation
        stack deployment, specific to this Firefly instance
      operationId: get-aws-cft-config
      tags:
        - Config
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successfully retrieved AWS CFT configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwsCftConfigResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /infrastructure/public-nat-ips:
    servers: []
    get:
      operationId: get_public_nat_ips
      summary: Get public NAT IP addresses
      description: >-
        Returns a list of public NAT IP addresses used by the Firefly
        infrastructure
      tags:
        - Infrastructure
      responses:
        '200':
          description: Successfully retrieved public NAT IPs
          content:
            application/json:
              schema:
                type: object
                properties:
                  ips:
                    type: array
                    items:
                      type: string
                      format: ipv4
                    description: List of public NAT IP addresses
                  count:
                    type: integer
                    description: Total number of IP addresses
                required:
                  - ips
                  - count
                example:
                  ips:
                    - 3.224.145.192
                    - 54.83.245.177
                    - 34.226.97.113
                  count: 3
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /user-service/{path}:
    servers: []
    get:
      summary: Proxy GET requests to User Service
      description: Proxies GET requests to the User Service
      operationId: user-service-proxy-get
      x-openapi-backend-squash: true
      tags:
        - User Service
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the user service
        - in: query
          name: search
          required: false
          schema:
            type: string
            maxLength: 255
          description: Search users by name or email using full-text search
          example: john@example.com
        - in: query
          name: type
          required: false
          schema:
            type: string
            enum:
              - USER
              - SA
              - TEAM
          description: Filter by user type - either regular USER or Service Account (SA)
          example: USER
        - in: query
          name: role_ids
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
            maxItems: 50
          style: form
          explode: false
          description: Filter by role IDs - users must have at least one of these roles
          example:
            - 550e8400-e29b-41d4-a716-446655440000
        - in: query
          name: team_ids
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
            maxItems: 50
          style: form
          explode: false
          description: >-
            Filter by team IDs - users must be members of at least one of these
            teams
          example:
            - 660f9511-f3ac-52e5-b827-557766551111
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Maximum number of users to return
          example: 25
        - in: query
          name: offset
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of users to skip
          example: 0
        - in: query
          name: pageSize
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Alternative to limit - maximum number of items per page
          example: 25
        - in: query
          name: page
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Page number for pagination
          example: 0
        - in: query
          name: sort
          required: false
          schema:
            type: string
          description: Sort parameter
        - in: query
          name: filter_by_email
          required: false
          schema:
            type: string
          description: Filter by email
        - in: query
          name: filter_by_role
          required: false
          schema:
            type: string
          description: Filter by role
        - in: query
          name: email
          required: false
          schema:
            type: string
          description: Filter by email
        - in: query
          name: user_id
          required: false
          schema:
            type: string
          description: Filter by user ID
          example: '1234567890'
        - in: query
          name: team_id
          required: false
          schema:
            type: string
          description: Filter by team ID
          example: 660f9511-f3ac-52e5-b827-557766551111
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from user service
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    post:
      summary: Proxy POST requests to User Service
      description: Proxies POST requests to the User Service
      operationId: user-service-proxy-post
      x-openapi-backend-squash: true
      tags:
        - User Service
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the user service
      requestBody:
        content:
          application/json:
            schema:
              type: object
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from user service
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    put:
      summary: Proxy PUT requests to User Service
      description: Proxies PUT requests to the User Service
      operationId: user-service-proxy-put
      x-openapi-backend-squash: true
      tags:
        - User Service
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the user service
      requestBody:
        content:
          application/json:
            schema:
              type: object
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from user service
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    patch:
      summary: Proxy PATCH requests to User Service
      description: Proxies PATCH requests to the User Service
      operationId: user-service-proxy-patch
      x-openapi-backend-squash: true
      tags:
        - User Service
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the user service
      requestBody:
        content:
          application/json:
            schema:
              type: object
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from user service
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    delete:
      summary: Proxy DELETE requests to User Service
      description: Proxies DELETE requests to the User Service
      operationId: user-service-proxy-delete
      x-openapi-backend-squash: true
      tags:
        - User Service
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the user service
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from user service
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
  /audit-log/{path}:
    servers: []
    get:
      summary: Proxy GET requests to Audit Log
      description: Proxies GET requests to the Audit Log
      operationId: audit-log-proxy-get
      x-openapi-backend-squash: true
      tags:
        - Audit Log
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the audit log
        - in: query
          name: search
          required: false
          schema:
            type: string
            maxLength: 255
          description: Search audit logs by name or email using full-text search
          example: john@example.com
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Maximum number of audit logs to return
          example: 25
        - in: query
          name: offset
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of audit logs to skip
          example: 0
        - in: query
          name: pageSize
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Alternative to limit - maximum number of items per page
          example: 25
        - in: query
          name: page
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Page number for pagination
          example: 0
        - in: query
          name: sort
          required: false
          schema:
            type: string
          description: Sort parameter
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from audit log
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    post:
      summary: Proxy POST requests to Audit Log
      description: Proxies POST requests to the Audit Log
      operationId: audit-log-proxy-post
      x-openapi-backend-squash: true
      tags:
        - Audit Log
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the audit log
      requestBody:
        content:
          application/json:
            schema:
              type: object
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from audit log
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
  /backup-and-dr/{path}:
    servers: []
    get:
      summary: Proxy GET requests to Backup and DR
      description: Proxies GET requests to the Backup and DR
      operationId: backup-and-dr-proxy-get
      x-openapi-backend-squash: true
      tags:
        - Backup and DR
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the backup and dr
        - in: query
          name: search
          required: false
          schema:
            type: string
            maxLength: 255
          description: Search backup and dr by name or email using full-text search
          example: john@example.com
        - in: query
          name: page_size
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            enum:
              - 25
              - 50
              - 100
            default: 25
          description: Maximum number of items per page
          example: 25
        - in: query
          name: page
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
          example: 1
        - in: query
          name: status
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - Active
                - Inactive
                - Pending
                - In Progress
                - Success
                - Failed
          description: |
            Filter by status (supports multiple values). 
            For policies: Active, Inactive
            For snapshots: Pending, In Progress, Success, Failed
          example:
            - Success
            - In Progress
        - in: query
          name: integration_id
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Filter by integration ID (supports multiple values)
          example:
            - '1234567890'
        - in: query
          name: asset_type
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Filter by resource type (supports multiple values)
          example:
            - aws_lambda_function
        - in: query
          name: region
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Filter by region (supports multiple values)
          example:
            - us-east-1
        - in: query
          name: policy_id
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Filter by policy ID (supports multiple values)
          example:
            - ffec4e2b-1dad-492e-a86f-6c4712427339
        - in: query
          name: from_date
          required: false
          schema:
            type: string
            format: date-time
          description: Filter snapshots from this date (ISO 8601 format)
          example: '2024-01-01T00:00:00Z'
        - in: query
          name: to_date
          required: false
          schema:
            type: string
            format: date-time
          description: Filter snapshots until this date (ISO 8601 format)
          example: '2024-12-31T23:59:59Z'
        - in: query
          name: provider_type
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: >-
            Filter by provider type (supports multiple values, e.g., "aws",
            "azure", "gcp")
          example:
            - aws
        - in: query
          name: sort_by
          required: false
          schema:
            type: string
            enum:
              - status
            default: status
          description: Field to sort by
          example: status
        - in: query
          name: sort_order
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort order (asc or desc)
          example: desc
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from backup and dr
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    post:
      summary: Proxy POST requests to Backup and DR
      description: Proxies POST requests to the Backup and DR
      operationId: backup-and-dr-proxy-post
      x-openapi-backend-squash: true
      tags:
        - Backup and DR
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the backup and dr
      requestBody:
        content:
          application/json:
            schema:
              type: object
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from backup and dr
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    put:
      summary: Proxy PUT requests to Backup and DR
      description: Proxies PUT requests to the Backup and DR
      operationId: backup-and-dr-proxy-put
      x-openapi-backend-squash: true
      tags:
        - Backup and DR
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the backup and dr
      requestBody:
        content:
          application/json:
            schema:
              type: object
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from backup and dr
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    delete:
      summary: Proxy DELETE requests to Backup and DR
      description: Proxies DELETE requests to the Backup and DR
      operationId: backup-and-dr-proxy-delete
      x-openapi-backend-squash: true
      tags:
        - Backup and DR
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to the backup and dr
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from backup and dr
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
  /api/inventory:
    servers: []
    post:
      summary: Retrieve inventory hits
      operationId: search-inventory
      parameters:
        - name: includeAssetConfiguration
          in: query
          description: Include asset configuration
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  $ref: '#/components/schemas/AssetSearchFilters'
                sorting:
                  type: object
                  properties:
                    field:
                      type: string
                      description: Field name to sort by
                    order:
                      type: string
                      enum:
                        - asc
                        - desc
                      description: Sort direction
                size:
                  type: integer
                  description: Number of results to return per page (max 10000)
                  default: 50
                source:
                  type: array
                  items:
                    type: string
                  description: List of fields to include in the response
                afterKey:
                  type: object
                  description: Pagination key for fetching next page of results
                  properties:
                    sortField:
                      type: string
                      description: Sort field value from the last result
                    id:
                      type: string
                      description: Unique identifier of the last result
      responses:
        '200':
          description: Successful response
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
            X-Total-Pages:
              $ref: '#/components/headers/X-Total-Pages'
          content:
            application/json:
              schema:
                type: object
                properties:
                  responseObjects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
                  totalObjects:
                    type: integer
                  afterKey:
                    type: object
                    description: The key to use for the next page of results
                    properties:
                      sortField:
                        type: string
                        description: Sort field value from the last result
                      id:
                        type: string
                        description: Unique identifier of the last result
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - api_other
      security:
        - JWTAuth: []
  /api/inventory/{assetId}:
    servers: []
    get:
      summary: Get an asset by ID
      operationId: get-asset
      security:
        - JWTAuth: []
      parameters:
        - name: assetId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - api_other
  /api/inventory/providers:
    servers: []
    get:
      summary: Get all supported providers
      description: Returns a list of all supported cloud and SaaS providers
      operationId: get-providers
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                  - aws
                  - gcp
                  - azurerm
                  - oci
                  - k8s
                  - akamai
                  - newrelic
                  - datadog
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - api_other
  /api/inventory/iac-coverage:
    servers: []
    post:
      summary: Get IaC coverage statistics
      description: >-
        Returns IaC coverage statistics for the account, optionally filtered by
        integrations
      operationId: get-iac-coverage
      security:
        - JWTAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IacCoverageRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IacCoverageResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - api_other
  /event-center:
    servers: []
    post:
      summary: Proxy POST requests to Event Center
      description: Proxies POST requests to the Event Center
      operationId: event-center-proxy-post
      x-openapi-backend-squash: true
      tags:
        - Event Center
      requestBody:
        content:
          application/json:
            schema:
              type: object
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from event center
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
  /organizations/{org}/entitlement-set:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    get:
      summary: Read organization entitlements
      operationId: tf-read-org-entitlements
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: org
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Organization entitlements
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/EntitlementSetResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '404':
          $ref: '#/components/responses/JsonApiNotFoundError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /organizations/{org}/workspaces/{name}:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    get:
      summary: Read workspace
      operationId: tf-read-workspace
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: org
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Workspace information
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WorkspaceResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '404':
          $ref: '#/components/responses/JsonApiNotFoundError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /workspaces/{workspace_id}/current-state-version:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    get:
      summary: Read current state version
      operationId: tf-read-current-state-version
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current state version
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/StateVersionResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '404':
          $ref: '#/components/responses/JsonApiNotFoundError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /workspaces/{workspace_id}/state-versions:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    post:
      summary: Upload state version
      description: >-
        Client sends state metadata and receives upload URL for 2-step state
        upload flow
      operationId: tf-upload-state-version
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/StateVersionUploadRequest'
      responses:
        '201':
          description: State version created, upload URL returned
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/StateVersionUploadResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '409':
          $ref: '#/components/responses/JsonApiConflictError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /workspaces/{workspace_id}/actions/lock:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    post:
      summary: Lock workspace
      operationId: tf-lock-workspace
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/LockWorkspaceRequest'
      responses:
        '200':
          description: Workspace locked
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WorkspaceResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '423':
          $ref: '#/components/responses/JsonApiLockedError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /workspaces/{workspace_id}/actions/unlock:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    post:
      summary: Unlock workspace
      operationId: tf-unlock-workspace
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/UnlockWorkspaceRequest'
      responses:
        '200':
          description: Workspace unlocked
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WorkspaceResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '404':
          $ref: '#/components/responses/JsonApiNotFoundError'
        '409':
          $ref: '#/components/responses/JsonApiConflictError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /workspaces/{workspace_id}/actions/force-unlock:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    post:
      summary: Force unlock workspace
      operationId: tf-force-unlock-workspace
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/UnlockWorkspaceRequest'
      responses:
        '200':
          description: Workspace force unlocked
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WorkspaceResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '423':
          $ref: '#/components/responses/JsonApiLockedError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /workspaces/{workspace_id}/state-versions/{state_version_id}/download:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    get:
      summary: Get state version download URL
      description: >-
        Returns a presigned URL for downloading the state file. The URL is valid
        for a limited time.
      operationId: tf-get-state-version-download
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
        - name: state_version_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Download URL retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - downloadUrl
                properties:
                  downloadUrl:
                    type: string
                    format: uri
                    description: Presigned URL for downloading the state file
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '404':
          $ref: '#/components/responses/JsonApiNotFoundError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /workspaces/{workspace_id}/state-versions/{state_version_id}/content:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    get:
      summary: Download state version content
      description: >-
        Returns a 307 redirect to the S3 presigned download URL. Used by
        Terraform/OpenTofu clients that send Authorization headers to the
        download URL. The redirect ensures the Authorization header is not sent
        to S3.
      operationId: tf-download-state-version-content
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
        - name: state_version_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '307':
          description: Redirect to S3 presigned download URL
          headers:
            Location:
              description: S3 presigned URL for downloading the state file
              schema:
                type: string
                format: uri
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '404':
          $ref: '#/components/responses/JsonApiNotFoundError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
    put:
      summary: Upload state version content
      description: >-
        Proxies the raw state file bytes to the orchestrator, which streams them
        to S3. This is step 2 of the 2-step state upload flow — the client PUTs
        the binary state body to the upload URL returned by step 1 (POST
        /workspaces/{workspace_id}/state-versions). No authentication is
        required: the upload URL itself is the capability token, issued only
        after a successful authenticated step 1.
      operationId: tf-upload-state-version-content
      tags:
        - Terraform Remote Backend
      security: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
        - name: state_version_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: State file uploaded successfully
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '404':
          $ref: '#/components/responses/JsonApiNotFoundError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
        '503':
          description: Service unavailable (upload concurrency limit reached)
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JsonApiError'
  /state-versions/{state_version_id}:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    get:
      summary: Read a state version by ID
      description: >-
        Returns a state version resource including the
        hosted-state-download-url.
      operationId: tf-read-state-version-by-id
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: state_version_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: State version found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/StateVersionResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '404':
          $ref: '#/components/responses/JsonApiNotFoundError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /workspaces/{workspace_id}/state-lock:
    servers:
      - url: https://api.firefly.ai/v2
        description: Firefly API Server
    get:
      summary: Get state lock information
      description: >-
        Returns the current lock information for a workspace, or null if no lock
        exists.
      operationId: tf-get-state-lock
      tags:
        - Terraform Remote Backend
      security:
        - JWTAuth: []
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Lock information or null if no lock exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockResponse'
        '401':
          $ref: '#/components/responses/JsonApiUnauthorizedError'
        '500':
          $ref: '#/components/responses/JsonApiInternalServerError'
  /relationships:
    servers: []
    post:
      operationId: get_relationships
      summary: Get resource relationships
      description: >
        Retrieves the relationships/connections for a specific resource
        identified by its FRN.

        Returns an array of connected resources with their full asset details
        including metadata,

        state information, and relationship type.


        Results are filtered based on the user's RBAC permissions - only
        connections to integrations

        the user has access to will be returned.
      tags:
        - Relationships
      security:
        - JWTAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - frn
                - integrationId
              properties:
                frn:
                  type: string
                  description: The Firefly Resource Name (FRN) of the resource to query
                  example: aws_instance:us-east-1:i-0123456789abcdef0
                integrationId:
                  type: string
                  description: The integration ID of the resource
                  example: 60123456789abcdef1234567
                level:
                  type: integer
                  description: Number of levels to traverse in the relationship graph
                  minimum: 1
                  maximum: 4
                  default: 1
                  example: 1
      responses:
        '200':
          description: Successfully retrieved relationships
          content:
            application/json:
              schema:
                type: array
                description: Array of connected resources with full asset details
                items:
                  $ref: '#/components/schemas/ResourceConnection'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden - User does not have permission to access this resource
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      You do not have permission to access resources from this
                      integration
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/iacStacks:
    servers: []
    post:
      summary: Search IaC stacks
      description: Query IaC stacks with filtering, sorting, and pagination
      operationId: search-iac-stacks
      tags:
        - IaC Stacks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchIacStacksRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchIacStacksResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - JWTAuth: []
  /api/iacStacks/backends:
    servers: []
    post:
      summary: Query backends
      description: Query backend/crawler data with filtering and pagination
      operationId: query-backends
      tags:
        - IaC Stacks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryBackendsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryBackendsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - JWTAuth: []
  /api/iacStacks/repositories:
    servers: []
    post:
      summary: Query repositories
      description: Query VCS repositories containing IaC code
      operationId: query-repositories
      tags:
        - IaC Stacks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRepositoriesRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IacStacksRepository'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - JWTAuth: []
  /api/iacStacks/modules:
    servers: []
    post:
      summary: Query modules
      description: Query Terraform/Pulumi modules with filtering and pagination
      operationId: query-modules
      tags:
        - IaC Stacks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryModulesRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryModulesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - JWTAuth: []
  /api/iacStacks/providers:
    servers: []
    post:
      summary: Query providers
      description: Query stack providers aggregations
      operationId: query-providers
      tags:
        - IaC Stacks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryProvidersRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryProvidersResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - JWTAuth: []
  /terralist/{path}:
    servers: []
    get:
      summary: Proxy GET requests to Terralist
      description: Proxies GET requests to the Terralist private Terraform registry
      operationId: terralist-proxy-get
      x-openapi-backend-squash: true
      tags:
        - Terralist
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to Terralist
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from Terralist
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    post:
      summary: Proxy POST requests to Terralist
      description: Proxies POST requests to the Terralist private Terraform registry
      operationId: terralist-proxy-post
      x-openapi-backend-squash: true
      tags:
        - Terralist
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to Terralist
      requestBody:
        content:
          application/json:
            schema:
              type: object
          application/octet-stream:
            schema:
              type: string
              format: binary
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from Terralist
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    put:
      summary: Proxy PUT requests to Terralist
      description: Proxies PUT requests to the Terralist private Terraform registry
      operationId: terralist-proxy-put
      x-openapi-backend-squash: true
      tags:
        - Terralist
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to Terralist
      requestBody:
        content:
          application/json:
            schema:
              type: object
          application/octet-stream:
            schema:
              type: string
              format: binary
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from Terralist
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
    delete:
      summary: Proxy DELETE requests to Terralist
      description: Proxies DELETE requests to the Terralist private Terraform registry
      operationId: terralist-proxy-delete
      x-openapi-backend-squash: true
      tags:
        - Terralist
      parameters:
        - in: path
          name: path
          required: true
          schema:
            type: string
          description: The path to proxy to Terralist
      security:
        - JWTAuth: []
      responses:
        '200':
          description: Successful response from Terralist
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
components:
  securitySchemes:
    JWTAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT authentication token
    BasicAuth:
      type: http
      scheme: basic
      description: Basic authentication
    AdminOnly:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT authentication token with admin privileges
    RunnerPoolAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for runner authentication
  parameters:
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    PageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 25
    Offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      description: The offset of the items to return
    SearchQuery:
      name: searchQuery
      in: query
      required: false
      schema:
        type: string
        description: Search query
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the workspace
    TaskId:
      name: taskId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the task
    RunId:
      name: runId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the run
    AccountId:
      name: accountId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the account
    VcsId:
      name: vcsId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the VCS integration
    PoolId:
      name: poolId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the runner pool
    RunnerName:
      name: runnerName
      in: path
      required: true
      schema:
        type: string
      description: Name of the runner
  schemas:
    CommonSearchOptions:
      type: object
      properties:
        projection:
          type: array
          items:
            type: string
          description: Fields to include in the response
        searchValue:
          type: string
          description: Value to search for across searchable fields
    RunnerTypeEnum:
      type: string
      enum:
        - github-actions
        - gitlab-pipelines
        - bitbucket-pipelines
        - azure-pipelines
        - jenkins
        - semaphore
        - atlantis
        - env0
        - firefly
        - unrecognized
      description: The type of CI/CD runner or pipeline system
      example: github-actions
    WorkspaceRunStatusEnum:
      type: string
      enum:
        - pending
        - running
        - success
        - failed
        - canceled
        - initializing
        - queued
        - planning
        - planning_destroy
        - applying
        - destroying
        - ready_for_apply
        - ready_for_destroy
        - destroyed
        - destroy_plan_completed
        - destroy_plan_failed
        - destroy_failed
        - discarded
        - canceling_init
        - canceling_plan
        - canceling_planning_destroy
        - canceling_apply
        - canceling_destroy
        - canceled_init
        - canceled_plan
        - canceled_planning_destroy
        - canceled_apply
        - canceled_destroy
        - init_error
        - plan_success
        - plan_error
        - apply_error
        - apply_success
        - blocked
        - Acknowledged
        - plan_no_changes
        - apply_no_changes
        - runner_failure
      description: The status of a workspace run
      example: plan_success
    VcsTypeEnum:
      type: string
      enum:
        - github
        - gitlab
        - bitbucket
        - codecommit
        - azuredevops
      description: The type of version control system
      example: github
    WorkspaceFilters:
      type: object
      description: Filters for workspaces
      properties:
        workspaceName:
          type: array
          items:
            type: string
            description: Name of the workspace
            example: production-infra
          description: Filter by workspace name
        repositories:
          type: array
          items:
            type: string
            description: Repository associated with the workspace
            example: org/repo-name
          description: Filter by repositories
        ciTool:
          type: array
          items:
            $ref: '#/components/schemas/RunnerTypeEnum'
          description: Filter by CI tool
        labels:
          type: array
          items:
            type: string
          description: Filter by labels
        status:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceRunStatusEnum'
          description: Filter by last run status
        isManagedWorkflow:
          type: boolean
          description: Filter by whether the workflow is managed
        vcsType:
          type: array
          items:
            $ref: '#/components/schemas/VcsTypeEnum'
          description: Filter by version control system type
        poolId:
          type: array
          items:
            type: string
            format: uuid
            description: UUID of the runner pool
            example: 123e4567-e89b-12d3-a456-426614174000
          description: Filter by runner pool ID
    SortConfig:
      type: object
      properties:
        order:
          type: integer
          enum:
            - -1
            - 1
          description: Sort order (-1 for descending, 1 for ascending)
    WorkspaceSortField:
      type: object
      properties:
        lastRunTime:
          $ref: '#/components/schemas/SortConfig'
        workspaceName:
          $ref: '#/components/schemas/SortConfig'
        repository:
          $ref: '#/components/schemas/SortConfig'
        terraformVersion:
          $ref: '#/components/schemas/SortConfig'
        lastRunStatus:
          $ref: '#/components/schemas/SortConfig'
        ciTool:
          $ref: '#/components/schemas/SortConfig'
        runs:
          $ref: '#/components/schemas/SortConfig'
      additionalProperties: false
      minProperties: 1
      maxProperties: 1
    ListWorkspacesRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/CommonSearchOptions'
        - type: object
          properties:
            filters:
              type: object
              allOf:
                - $ref: '#/components/schemas/WorkspaceFilters'
                - type: object
                  properties:
                    $or:
                      $ref: '#/components/schemas/WorkspaceFilters'
            sort:
              $ref: '#/components/schemas/WorkspaceSortField'
    BaseEntity:
      type: object
      description: Base entity with common fields
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: Unique identifier
          example: 507f1f77bcf86cd799439011
        accountId:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: Unique identifier of the associated account
          example: 507f1f77bcf86cd799439011
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the entity was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the entity was last updated
    Workspace:
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          properties:
            accountId:
              type: string
              description: Account ID
              example: 507f1f77bcf86cd799439011
            workspaceId:
              type: string
              description: Workspace ID
              example: 507f1f77bcf86cd799439012
            workspaceName:
              type: string
              description: Name of the workspace
              example: production-infra
            repo:
              type: string
              description: Repository name
              example: org/repo-name
            repoUrl:
              type: string
              description: Repository URL
              example: https://github.com/org/repo-name
            vcsType:
              $ref: '#/components/schemas/VcsTypeEnum'
            runnerType:
              $ref: '#/components/schemas/RunnerTypeEnum'
            lastRunStatus:
              $ref: '#/components/schemas/WorkspaceRunStatusEnum'
            lastApplyTime:
              type: string
              format: date-time
              description: Timestamp of the last apply
            lastPlanTime:
              type: string
              format: date-time
              description: Timestamp of the last plan
            lastRunTime:
              type: string
              format: date-time
              description: Timestamp of the last run
            iacType:
              type: string
              description: Type of Infrastructure as Code
              example: terraform
            iacTypeVersion:
              type: string
              description: Version of the IaC tool
              example: 1.0.11
            backendSummary:
              type: object
              description: Summary of backend configuration
              properties:
                backendType:
                  type: string
                  description: Type of backend
                  example: s3
                backendConfig:
                  type: object
                  additionalProperties: true
                  description: Backend configuration
                  example:
                    bucket: terraform-state
                    key: prod/terraform.tfstate
                iacStackId:
                  type: string
                  description: ID of the IaC stack
                  example: stack-123
                managedResourceCount:
                  type: integer
                  description: Number of managed resources
                  example: 42
            labels:
              type: array
              items:
                type: string
              description: Labels associated with the workspace
              example:
                - prod
                - terraform
            poolId:
              type: string
              format: uuid
              description: UUID of the runner pool associated with the workspace
              example: 123e4567-e89b-12d3-a456-426614174000
            runsCount:
              type: integer
              description: Number of runs
              example: 5
            isWorkflowManaged:
              type: boolean
              description: Whether the workflow is managed by the system
              example: true
            guardrails:
              type: array
              items:
                type: string
              description: List of guardrails
              example:
                - cost
                - security
            oidcAuthentication:
              type: boolean
              nullable: true
              description: >-
                OIDC authentication setting. If null, inherits from parent
                project.
            isRemote:
              type: boolean
              description: >-
                Whether this workspace uses the internal remote backend for
                state management
            createdAt:
              type: string
              format: date-time
              description: Timestamp when the workspace was created
            updatedAt:
              type: string
              format: date-time
              description: Timestamp when the workspace was last updated
    ListWorkspacesResponse:
      type: array
      items:
        $ref: '#/components/schemas/Workspace'
    DeleteWorkspaceResponse:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: integer
          enum:
            - 200
        data:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              example: Workspace deleted successfully
    UpdateWorkspaceLabelsRequest:
      type: object
      required:
        - labels
      properties:
        labels:
          type: array
          items:
            type: string
          description: List of labels to assign to the workspace
    UpdateWorkspaceLabelsResponse:
      type: object
      required:
        - id
        - workspaceName
        - labels
        - updatedAt
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          example: 507f1f77bcf86cd799439015
        workspaceName:
          type: string
          example: production-infra
        labels:
          type: array
          items:
            type: string
          example:
            - production
            - terraform
            - critical
        updatedAt:
          type: string
          format: date-time
    WorkspaceRunFilters:
      type: object
      description: Filters for workspace runs
      properties:
        runId:
          type: array
          items:
            type: string
            description: Unique identifier for the run
            example: run-123456
          description: Filter by Run ID
        runName:
          type: array
          items:
            type: string
            description: Name of the run
            example: Deploy to Production
          description: Filter by Run Name
        status:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceRunStatusEnum'
          description: Filter by Run Status
        pullRequestUrl:
          type: array
          items:
            type: string
            description: URL of the associated pull request
            example: https://github.com/org/repo/pull/123
          description: Filter by Pull Request URL
        branch:
          type: array
          items:
            type: string
            description: Branch associated with the run
            example: main
          description: Filter by Branch
        commitId:
          type: array
          items:
            type: string
            description: ID of the commit
            example: abc123def456
          description: Filter by Commit ID
        ciTool:
          type: array
          items:
            $ref: '#/components/schemas/RunnerTypeEnum'
          description: Filter by CI Tool
        buildId:
          type: array
          items:
            type: string
            description: ID of the build
            example: build-789012
          description: Filter by Build ID
        buildName:
          type: array
          items:
            type: string
            description: Name of the build
            example: CI Build
          description: Filter by Build Name
        buildUrl:
          type: array
          items:
            type: string
            description: URL of the build
            example: https://github.com/org/repo/actions/runs/789012
          description: Filter by Build URL
        vcsType:
          type: array
          items:
            $ref: '#/components/schemas/VcsTypeEnum'
          description: Filter by VCS Type
        repository:
          type: array
          items:
            type: string
            description: Repository associated with the run
            example: org/repo
          description: Filter by repository
        repositoryUrl:
          type: array
          items:
            type: string
            description: URL of the repository
            example: https://github.com/org/repo
          description: Filter by repository URL
        title:
          type: array
          items:
            type: string
            description: Title of the run
            example: Update infrastructure for new feature
          description: Filter by Title
        createdAt:
          type: string
          format: date-time
          description: Filter by Creation Date
        updatedAt:
          type: string
          format: date-time
          description: Filter by Update Date
    WorkspaceRunSortField:
      type: object
      properties:
        updatedAt:
          $ref: '#/components/schemas/SortConfig'
        title:
          $ref: '#/components/schemas/SortConfig'
        commitId:
          $ref: '#/components/schemas/SortConfig'
        branch:
          $ref: '#/components/schemas/SortConfig'
        status:
          $ref: '#/components/schemas/SortConfig'
        ciTool:
          $ref: '#/components/schemas/SortConfig'
        vcsType:
          $ref: '#/components/schemas/SortConfig'
        repository:
          $ref: '#/components/schemas/SortConfig'
      additionalProperties: false
      minProperties: 1
      maxProperties: 1
    ListWorkspaceRunsRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/CommonSearchOptions'
        - type: object
          properties:
            filters:
              type: object
              allOf:
                - $ref: '#/components/schemas/WorkspaceRunFilters'
                - type: object
                  properties:
                    $or:
                      $ref: '#/components/schemas/WorkspaceRunFilters'
            sort:
              $ref: '#/components/schemas/WorkspaceRunSortField'
    TaskTypeEnum:
      type: string
      enum:
        - post-plan
        - post-apply
      description: The type of task in the workflow
      example: post-plan
    GuardrailsSummary:
      type: object
      description: Summary of guardrail results
      properties:
        total:
          type: integer
          description: Total number of guardrails
          example: 10
        passed:
          type: integer
          description: Number of passed guardrails
          example: 8
        failed:
          type: integer
          description: Number of failed guardrails
          example: 2
        violations:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Violation ID
                example: v1
              severity:
                type: string
                enum:
                  - high
                  - medium
                  - low
                description: Severity of the violation
                example: high
              message:
                type: string
                description: Violation message
                example: Resource does not have required tags
    BackendSummary:
      type: object
      description: Summary of backend configuration
      properties:
        type:
          type: string
          enum:
            - s3
            - azurerm
            - gcs
            - consul
          description: Type of backend
          example: s3
        config:
          type: object
          additionalProperties: true
          description: Backend configuration
          example:
            bucket: terraform-state
            key: prod/terraform.tfstate
        resources:
          type: integer
          description: Number of resources
          example: 42
    ChangedFilesCodeSummary:
      type: object
      description: Summary of changed code files
      properties:
        total:
          type: integer
          description: Total number of files
          example: 5
        added:
          type: integer
          description: Number of added files
          example: 2
        modified:
          type: integer
          description: Number of modified files
          example: 3
        deleted:
          type: integer
          description: Number of deleted files
          example: 0
        files:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: File path
                example: main.tf
              type:
                type: string
                enum:
                  - added
                  - modified
                  - deleted
                description: Type of change
                example: modified
    Task:
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          properties:
            contentKeys:
              type: object
              additionalProperties:
                type: string
              description: Keys for accessing content related to subtasks
            status:
              type: string
              description: Status of the task run
              example: completed
            resultStatus:
              type: string
              description: Result status of the task
              example: success
            type:
              $ref: '#/components/schemas/TaskTypeEnum'
            guardrailsSummary:
              allOf:
                - $ref: '#/components/schemas/GuardrailsSummary'
                - type: object
                  properties:
                    description:
                      type: string
                      description: Summary of guardrail results
            backendSummary:
              allOf:
                - $ref: '#/components/schemas/BackendSummary'
                - type: object
                  properties:
                    description:
                      type: string
                      description: Summary of backend configuration
            changedFilesCodeSummary:
              allOf:
                - $ref: '#/components/schemas/ChangedFilesCodeSummary'
                - type: object
                  properties:
                    description:
                      type: string
                      description: Summary of changed code files
            vcsType:
              $ref: '#/components/schemas/VcsTypeEnum'
            runnerType:
              $ref: '#/components/schemas/RunnerTypeEnum'
    WorkspaceRunError:
      type: object
      properties:
        type:
          type: string
        description:
          type: string
        activity:
          type: string
        temporalWorkflowId:
          type: string
        cause:
          type: string
      required:
        - type
        - description
        - temporalWorkflowId
    WorkspaceRun:
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          properties:
            accountId:
              type: string
              pattern: ^[0-9a-fA-F]{24}$
              description: Unique identifier of the account
              example: 507f1f77bcf86cd799439011
            workspaceId:
              type: string
              description: Unique identifier of the associated workspace
              example: 507f1f77bcf86cd799439012
            workspaceName:
              type: string
              description: Name of the workspace
              example: production-infra
            runId:
              type: string
              description: Unique identifier for the run
              example: run-123456
            runName:
              type: string
              description: Name of the run
              example: Deploy to Production
            status:
              $ref: '#/components/schemas/WorkspaceRunStatusEnum'
            pullRequestId:
              type: string
              description: ID of the associated pull request
              example: '123'
            pullRequestUrl:
              type: string
              description: URL of the associated pull request
              example: https://github.com/org/repo/pull/123
            branch:
              type: string
              description: Branch associated with the run
              example: main
            commitId:
              type: string
              description: ID of the commit
              example: abc123def456
            commitUrl:
              type: string
              description: URL of the commit
              example: https://github.com/org/repo/commit/abc123def456
            runnerType:
              $ref: '#/components/schemas/RunnerTypeEnum'
            buildId:
              type: string
              description: ID of the build
              example: build-789012
            buildUrl:
              type: string
              description: URL of the build
              example: https://github.com/org/repo/actions/runs/789012
            buildName:
              type: string
              description: Name of the build
              example: CI Build
            vcsType:
              $ref: '#/components/schemas/VcsTypeEnum'
            repo:
              type: string
              description: Repository associated with the run
              example: org/repo
            repoUrl:
              type: string
              description: URL of the repository
              example: https://github.com/org/repo
            ownerSummary:
              type: object
              description: Summary of the owner of the run
              properties:
                email:
                  type: string
                  description: Email of the owner
                  example: john.doe@example.com
                name:
                  type: string
                  description: Name of the owner
                  example: John Doe
                initials:
                  type: string
                  description: Initials of the owner
                  example: JD
                customColor:
                  type: string
                  description: Custom color for the owner
                  example: '#00000F'
            title:
              type: string
              description: Title of the run
              example: Update infrastructure for new feature
            terraformVersion:
              type: string
              description: Version of Terraform used
              example: 1.0.11
            iacType:
              type: string
              enum:
                - terraform
                - opentofu
                - k8s
              description: Type of Infrastructure as Code
              example: terraform
            backendSummary:
              type: object
              description: Summary of backend configuration
              properties:
                backendType:
                  type: string
                  description: Type of backend
                  example: s3
                backendConfig:
                  type: object
                  additionalProperties: true
                  description: Backend configuration
                iacStackId:
                  type: string
                  description: ID of the IaC stack
                managedResourceCount:
                  type: integer
                  description: Number of managed resources
            planTaskId:
              type: string
              pattern: ^[0-9a-fA-F]{24}$
              description: Unique identifier of the plan task
              example: 507f1f77bcf86cd799439013
            applyTaskId:
              type: string
              pattern: ^[0-9a-fA-F]{24}$
              description: Unique identifier of the apply task
              example: 507f1f77bcf86cd799439014
            plan:
              type: array
              description: Plan tasks
              items:
                $ref: '#/components/schemas/Task'
            apply:
              type: array
              description: Apply tasks
              items:
                $ref: '#/components/schemas/Task'
            error:
              $ref: '#/components/schemas/WorkspaceRunError'
    ListWorkspaceRunsResponse:
      type: array
      items:
        $ref: '#/components/schemas/WorkspaceRun'
    ResourceActionEnum:
      type: string
      enum:
        - no-op
        - create
        - read
        - update
        - delete
      description: The type of action performed on a resource
      example: create
    ResourceFilters:
      type: object
      description: Filters for resources
      properties:
        action:
          allOf:
            - type: array
              items:
                $ref: '#/components/schemas/ResourceActionEnum'
            - description: Filter by Resource Action
        hasDiagnostics:
          type: boolean
          description: Filter Resources that have Diagnostics
        taskType:
          allOf:
            - type: array
              items:
                $ref: '#/components/schemas/TaskTypeEnum'
            - description: Filter by Task Type
        resourceId:
          allOf:
            - type: array
              items:
                type: string
                description: ID of the resource
                example: aws_s3_bucket.logs
            - description: Filter by Resource ID
        providerName:
          type: array
          items:
            type: string
            description: Name of the provider
            example: aws
          description: Filter by Provider Name
        isDrifted:
          type: boolean
          description: Whether the resource is drifted
          example: false
    ResourceSortField:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/SortConfig'
        mode:
          $ref: '#/components/schemas/SortConfig'
        action:
          $ref: '#/components/schemas/SortConfig'
        isDrifted:
          $ref: '#/components/schemas/SortConfig'
        type:
          $ref: '#/components/schemas/SortConfig'
        taskType:
          $ref: '#/components/schemas/SortConfig'
        providerName:
          $ref: '#/components/schemas/SortConfig'
        updatedAt:
          $ref: '#/components/schemas/SortConfig'
        createdAt:
          $ref: '#/components/schemas/SortConfig'
      additionalProperties: false
      minProperties: 1
      maxProperties: 1
    ListRunResourcesRequest:
      type: object
      required:
        - mode
      allOf:
        - $ref: '#/components/schemas/CommonSearchOptions'
        - type: object
          properties:
            mode:
              type: string
              enum:
                - table
                - graph
                - summary
                - costPolicy
              description: The mode to display the resources in
            filters:
              type: object
              allOf:
                - $ref: '#/components/schemas/ResourceFilters'
                - type: object
                  properties:
                    $or:
                      $ref: '#/components/schemas/ResourceFilters'
            sort:
              $ref: '#/components/schemas/ResourceSortField'
    BaseResource:
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          properties:
            taskId:
              type: string
              pattern: ^[0-9a-fA-F]{24}$
              description: Unique identifier of the associated task
              example: 507f1f77bcf86cd799439013
            name:
              type: string
              description: Name of the resource
              example: aws_instance.example
            type:
              type: string
              description: Type of the resource
              example: aws_instance
            mode:
              type: string
              enum:
                - managed
                - data
              description: Mode of the resource
              example: managed
            action:
              $ref: '#/components/schemas/ResourceActionEnum'
    DataTypeEnum:
      type: string
      enum:
        - terraform
        - k8s
        - cloudformation
        - arm
      description: The type of infrastructure data
      example: terraform
    Resource:
      allOf:
        - $ref: '#/components/schemas/BaseResource'
        - type: object
          properties:
            isDrifted:
              type: boolean
              description: Whether the resource is drifted
              example: false
            taskType:
              $ref: '#/components/schemas/TaskTypeEnum'
            dataType:
              $ref: '#/components/schemas/DataTypeEnum'
            providerName:
              type: string
              description: Name of the provider
              example: aws
            providerType:
              type: string
              description: Type of the provider
              example: aws
            providerVersion:
              type: string
              description: Version of the provider
              example: 4.0.0
    TableModeResponse:
      type: object
      required:
        - resources
      properties:
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
    SummaryModeResponse:
      type: object
      required:
        - policyData
        - costData
        - tagsData
      properties:
        policyData:
          type: object
          properties:
            HIGH:
              type: array
              items:
                type: object
                properties:
                  assetType:
                    type: string
                  reason:
                    type: string
                  resource:
                    type: object
            MEDIUM:
              type: array
              items:
                type: object
            LOW:
              type: array
              items:
                type: object
        costData:
          type: array
          items:
            type: object
        tagsData:
          type: array
          items:
            type: object
    ListRunResourcesResponse:
      type: object
      oneOf:
        - $ref: '#/components/schemas/TableModeResponse'
        - $ref: '#/components/schemas/SummaryModeResponse'
    ChangedCodeFilters:
      type: object
      description: Filters for changed code files
      properties:
        taskId:
          allOf:
            - type: array
              items:
                type: string
                pattern: ^[0-9a-fA-F]{24}$
                description: Unique identifier of the associated task
                example: 507f1f77bcf86cd799439013
            - description: Filter by task ID
        suffix:
          allOf:
            - type: array
              items:
                type: string
                description: File extension or suffix
                example: tf
            - description: Filter by file suffix
        taskType:
          allOf:
            - type: array
              items:
                $ref: '#/components/schemas/TaskTypeEnum'
            - description: Filter by task type
        filePath:
          allOf:
            - type: array
              items:
                type: string
                description: Path to the file in the repository
                example: infrastructure/main.tf
            - description: Filter by file path (supports glob patterns)
    ChangedCodeSortField:
      type: object
      properties:
        taskType:
          $ref: '#/components/schemas/SortConfig'
        suffix:
          $ref: '#/components/schemas/SortConfig'
        updatedAt:
          $ref: '#/components/schemas/SortConfig'
      additionalProperties: false
      minProperties: 1
      maxProperties: 1
    ListRunChangedCodeRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/CommonSearchOptions'
        - type: object
          properties:
            filters:
              type: object
              allOf:
                - $ref: '#/components/schemas/ChangedCodeFilters'
                - type: object
                  properties:
                    $or:
                      $ref: '#/components/schemas/ChangedCodeFilters'
            sort:
              $ref: '#/components/schemas/ChangedCodeSortField'
    ChangedFileResponse:
      type: object
      description: Represents a file that has been changed
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: Unique identifier of the changed file
          example: 507f1f77bcf86cd799439014
        filePath:
          type: string
          description: Path to the file
          example: infrastructure/main.tf
        folderPath:
          type: string
          description: Path to the folder containing the file
          example: infrastructure
        fileSuffix:
          type: string
          description: Suffix of the file
          example: tf
        content:
          type: string
          description: Current content of the file
        changes:
          type: object
          description: Changes made to the file
          properties:
            additions:
              type: integer
              description: Number of lines added
              example: 10
            deletions:
              type: integer
              description: Number of lines deleted
              example: 5
            diff:
              type: string
              description: Diff of the changes
              example: |-
                @@ -1,5 +1,10 @@
                ...
    ListRunChangedCodeResponse:
      type: object
      description: Response containing changed files grouped by folder path
      additionalProperties:
        type: array
        description: Array of changed files in a specific folder
        items:
          $ref: '#/components/schemas/ChangedFileResponse'
      example:
        infrastructure:
          - id: 507f1f77bcf86cd799439014
            filePath: infrastructure/main.tf
            folderPath: infrastructure
            fileSuffix: tf
            changes:
              additions: 10
              deletions: 5
        modules:
          - id: 507f1f77bcf86cd799439015
            filePath: modules/network/main.tf
            folderPath: modules/network
            fileSuffix: tf
            changes:
              additions: 3
              deletions: 1
    ListWorkspaceTasksEnvironmentsResponse:
      type: array
      description: List of environment names for tasks in a workspace run
      items:
        type: string
        description: Environment name
        example: production
    GetWorkspaceTasksForEnvironmentResponse:
      type: array
      description: List of tasks for a specific environment
      items:
        $ref: '#/components/schemas/Task'
    type:
      type: string
      enum:
        - policy
        - cost
        - resource
        - tag
      description: Type of the guardrail rule
    ListGuardrailsFilters:
      type: object
      properties:
        createdBy:
          type: array
          items:
            type: string
          description: User names to filter by
          example:
            - John Doe
        type:
          type: array
          items:
            $ref: '#/components/schemas/type'
          description: Types of guardrail rules to filter
          example:
            - policy
            - cost
        labels:
          type: array
          items:
            type: string
          description: Labels to filter by
          example:
            - production
        repositories:
          type: array
          items:
            type: string
          description: Repository names to filter by
          example:
            - my-repo
        workspaces:
          type: array
          items:
            type: string
          description: Workspace names to filter by
          example:
            - my-workspace
        branches:
          type: array
          items:
            type: string
          description: Branch names to filter by
          example:
            - main
    GuardrailSortField:
      type: object
      properties:
        createdAt:
          $ref: '#/components/schemas/SortConfig'
        accountId:
          $ref: '#/components/schemas/SortConfig'
        createdBy:
          $ref: '#/components/schemas/SortConfig'
        name:
          $ref: '#/components/schemas/SortConfig'
        severity:
          $ref: '#/components/schemas/SortConfig'
      additionalProperties: false
      minProperties: 1
      maxProperties: 1
    ListGuardrailsRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/CommonSearchOptions'
        - type: object
          properties:
            filters:
              type: object
              allOf:
                - $ref: '#/components/schemas/ListGuardrailsFilters'
                - type: object
                  properties:
                    $or:
                      $ref: '#/components/schemas/ListGuardrailsFilters'
            sort:
              type: array
              maxItems: 1
              items:
                $ref: '#/components/schemas/GuardrailSortField'
    IncludeExcludeWildcard:
      type: object
      description: A pattern for including and excluding items using wildcards
      properties:
        include:
          type: array
          description: List of patterns to include
          items:
            type: string
        exclude:
          type: array
          description: List of patterns to exclude
          items:
            type: string
    GuardrailScope:
      type: object
      required:
        - workspaces
        - repositories
        - branches
        - labels
      properties:
        workspaces:
          allOf:
            - $ref: '#/components/schemas/IncludeExcludeWildcard'
            - type: object
              required:
                - include
              properties:
                include:
                  minItems: 1
        repositories:
          allOf:
            - $ref: '#/components/schemas/IncludeExcludeWildcard'
            - type: object
              required:
                - include
              properties:
                include:
                  minItems: 1
        branches:
          allOf:
            - $ref: '#/components/schemas/IncludeExcludeWildcard'
            - type: object
              required:
                - include
              properties:
                include:
                  minItems: 1
        labels:
          allOf:
            - $ref: '#/components/schemas/IncludeExcludeWildcard'
            - type: object
              required:
                - include
              properties:
                include:
                  minItems: 1
    CostCriteria:
      type: object
      oneOf:
        - required:
            - thresholdAmount
        - required:
            - thresholdPercentage
      properties:
        thresholdAmount:
          type: number
          format: float
          description: Absolute threshold amount (in USD) for cost criteria
        thresholdPercentage:
          type: number
          format: float
          description: Percentage threshold for cost criteria
    Policies:
      allOf:
        - $ref: '#/components/schemas/IncludeExcludeWildcard'
        - description: List of policies to include or exclude
    PolicyCriteria:
      type: object
      properties:
        severity:
          type: string
          description: Severity level for policy criteria
        policies:
          $ref: '#/components/schemas/Policies'
    Regions:
      allOf:
        - $ref: '#/components/schemas/IncludeExcludeWildcard'
        - description: List of regions to include or exclude
    AssetTypes:
      allOf:
        - $ref: '#/components/schemas/IncludeExcludeWildcard'
        - description: List of asset types to include or exclude
    ResourceCriteria:
      type: object
      required:
        - actions
        - regions
        - assetTypes
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ResourceActionEnum'
          minItems: 1
        regions:
          allOf:
            - $ref: '#/components/schemas/Regions'
            - type: object
              required:
                - include
              properties:
                include:
                  minItems: 1
        assetTypes:
          allOf:
            - $ref: '#/components/schemas/AssetTypes'
            - type: object
              required:
                - include
              properties:
                include:
                  minItems: 1
        specificResources:
          type: array
          items:
            type: string
          description: List of specific resources
    AnyTagsCriteria:
      type: object
      required:
        - tagEnforcementMode
      properties:
        tagEnforcementMode:
          type: string
          enum:
            - anyTags
          description: Mode of tag enforcement
      additionalProperties: false
    RequiredTagsCriteria:
      type: object
      required:
        - tagEnforcementMode
        - requiredTags
      properties:
        tagEnforcementMode:
          type: string
          enum:
            - requiredTags
          description: Mode of tag enforcement
        requiredTags:
          type: array
          items:
            type: string
          minItems: 1
          description: List of required tags
      additionalProperties: false
    RequiredValuesCriteria:
      type: object
      required:
        - tagEnforcementMode
        - requiredValues
      properties:
        tagEnforcementMode:
          type: string
          enum:
            - requiredValues
          description: Mode of tag enforcement
        requiredValues:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          minProperties: 1
          description: Map of tag keys to required values
      additionalProperties: false
    TagCriteria:
      oneOf:
        - $ref: '#/components/schemas/AnyTagsCriteria'
        - $ref: '#/components/schemas/RequiredTagsCriteria'
        - $ref: '#/components/schemas/RequiredValuesCriteria'
    Criteria:
      type: object
      minProperties: 1
      properties:
        cost:
          $ref: '#/components/schemas/CostCriteria'
        policy:
          $ref: '#/components/schemas/PolicyCriteria'
        resource:
          $ref: '#/components/schemas/ResourceCriteria'
        tag:
          $ref: '#/components/schemas/TagCriteria'
    GuardrailRule:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          readOnly: true
          description: Unique identifier of the guardrail rule
          example: 507f1f77bcf86cd799439012
        accountId:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: Unique identifier of the associated account
          example: 507f1f77bcf86cd799439012
        createdBy:
          type: string
          minLength: 1
          description: Name of the user who created the rule
          example: John Doe
        name:
          type: string
          minLength: 1
          description: Name of the guardrail rule
        type:
          type: string
          enum:
            - policy
            - cost
            - resource
            - tag
          description: Type of the guardrail rule
        scope:
          allOf:
            - $ref: '#/components/schemas/GuardrailScope'
            - description: Scope of the guardrail rule
        criteria:
          $ref: '#/components/schemas/Criteria'
        isEnabled:
          type: boolean
          description: Whether the rule is enabled
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the rule was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the rule was last updated
        notificationId:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: Unique identifier of the associated notification configuration
          example: 507f1f77bcf86cd799439012
        severity:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
          description: Severity level of the guardrail rule
        enforceOnNoOp:
          type: boolean
          description: Whether to enforce the rule on no-op assets
    CreateGuardrailRequest:
      allOf:
        - $ref: '#/components/schemas/GuardrailRule'
        - type: object
          required:
            - name
            - isEnabled
            - type
            - createdBy
            - severity
            - scope
            - criteria
    CreateGuardrailResponse:
      type: object
      required:
        - ruleId
        - notificationId
      properties:
        ruleId:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: Unique identifier of the created rule
          example: 507f1f77bcf86cd799439011
        notificationId:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: Unique identifier of the created notification
          example: 507f1f77bcf86cd799439012
    DeleteGuardrailResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: integer
          enum:
            - 200
          description: HTTP Status Code
          example: 200
        message:
          type: string
          description: Success message
          example: Guardrail rule and notification deleted successfully
    UpdateGuardrailRequest:
      allOf:
        - $ref: '#/components/schemas/GuardrailRule'
        - type: object
          required:
            - name
            - type
            - scope
            - criteria
            - isEnabled
    UpdateGuardrailResponse:
      type: object
      required:
        - id
        - name
        - enabled
        - updatedAt
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: Unique identifier of the updated rule
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the Guardrail Rule
          example: Enforce S3 Encryption
        enabled:
          type: boolean
          description: Whether the Rule is Active
          example: true
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the Last Update
          example: '2024-11-11T10:00:00Z'
    StateVersion:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for a state version
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        serial:
          type: integer
          format: int64
          description: State serial number (monotonically increasing)
          example: 42
        terraformVersion:
          type: string
          nullable: true
          description: Terraform version used to create this state version
          example: 1.5.0
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the state version was created
          example: '2024-01-15T10:30:00Z'
        createdBy:
          type: string
          nullable: true
          description: Owner/user who created this state version
          example: user@example.com
        downloadUrl:
          type: string
          format: uri
          nullable: true
          description: >-
            Presigned URL for downloading the state file. May be null if the
            state file is not available.
          example: https://s3.amazonaws.com/bucket/path/to/state?X-Amz-Algorithm=...
    AllVcsResponse:
      type: object
      properties:
        github:
          type: array
          items:
            $ref: '#/components/schemas/VcsIntegration'
        gitlab:
          type: array
          items:
            $ref: '#/components/schemas/VcsIntegration'
        bitbucket:
          type: array
          items:
            $ref: '#/components/schemas/VcsIntegration'
        bitbucketdc:
          type: array
          items:
            $ref: '#/components/schemas/VcsIntegration'
        codecommit:
          type: array
          items:
            $ref: '#/components/schemas/VcsIntegration'
        azuredevops:
          type: array
          items:
            $ref: '#/components/schemas/VcsIntegration'
    VcsIntegration:
      type: object
      properties:
        id:
          type: string
          description: Integration ID
        name:
          type: string
          description: Integration name
        type:
          type: string
          description: VCS provider type
        domain:
          type: string
          description: VCS domain (for self-hosted instances)
        isEnabled:
          type: boolean
          description: Whether the integration is enabled
        syncStatus:
          type: string
          description: Current sync status
    Repository:
      type: object
      properties:
        id:
          type: string
          description: Repository ID
        name:
          type: string
          description: Repository name
        fullName:
          type: string
          description: Full repository name (org/repo)
        private:
          type: boolean
          description: Whether the repository is private
        url:
          type: string
          description: Repository URL
    GetBranchesRequest:
      type: object
      required:
        - id
        - repoFullName
      properties:
        id:
          type: string
          description: VCS integration ID
        repoFullName:
          type: string
          description: Full repository name (org/repo)
    Branch:
      type: object
      properties:
        name:
          type: string
          description: Branch name
    DirectoryNode:
      type: object
      description: A node in the directory tree representing either a file or directory
      properties:
        name:
          type: string
          description: Name of the file or directory
        path:
          type: string
          description: Full path from repository root
        type:
          type: string
          enum:
            - file
            - directory
          description: Type of the node (file or directory)
        children:
          type: array
          items:
            $ref: '#/components/schemas/DirectoryNode'
          description: Child nodes (only present for directories)
    CloneUrlRequest:
      type: object
      required:
        - vcsId
        - repository
      properties:
        vcsId:
          type: string
          description: The VCS integration ID
          example: 66169dfaf49923c0aab04510
        repository:
          type: string
          description: |
            Repository path. Format varies by provider:
            - GitHub/GitLab/Bitbucket: org/repo
            - Bitbucket DC: project/repo
            - Azure DevOps: org/project/repo
            - CodeCommit: repo-name
          example: my-org/my-repo
        region:
          type: string
          description: AWS region (required only for CodeCommit)
          example: us-east-1
    CloneUrlResponse:
      type: object
      required:
        - cloneUrl
        - vcsType
      properties:
        cloneUrl:
          type: string
          description: The authenticated git clone URL
          example: https://ghp_xxxx@github.com/my-org/my-repo.git
        vcsType:
          type: string
          enum:
            - github
            - gitlab
            - bitbucket
            - bitbucketdc
            - azuredevops
            - codecommit
          description: The type of VCS provider
        credentials:
          $ref: '#/components/schemas/CodeCommitCredentials'
    CodeCommitCredentials:
      type: object
      description: >-
        AWS credentials for CodeCommit (only returned for CodeCommit
        integrations)
      properties:
        accessKey:
          type: string
          description: AWS access key ID
        secretKey:
          type: string
          description: AWS secret access key
        sessionToken:
          type: string
          description: AWS session token
        region:
          type: string
          description: AWS region
    ImportVcsModuleRequest:
      type: object
      required:
        - name
        - providerType
        - version
        - vcsId
        - repo
        - branch
      properties:
        name:
          type: string
          description: Module name in registry path
          example: aws-vpc
        providerType:
          type: string
          description: Terraform provider type
          example: aws
        version:
          type: string
          description: Module version in valid semver format
          example: 1.0.0
        vcsId:
          type: string
          description: VCS integration ID
          example: 66169dfaf49923c0aab04510
        repo:
          type: string
          description: GitHub repoFullName (owner/repo)
          example: infralight/infrastructure
        branch:
          type: string
          description: Branch name to import from
          example: main
        path:
          type: string
          description: >-
            Optional path to module directory in repository. Defaults to
            repository root.
          example: modules/github/repo
    ImportVcsModuleResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: Module imported successfully
    ImportVcsModuleErrorCategory:
      type: string
      enum:
        - VALIDATION_ERROR
        - VCS_INTEGRATION_NOT_FOUND
        - VCS_CREDENTIALS_FETCH_FAILED
        - MODULE_DOWNLOAD_FAILED
        - REGISTRY_UNAVAILABLE
        - INTERNAL_ERROR
    ImportVcsModuleErrorResponse:
      type: object
      required:
        - errorCategory
        - message
      properties:
        errorCategory:
          $ref: '#/components/schemas/ImportVcsModuleErrorCategory'
        message:
          type: string
          example: Module download failed while importing from repository
    ProjectProperties:
      type: object
      properties:
        name:
          type: string
          description: Name of the project
        description:
          type: string
          description: Description of the project
        labels:
          type: array
          items:
            type: string
          description: Labels to assign to the project
        poolId:
          type: string
          format: uuid
          description: UUID of the runner pool associated with the project
          example: 123e4567-e89b-12d3-a456-426614174000
        cronExecutionPattern:
          type: string
          description: Cron pattern for scheduled executions
        variables:
          type: array
          items:
            $ref: '#/components/schemas/Variable'
          description: Variables associated with the project
        oidcAuthentication:
          type: boolean
          nullable: true
          description: OIDC authentication setting.
    CreateProjectRequest:
      allOf:
        - $ref: '#/components/schemas/ProjectProperties'
        - type: object
          required:
            - name
          properties:
            parentId:
              type: string
              description: >-
                ID of the parent project. If missing or empty, the server will
                attempt to create a root project.
    UpdateProjectRequest:
      allOf:
        - $ref: '#/components/schemas/ProjectProperties'
    Project:
      allOf:
        - $ref: '#/components/schemas/ProjectProperties'
        - type: object
          properties:
            id:
              type: string
              description: Unique identifier for the project
            accountId:
              type: string
              description: ID of the account the project belongs to
            membersCount:
              type: integer
              minimum: 0
              description: Number of members assigned to the project
            workspaceCount:
              type: integer
              minimum: 0
              description: Number of workspaces in the project
            parentId:
              type: string
              description: ID of the parent project (for nested projects)
    ProjectTree:
      type: object
      properties:
        data:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Project'
              - type: object
                properties:
                  hasChildren:
                    type: boolean
                    description: Indicates if the project has child projects
                  children:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  ancestors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                    description: Array of parent projects up to the root
    Member:
      type: object
      required:
        - userId
        - role
      properties:
        userId:
          type: string
          description: ID of the user
        role:
          type: string
          enum:
            - admin
            - member
          description: Role of the user in the project
    Variable:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
        sensitivity:
          type: string
          enum:
            - string
            - secret
        destination:
          type: string
          enum:
            - env
            - iac
    IacProvisioner:
      type: object
      description: Infrastructure as Code provisioner configuration
      properties:
        type:
          type: string
          enum:
            - terraform
            - opentofu
          description: Type of IaC provisioner
        version:
          type: string
          description: Version of the provisioner
      required:
        - type
        - version
    MultiEnvProvisioner:
      type: object
      description: Multi-environment provisioner configuration
      required:
        - type
        - version
      properties:
        type:
          type: string
          enum:
            - terragrunt
          description: Type of multi-environment provisioner
        version:
          type: string
          description: >-
            Version of the multi-environment provisioner. Should be a valid
            semver when provided.
        applyAll:
          type: boolean
          default: false
          description: Whether to apply all environments or not
        stopOnError:
          type: boolean
          default: false
          description: Whether to stop on error during multi-environment provisioning
    WorkspaceTriggerConfig:
      type: object
      properties:
        runOnPullRequest:
          type: boolean
          default: true
        runOnPush:
          type: boolean
          default: true
        autoApply:
          type: boolean
          default: false
    RunnersWorkspace:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the workspace
        name:
          type: string
          description: Name of the workspace
        description:
          type: string
          description: Description of the workspace
        accountId:
          type: string
          description: ID of the account the workspace belongs to
        repository:
          type: string
          description: Repository URL for the workspace
        workingDirectory:
          type: string
          description: Working directory within the repository
        vcsIntegrationId:
          type: string
          description: ID of the VCS integration
        vcs:
          type: string
          description: VCS type (e.g., github, gitlab)
        defaultBranch:
          type: string
          description: Default branch for the workspace
        cronExecutionPattern:
          type: string
          description: Cron pattern for scheduled executions
        iacProvisioner:
          $ref: '#/components/schemas/IacProvisioner'
        multiEnvProvisioner:
          $ref: '#/components/schemas/MultiEnvProvisioner'
        labels:
          type: array
          items:
            type: string
          description: Labels assigned to the workspace
        poolId:
          type: string
          description: ID of the runner pool associated with the workspace
          example: 123e4567-e89b-12d3-a456-426614174000
        triggerConfig:
          $ref: '#/components/schemas/WorkspaceTriggerConfig'
        oidcAuthentication:
          type: boolean
          nullable: true
          description: OIDC authentication setting. If null, inherits from parent project.
        isRemote:
          type: boolean
          description: >-
            Whether this workspace uses the internal remote backend for state
            management
      required:
        - name
        - repository
        - vcsIntegrationId
        - vcs
        - defaultBranch
        - iacProvisioner
    VariableWithOrigin:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
        sensitivity:
          type: string
          enum:
            - string
            - secret
        destination:
          type: string
          enum:
            - env
            - iac
        origin:
          $ref: '#/components/schemas/VariableOrigin'
    VariableData:
      type: object
      required:
        - key
      properties:
        key:
          type: string
        value:
          type: string
        sensitivity:
          type: string
          enum:
            - string
            - secret
        destination:
          type: string
          enum:
            - env
            - iac
        origin:
          type: string
          enum:
            - project
            - workspace
            - variableSet
    UpsertProjectVariablesRequest:
      type: object
      required:
        - variables
      properties:
        variables:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Variable'
    DeleteProjectVariablesRequest:
      type: object
      required:
        - variableKeys
      properties:
        variableKeys:
          type: array
          minItems: 1
          items:
            type: string
          description: Array of variable keys to delete
    VariableOrigin:
      type: object
      required:
        - type
        - variableSetId
      properties:
        type:
          type: string
          enum:
            - project
            - workspace
            - variable_set
        fullName:
          type: string
        fullId:
          type: string
        variableSetFullName:
          type: string
        variableSetFullId:
          type: string
        consumerType:
          type: string
          enum:
            - project
            - workspace
        projectDepth:
          type: integer
        variableSetDepth:
          type: integer
        variableSetId:
          type: string
    UpsertVariablesRequest:
      type: object
      required:
        - variables
      properties:
        variables:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              variableId:
                type: string
                description: >-
                  Optional variable ID. If provided, updates existing variable;
                  if not, creates new variable
              variableData:
                $ref: '#/components/schemas/VariableData'
            required:
              - variableData
    DeleteVariablesRequest:
      type: object
      required:
        - variableIds
      properties:
        variableIds:
          type: array
          minItems: 1
          items:
            type: string
          description: Array of variable IDs to delete
    CreateVariableSetRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the variable set
        description:
          type: string
          description: Description of the variable set
        labels:
          type: array
          items:
            type: string
          description: Labels to assign to the variable set
        parents:
          type: array
          items:
            type: string
          description: Parent variable set IDs
        variables:
          type: array
          items:
            $ref: '#/components/schemas/Variable'
          description: Initial variables to create in the variable set
    UpdateVariableSetRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the variable set
        description:
          type: string
          description: Description of the variable set
        labels:
          type: array
          items:
            type: string
          description: Labels to assign to the variable set
        parents:
          type: array
          items:
            type: string
          description: Parent variable set IDs
        variables:
          type: array
          items:
            $ref: '#/components/schemas/Variable'
          description: Variables in the variable set
    CreateVariableSetResponse:
      type: object
      properties:
        variableSetId:
          type: string
          description: ID of the created variable set
    UpsertVariableSetVariablesRequest:
      type: object
      required:
        - variables
      properties:
        variables:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Variable'
          description: Variables to upsert in the variable set
    VariableSet:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the variable set
        version:
          type: integer
          description: Version number of the variable set
        name:
          type: string
          description: Name of the variable set
        description:
          type: string
          description: Description of the variable set
        labels:
          type: array
          items:
            type: string
          description: Labels assigned to the variable set
        parents:
          type: array
          items:
            type: string
          description: Parent variable set IDs
        variables:
          type: array
          items:
            $ref: '#/components/schemas/Variable'
          description: Variables in the variable set
        descendants:
          type: array
          items:
            $ref: '#/components/schemas/VariableSetDescendant'
          description: Descendant variable sets with only id and name
        consumers:
          $ref: '#/components/schemas/VariableSetConsumers'
    VariableSetDescendant:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the descendant
        name:
          type: string
          description: Name of the descendant
    VariableSetConsumers:
      type: object
      properties:
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/VariableSetDescendant'
          description: Workspaces that consume this variable set (only id and name)
        projects:
          type: array
          items:
            $ref: '#/components/schemas/VariableSetDescendant'
          description: Projects that consume this variable set (only id and name)
    VariableSetWithAssociation:
      type: object
      properties:
        id:
          type: string
        version:
          type: integer
        consumable:
          type: boolean
        name:
          type: string
        labels:
          type: array
          items:
            type: string
        description:
          type: string
        parents:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
        descendants:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              parentId:
                type: string
              relativeDepth:
                type: integer
        consumers:
          type: object
          properties:
            workspaces:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  parentProjectId:
                    type: string
            projects:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  parentId:
                    type: string
                  relativeDepth:
                    type: integer
    CreateWorkspaceRequest:
      type: object
      required:
        - runnerType
        - iacType
        - workspaceName
        - vcsId
        - repo
        - defaultBranch
        - vcsType
        - workDir
        - variables
        - execution
      properties:
        runnerType:
          type: string
          description: Type of runner (e.g., firefly_runners)
          example: firefly_runners
        iacType:
          type: string
          description: Infrastructure as Code type
          example: terraform
        workspaceName:
          type: string
          description: Unique workspace name
          example: my-workspace
        description:
          type: string
          description: Workspace description
          example: Production environment workspace
        labels:
          type: array
          items:
            type: string
          description: Labels assigned to the workspace
          example:
            - production
            - terraform
        vcsId:
          type: string
          description: VCS integration ID
          example: 5fd126f5744410407fbc552f
        repo:
          type: string
          description: Repository name
          example: infralight/appiac
        defaultBranch:
          type: string
          description: Default branch
          example: main
        vcsType:
          type: string
          description: VCS type (github, gitlab, etc.)
          example: github
        workDir:
          type: string
          description: Working directory path
          example: terraform/production
        variables:
          type: array
          items:
            $ref: '#/components/schemas/Variable'
          description: Array of workspace variables
        consumedVariableSets:
          type: array
          items:
            type: string
          description: Array of variable set IDs that this workspace consumes
          example:
            - var-set-1
            - var-set-2
        execution:
          type: object
          required:
            - triggers
            - applyRule
            - terraformVersion
          properties:
            triggers:
              type: array
              items:
                type: string
              description: When to trigger runs
              example:
                - merge
            applyRule:
              type: string
              description: Apply rule (manual/auto)
              example: manual
            terraformVersion:
              type: string
              description: Terraform version
              example: 1.5.7
        project:
          type: string
          nullable: true
          description: Project ID or null for global access
          example: null
        terraformVariables:
          type: object
          description: Cleaned by deleteMockArrays
        terraformSensitiveVariables:
          type: object
          description: Cleaned by deleteMockArrays
        providersCredentials:
          type: object
          description: Cleaned by deleteMockArrays
        runnerEnvironment:
          type: object
          description: Cleaned by deleteMockArrays
        iacProvisioner:
          $ref: '#/components/schemas/IacProvisioner'
        multiEnvProvisioner:
          $ref: '#/components/schemas/MultiEnvProvisioner'
        poolId:
          type: string
          description: ID of the runner pool associated with the workspace
          example: 123e4567-e89b-12d3-a456-426614174000
        oidcAuthentication:
          type: boolean
          nullable: true
          description: OIDC authentication setting. If null, inherits from parent project.
        isRemote:
          type: boolean
          description: >-
            Whether this workspace uses the internal remote backend for state
            management
    TaskVcs:
      type: object
      description: VCS configuration for the task
      properties:
        reference:
          type: string
          description: Git reference (branch, tag, or commit)
          example: main
        type:
          type: string
          enum:
            - branch
            - tag
            - commit
          description: Type of VCS reference
      required:
        - reference
        - type
    RunTaskRequestTrigger:
      type: object
      description: Trigger information for the task
      properties:
        type:
          type: string
          enum:
            - manual
            - pull_request
            - push
            - schedule
          description: Type of trigger
          example: manual
        source:
          type: string
          enum:
            - Firefly
            - VCS
          description: Source of the trigger
          example: Firefly
      required:
        - type
        - source
    RunTaskRequest:
      type: object
      description: Request to run a task on workspace infrastructure
      properties:
        description:
          type: string
          description: Optional description for the task
          example: Running infrastructure task
        vcs:
          $ref: '#/components/schemas/TaskVcs'
        trigger:
          $ref: '#/components/schemas/RunTaskRequestTrigger'
        taskId:
          type: string
          description: Optional ID of the task to run
          example: task-12345
        cmdArguments:
          type: string
          description: Optional command line arguments for the task
          example: '-auto-approve'
      required:
        - vcs
        - trigger
    TaskError:
      type: object
      description: Error information if the task failed
      properties:
        type:
          type: string
          enum:
            - UNEXPECTED
          description: Type of error
        description:
          type: string
          description: Error description
    TaskTrigger:
      type: object
      description: Trigger information for the completed task
      properties:
        type:
          type: string
          enum:
            - manual
            - pull_request
            - push
            - scheduled
          description: Type of trigger
    TaskResponse:
      type: object
      description: Response from task initiation
      properties:
        accountId:
          type: string
          description: ID of the account
        id:
          type: string
          description: ID of the created task
        status:
          type: string
          enum:
            - pending
            - running
            - success
            - failed
            - canceled
          description: Current status of the task
        error:
          $ref: '#/components/schemas/TaskError'
        currentStep:
          type: string
          enum:
            - plan
            - post_plan
            - apply
            - post_apply
          description: Current step in the task execution
        workspaceId:
          type: string
          description: ID of the workspace the task is running on
        vcs:
          $ref: '#/components/schemas/TaskVcs'
        trigger:
          $ref: '#/components/schemas/TaskTrigger'
        type:
          type: string
          enum:
            - plan
            - apply
            - destroy
          description: Type of task that was executed
        cmdArguments:
          type: string
          description: Command line arguments used for the task
        createdAt:
          type: string
          format: date-time
          description: When the task was created
        updatedAt:
          type: string
          format: date-time
          description: When the task was last updated
      required:
        - id
        - status
        - workspaceId
        - type
    EditWorkspaceRequest:
      type: object
      properties:
        name:
          type: string
          description: Workspace name
          example: my-workspace
        description:
          type: string
          description: Workspace description
          example: Production environment workspace
        labels:
          type: array
          items:
            type: string
          description: Labels assigned to the workspace
          example:
            - production
            - terraform
        vcsIntegrationId:
          type: string
          description: VCS integration ID
          example: 5fd126f5744410407fbc552f
        repository:
          type: string
          description: Repository name
          example: infralight/appiac
        defaultBranch:
          type: string
          description: Default branch
          example: main
        vcs:
          type: string
          description: VCS type (github, gitlab, etc.)
          example: github
        workingDirectory:
          type: string
          description: Working directory path
          example: terraform/production
        iacProvisioner:
          $ref: '#/components/schemas/IacProvisioner'
        multiEnvProvisioner:
          $ref: '#/components/schemas/MultiEnvProvisioner'
        runnerType:
          type: string
          description: Type of runner (e.g., firefly_runners)
          example: firefly_runners
        triggerConfig:
          type: object
          properties:
            runOnPullRequest:
              type: boolean
              description: Whether to run on pull requests
              example: true
            runOnPush:
              type: boolean
              description: Whether to run on push events
              example: false
            autoApply:
              type: boolean
              description: Whether to auto-apply changes
              example: false
        cronExecutionPattern:
          type: string
          description: Cron pattern for scheduled executions
          example: 0 2 * * *
        parentId:
          type: string
          nullable: true
          description: Project ID or null for global access
          example: null
        poolId:
          type: string
          description: ID of the runner pool associated with the workspace
          example: 123e4567-e89b-12d3-a456-426614174000
        oidcAuthentication:
          type: boolean
          nullable: true
          description: OIDC authentication setting. If null, inherits from parent project.
    VcsTokenResponse:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: The VCS token
    UpdateTaskStatusRequest:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/TaskStatus'
        error:
          $ref: '#/components/schemas/TaskError'
        currentStep:
          $ref: '#/components/schemas/CurrentStep'
        workspaceRunId:
          type: string
    TaskStatus:
      type: string
      enum:
        - pending
        - running
        - success
        - failed
        - canceled
        - initializing
        - queued
        - planning
        - planning_destroy
        - applying
        - destroying
        - ready_for_apply
        - ready_for_destroy
        - destroyed
        - destroy_plan_completed
        - destroy_plan_failed
        - destroy_failed
        - discarded
        - canceling_init
        - canceling_plan
        - canceling_planning_destroy
        - canceling_apply
        - canceling_destroy
        - canceled_init
        - canceled_plan
        - canceled_planning_destroy
        - canceled_apply
        - canceled_destroy
    CurrentStep:
      type: string
      enum:
        - plan
        - post_plan
        - apply
        - post_apply
    UpdateCheckRunRequest:
      type: object
      required:
        - checkRunId
        - update
        - commitId
      properties:
        checkRunId:
          type: string
        commitId:
          type: string
          description: Commit identifier
        update:
          type: string
          enum:
            - queued
            - in_progress
            - success
            - failure
            - blocked
        gitlab:
          $ref: '#/components/schemas/GitLabCheckRunUpdate'
    GitLabCheckRunUpdate:
      type: object
      properties:
        projectId:
          type: integer
          description: Project identifier
        prId:
          type: integer
          description: Merge request ID if applicable
        headSha:
          type: string
          description: Head SHA of the commit
    SubTaskType:
      type: string
      enum:
        - plan
        - apply
        - rego
        - rego-changed-code
        - rego-plan-output
        - firefly-rego-lib-plan-output
        - cost
        - dot-terraform-state
        - dot-terraform-modules
        - terraform-providers
        - changed-code
        - guardrails
        - send-event
      description: Type of sub-task
    TaskFlow:
      type: array
      items:
        $ref: '#/components/schemas/SubTaskType'
      description: Flow of sub-tasks to execute
    TaskMetadata:
      type: object
      description: Metadata for the task
      additionalProperties: true
    InvalidArtifacts:
      type: object
      description: Invalid artifacts information
      additionalProperties: true
    SelfHostedRunTaskRequest:
      type: object
      required:
        - type
        - flow
        - content
      properties:
        accountId:
          type: string
          description: Account ID
        type:
          $ref: '#/components/schemas/TaskTypeEnum'
        flow:
          $ref: '#/components/schemas/TaskFlow'
        content:
          type: object
          additionalProperties:
            type: string
            nullable: true
          description: Map of sub-task types to content (base64-encoded byte arrays)
        metadata:
          $ref: '#/components/schemas/TaskMetadata'
        runnerType:
          type: string
          description: Type of runner
        repo:
          type: string
          description: Repository name
        workspace:
          type: string
          description: Workspace name
        availableLogs:
          type: array
          items:
            type: string
          description: List of available log identifiers
        tfWorkingDir:
          type: string
          description: Terraform working directory
        environment:
          type: string
          description: Environment name
    SelfHostedSaveInvalidArtifactsRequest:
      type: object
      required:
        - workspace
        - invalidArtifacts
      properties:
        accountId:
          type: string
          description: Account ID
        workspace:
          type: string
          description: Workspace name
        invalidArtifacts:
          $ref: '#/components/schemas/InvalidArtifacts'
    SelfHostedSaveLogsRequest:
      type: object
      required:
        - content
        - product
        - logId
      properties:
        accountId:
          type: string
          description: Account ID
        content:
          type: string
          format: byte
          description: Log content as byte array
        product:
          type: string
          description: Product identifier
        logId:
          type: string
          description: Log identifier
    SelfHostedRunTaskV2Response:
      type: object
      properties:
        taskId:
          type: string
        shouldWait:
          type: boolean
      required:
        - taskId
        - shouldWait
    UpdateWorkspaceRequest:
      type: object
      properties:
        description:
          type: string
        labels:
          type: array
          items:
            type: string
        cronExecutionPattern:
          type: string
        iacProvisioner:
          $ref: '#/components/schemas/IacProvisioner'
        multiEnvProvisioner:
          $ref: '#/components/schemas/MultiEnvProvisioner'
        repositoryUrl:
          type: string
        runsCount:
          type: integer
        isWorkflowManaged:
          type: boolean
        lastRunStatus:
          $ref: '#/components/schemas/WorkspaceRunStatus'
        lastApplyTime:
          type: string
          format: date-time
        lastPlanTime:
          type: string
          format: date-time
        lastDestroyTime:
          type: string
          format: date-time
        lastRunTime:
          type: string
          format: date-time
        backendSummary:
          allOf:
            - $ref: '#/components/schemas/BackendSummary'
          description: 'Deprecated: Use backends instead'
        backends:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BackendSummary'
          description: Map of environment to backend summary
        triggerConfig:
          $ref: '#/components/schemas/WorkspaceTriggerConfig'
        poolId:
          type: string
          description: ID of the runner pool to assign to this workspace
        oidcAuthentication:
          type: boolean
          nullable: true
          description: OIDC authentication setting. If null, inherits from parent project.
    WorkspaceRunStatus:
      type: string
      enum:
        - pending
        - running
        - success
        - failed
        - canceled
        - initializing
        - queued
        - planning
        - planning_destroy
        - applying
        - destroying
        - ready_for_apply
        - ready_for_destroy
        - destroyed
        - destroy_plan_completed
        - destroy_plan_failed
        - destroy_failed
        - discarded
        - canceling_init
        - canceling_plan
        - canceling_planning_destroy
        - canceling_apply
        - canceling_destroy
        - canceled_init
        - canceled_plan
        - canceled_planning_destroy
        - canceled_apply
        - canceled_destroy
        - init_error
        - plan_success
        - plan_error
        - apply_error
        - apply_success
        - blocked
        - Acknowledged
        - plan_no_changes
        - apply_no_changes
        - runner_failure
    UpdateWorkspaceRunRequest:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/WorkspaceRunStatus'
        AccountId:
          type: string
        workspaceId:
          type: string
        workspaceRunId:
          type: string
        error:
          $ref: '#/components/schemas/WorkspaceRunError'
      required:
        - workspaceRunId
    OwnerSummary:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
        initials:
          type: string
        customColor:
          type: string
    CheckPendingTasksResponse:
      type: object
      properties:
        hasPendingTasks:
          type: boolean
    AddWorkspaceRunRequest:
      type: object
      required:
        - workspaceRun
      properties:
        workspaceRun:
          $ref: '#/components/schemas/WorkspaceRun'
    OAuthTokenResponse:
      type: object
      properties:
        id_token:
          type: string
          description: JSON Web Token (JWT) ID token with OIDC claims
        token_type:
          type: string
          description: Token type (always "Bearer")
        expires_in:
          type: integer
          description: Token expiration time in seconds
      required:
        - id_token
        - token_type
        - expires_in
    PoolHealthStatus:
      type: string
      enum:
        - healthy
        - partial
        - inactive
      description: Overall health status of the pool
    RunnerHealthStatus:
      type: string
      enum:
        - active
        - awaiting_first_heartbeat
        - timeout
      description: Current health status of the runner
    PoolHealth:
      type: object
      properties:
        poolStatus:
          $ref: '#/components/schemas/PoolHealthStatus'
        statusByRunner:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RunnerHealthStatus'
          description: Map of runner ID to runner health status
    RunnerPool:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the runner pool
        name:
          type: string
          description: Name of the runner pool
        accountId:
          type: string
          description: ID of the account the pool belongs to
        labels:
          type: array
          items:
            type: string
          description: Labels assigned to the runner pool
        description:
          type: string
          description: Description of the runner pool
        runnersCount:
          type: integer
          minimum: 0
          description: Number of runners in the pool
        assignedProjectsCount:
          type: integer
          minimum: 0
          description: Number of projects assigned to this pool
        assignedWorkspaceCount:
          type: integer
          minimum: 0
          description: Number of workspaces assigned to this pool
        assignedProjects:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
          description: List of projects assigned to this pool
        assignedWorkspaces:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
          description: List of workspaces assigned to this pool
        health:
          $ref: '#/components/schemas/PoolHealth'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the pool was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the pool was last updated
    CreateRunnerPoolRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the runner pool
        labels:
          type: array
          items:
            type: string
          description: Labels to assign to the runner pool
        description:
          type: string
          description: Description of the runner pool
    JWTToken:
      type: object
      properties:
        token:
          type: string
          description: JWT token for runner authentication
        expiresAt:
          type: string
          format: date-time
          description: Token expiration timestamp
    CreateRunnerPoolResponse:
      type: object
      properties:
        poolId:
          type: string
          description: ID of the created runner pool
        jwt:
          $ref: '#/components/schemas/JWTToken'
    RunnerPoolMatchFilters:
      type: object
      description: >-
        Matching filters (key-value pairs). Values within the same filter use OR
        logic, filters across different types use AND logic.
      properties:
        name:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        status:
          oneOf:
            - $ref: '#/components/schemas/PoolHealthStatus'
            - type: array
              items:
                $ref: '#/components/schemas/PoolHealthStatus'
        labels:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
    TimestampFilters:
      type: object
      properties:
        before:
          type: string
          format: date-time
          description: Matches when timestamp is before this date
        after:
          type: string
          format: date-time
          description: Matches when timestamp is after this date
    RunnerPoolFilters:
      type: object
      properties:
        match:
          $ref: '#/components/schemas/RunnerPoolMatchFilters'
        created:
          $ref: '#/components/schemas/TimestampFilters'
        updated:
          $ref: '#/components/schemas/TimestampFilters'
    RunnerPoolSort:
      type: object
      required:
        - field
        - direction
      properties:
        field:
          type: string
          description: Field to sort by
          enum:
            - name
            - createdAt
            - updatedAt
            - runnersCount
            - assignedProjectsCount
            - assignedWorkspaceCount
            - poolStatus
        direction:
          type: string
          enum:
            - asc
            - desc
          description: Sort direction, either ascending (asc) or descending (desc)
      example:
        field: runnersCount
        direction: desc
    SearchRunnerPoolsRequest:
      type: object
      properties:
        text:
          type: string
          description: Free text search query, searches across pool name and labels
        filters:
          $ref: '#/components/schemas/RunnerPoolFilters'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/RunnerPoolSort'
          description: Array of sort criteria. Multiple sort fields are applied in order.
    EnhancedWorkspaceNode:
      type: object
      required:
        - id
        - name
        - type
        - projectId
        - effectivePoolId
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - workspace
        projectId:
          type: string
        defaultBranch:
          type: string
        poolId:
          type: string
          nullable: true
        effectivePoolId:
          type: string
          nullable: true
    EnhancedProjectNode:
      type: object
      required:
        - id
        - name
        - path
        - type
        - effectivePoolId
        - isRoot
        - workspaces
        - children
      properties:
        id:
          type: string
        name:
          type: string
        path:
          type: string
        type:
          type: string
          enum:
            - project
        parentId:
          type: string
        poolId:
          type: string
          nullable: true
        effectivePoolId:
          type: string
          nullable: true
        isRoot:
          type: boolean
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/EnhancedWorkspaceNode'
        children:
          type: array
          items:
            $ref: '#/components/schemas/EnhancedProjectNode'
    AssignableTreeResponse:
      type: object
      required:
        - data
        - metadata
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EnhancedProjectNode'
        metadata:
          type: object
          required:
            - totalProjects
            - totalWorkspaces
          properties:
            totalProjects:
              type: integer
            totalWorkspaces:
              type: integer
            currentPoolId:
              type: string
    UpdateRunnerPoolRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the runner pool
        labels:
          type: array
          items:
            type: string
          description: Labels to assign to the runner pool
        description:
          type: string
          description: Description of the runner pool
    RunnerDeploymentType:
      type: string
      enum:
        - kubernetes
        - docker
        - binary
      description: Type of deployment for runners
    GetRunnerDeploymentInstructionsRequest:
      type: object
      required:
        - initialCount
        - deploymentType
      properties:
        initialCount:
          type: integer
          minimum: 1
        deploymentType:
          $ref: '#/components/schemas/RunnerDeploymentType'
    Runner:
      type: object
      properties:
        poolId:
          type: string
        name:
          type: string
        lastSeen:
          type: string
          format: date-time
        version:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/RunnerHealthStatus'
    RegisterRunnerRequest:
      type: object
      required:
        - name
        - version
      properties:
        name:
          type: string
        version:
          type: string
    RunnerCredentialsResponse:
      type: object
      properties:
        temporalUrl:
          type: string
        temporalNamespace:
          type: string
        temporalQueue:
          type: string
          description: Temporal task queue name for the runner pool
        temporalCertificate:
          type: string
          description: Base64-encoded PEM certificate for Temporal mTLS authentication
        temporalPrivateKey:
          type: string
          description: Base64-encoded PEM private key for Temporal mTLS authentication
        temporalCACert:
          type: string
          description: >-
            Base64-encoded PEM CA certificate for verifying Temporal server
            certificate
        temporalJWT:
          $ref: '#/components/schemas/JWTToken'
    RunnerHeartbeatRequest:
      type: object
      required:
        - version
      properties:
        version:
          type: string
    OIDCConfiguration:
      type: object
      properties:
        issuer:
          type: string
          description: URL using https scheme with no query or fragment
        token_endpoint:
          type: string
          description: URL of OAuth 2.0 token endpoint
        jwks_uri:
          type: string
          description: URL of JSON Web Key Set document
        response_types_supported:
          type: array
          items:
            type: string
          description: Array of supported OAuth 2.0 response types
        subject_types_supported:
          type: array
          items:
            type: string
          description: Array of supported subject identifier types
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
          description: Array of JWS signing algorithms supported for ID tokens
      required:
        - issuer
        - token_endpoint
        - jwks_uri
        - response_types_supported
        - subject_types_supported
        - id_token_signing_alg_values_supported
    JWKSet:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/JWK'
          description: Array of JSON Web Keys
      required:
        - keys
    JWK:
      type: object
      properties:
        kty:
          type: string
          description: Key type (e.g., "RSA")
        use:
          type: string
          description: Intended use of the key (e.g., "sig" for signature)
        kid:
          type: string
          description: Key ID
        alg:
          type: string
          description: Algorithm (e.g., "RS256")
        'n':
          type: string
          description: RSA modulus (base64-url-encoded)
        e:
          type: string
          description: RSA exponent (base64-url-encoded)
      required:
        - kty
        - use
        - kid
        - alg
        - 'n'
        - e
    ListModuleReposResponse:
      type: array
      items:
        type: object
        properties:
          key:
            type: object
            properties:
              repoFullName:
                type: string
                description: The full name of the repository
              vcsType:
                type: string
                description: >-
                  The VCS where this repository is located (e.g. github, gitlab,
                  bitbucket)
              isPublic:
                type: boolean
                description: Whether the repository is public or private
          doc_count:
            type: integer
            description: The number of modules for the given asset types in the repository
    ListModulesResponse:
      type: array
      items:
        type: object
        properties:
          moduleSourceType:
            type: string
            description: Whether the source code from this repository is private or public
          moduleName:
            type: string
            description: The name of the module
          moduleFullPathMD5:
            type: string
            description: The MD5 hash of the module path
          moduleResourceTypes:
            type: array
            items:
              type: string
              description: The Terraform asset type (e.g. aws_s3_bucket)
          missingAssetTypes:
            type: boolean
            description: >-
              Whether the module is missing asset types given the input
              resourceTypes
    CodifyModuleRequest:
      type: object
      required:
        - assetId
        - assetType
        - moduleMD5
        - provider
        - providerId
        - sourceType
      properties:
        assetId:
          type: string
          description: The id of the resource to be codified using module call
        assetType:
          type: string
          description: The Terraform asset type (e.g. aws_s3_bucket)
        format:
          type: string
          description: The format of the codified result (e.g. terraform, json)
          enum:
            - HCL
            - YAML
            - JSON
            - TFVARS
            - TFVARS_JSON
            - TERRAGRUNT
          default: HCL
        moduleMD5:
          type: string
          description: The MD5 hash of the module path
        repoProtocol:
          type: string
          description: The protocol to reach the module's repository
          enum:
            - ssh
            - https
          default: ssh
        provider:
          type: string
          description: The provider of the resource type
          enum:
            - akamai
            - aws
            - azurerm
            - cloudflare
            - datadog
            - gcp
            - github
            - mongodbatlas
            - newrelic
            - ns1
            - oci
            - pagerduty
            - vault
        providerId:
          type: string
          description: The Firefly integration ID where the resource is located
        sourceType:
          type: string
          description: The source type of the module (e.g. private, public)
          enum:
            - private
            - public
        withAi:
          type: boolean
          description: Whether to use AI to codify the module
          default: true
    CodifyModuleResponse:
      type: object
      properties:
        Files:
          type: object
          additionalProperties:
            type: string
          description: Map of file paths to their contents
        CodifiedMismatches:
          type: array
          items:
            type: string
          description: List of asset types that could not be codified
        ModuleMismatches:
          type: array
          items:
            type: string
          description: >-
            Asset types present in the module that are not part of the original
            request
        TerraformCMDs:
          type: array
          items:
            type: string
          description: Terraform commands to import the generated module
        TerraformImportBlocks:
          type: array
          items:
            type: string
          description: Terraform import blocks
        HasUnknownModules:
          type: boolean
          description: Whether the module has unknown modules
        ModuleCallGaps:
          type: array
          items:
            type: string
          description: >-
            Potential issues with existing module call considering input and
            output
        Format:
          type: string
          description: The format of the codified result based on the request
          enum:
            - HCL
            - YAML
            - JSON
            - TFVARS
            - TFVARS_JSON
            - TERRAGRUNT
    CreateModuleRequest:
      type: object
      required:
        - assetId
        - assetType
        - provider
        - providerId
      properties:
        assetId:
          type: string
          description: The id of the resource to be codified using create module
        assetType:
          type: string
          description: The Terraform asset type (e.g. aws_s3_bucket)
        provider:
          type: string
          description: The provider of the resource type
          enum:
            - akamai
            - aws
            - azurerm
            - cloudflare
            - datadog
            - gcp
            - github
            - mongodbatlas
            - newrelic
            - ns1
            - oci
            - pagerduty
            - vault
        providerId:
          type: string
          description: The Firefly integration ID where the resource is located
        tfVersion:
          type: string
          description: The Terraform version to use from the specified provider
        withAi:
          type: boolean
          description: Whether to use AI to create the module
          default: true
        withDependencies:
          type: boolean
          description: >-
            Whether to include dependencies in the module (only available when
            withAi is true)
          default: false
    CreateModuleResponse:
      type: object
      additionalProperties:
        type: string
      description: Map of file paths to their contents
    CodifyAssetRequest:
      type: object
      required:
        - assetType
        - assetId
        - iacType
        - provider
        - accountNumber
      properties:
        assetType:
          type: string
          description: The Terraform asset type (e.g., aws_s3_bucket)
        assetId:
          type: string
          description: The unique identifier of the cloud asset (e.g., ARN)
        iacType:
          type: string
          description: The Infrastructure as Code type
          enum:
            - terraform
            - tfcdk
            - cloudformation
            - pulumi
        provider:
          type: string
          description: The cloud provider (e.g., aws, azure, gcp)
        accountNumber:
          type: string
          description: The cloud account number/ID
        ignoreEscaping:
          type: boolean
          default: false
          description: If true, returns raw HCL without escaping newlines
    CodifyAssetResponse:
      type: object
      properties:
        codifiedResult:
          type: string
          description: The generated IaC code
        importBlocks:
          type: string
          description: Terraform import blocks (semicolon-separated)
        importCommand:
          type: string
          description: Terraform import commands (semicolon-separated)
        providerBlock:
          type: string
          description: The Terraform provider block
    CreatePullRequestRequest:
      type: object
      required:
        - vcsId
        - repository
        - iacType
        - resources
      properties:
        vcsId:
          type: string
          description: VCS integration ID
        repository:
          type: string
          description: Repository full name (e.g., org/repo)
        iacType:
          type: string
          description: Infrastructure as Code type
          enum:
            - terraform
            - tfcdk
            - cloudformation
            - pulumi
        resources:
          type: array
          items:
            $ref: '#/components/schemas/CodificationResource'
          description: Array of cloud resources to codify
        codificationData:
          $ref: '#/components/schemas/CodificationData'
        prComment:
          type: string
          description: Comment to include in the pull request description
        fileName:
          type: string
          description: File path for the codified output
        selectedBranch:
          type: string
          description: Target branch name (defaults to main/master)
    CodificationResource:
      type: object
      required:
        - assetType
        - assetId
        - providerId
        - provider
      properties:
        assetType:
          type: string
          description: The Terraform asset type (e.g., aws_s3_bucket)
        assetId:
          type: string
          description: The unique identifier of the cloud asset
        providerId:
          type: string
          description: The Firefly integration ID
        provider:
          type: string
          description: The cloud provider
        revisionId:
          type: string
          description: Optional revision ID for the asset
        isDeleted:
          type: boolean
          description: Whether the asset has been deleted
        frn:
          type: string
          description: Firefly Resource Name
    CodificationData:
      type: object
      properties:
        codificationMode:
          type: string
          description: The codification mode (e.g., NAIVE, MODULE)
        preparedContent:
          type: array
          items:
            type: object
            properties:
              filePath:
                type: string
              content:
                type: string
              overWrite:
                type: boolean
                default: false
                description: >-
                  Whether to overwrite the file if it already exists in the
                  repository
          description: Pre-prepared file content to use instead of codifying
        selectedModule:
          type: string
          description: Selected module identifier (used in PR title)
        fileExtension:
          type: string
          description: File extension for the output
          default: tf
        codifyType:
          type: string
          description: Type of codification operation (e.g., codification, remediation)
        commitDetails:
          type: string
          description: Additional commit message details
        language:
          type: string
          description: Output language format
          default: hcl
        withImportBlocks:
          type: boolean
          description: Include Terraform import blocks in the output
          default: false
        withProviderBlock:
          type: boolean
          description: Include Terraform provider block in the output
          default: false
    CreatePullRequestResponse:
      type: object
      required:
        - ok
        - url
        - branchName
      properties:
        ok:
          type: boolean
          description: Whether the pull request was created successfully
        url:
          type: string
          description: URL of the created pull request
        branchName:
          type: string
          description: Name of the created branch
    IntegrationResponse:
      type: object
      properties:
        id:
          type: string
          description: Integration ID
        accountId:
          type: string
          description: Account ID
        name:
          type: string
          description: Integration name
        active:
          type: boolean
          description: Whether the integration is active
        lastScan:
          type: string
          format: date-time
          description: Last successful scan time
        creationDate:
          type: string
          format: date-time
          description: Integration creation date
        accountNumber:
          type: string
          description: Cloud account number (for AWS, Azure, K8s)
        projectId:
          type: string
          description: GCP project ID (for GCP only)
    CreateAwsIntegrationRequest:
      type: object
      required:
        - accountNumber
        - nickname
      properties:
        accountNumber:
          type: string
          description: AWS account number (12 digits)
          pattern: ^[0-9]{12}$
        nickname:
          type: string
          description: Friendly name for the integration
    CreateK8sIntegrationRequest:
      type: object
      required:
        - clusterId
      properties:
        clusterId:
          type: string
          description: Kubernetes cluster ID
        accessKey:
          type: string
          description: Optional access key for authentication
        secretKey:
          type: string
          description: Optional secret key for authentication
        isProduction:
          type: boolean
          description: Whether this is a production cluster
    CreateAwsIntegrationResponse:
      type: object
      properties:
        externalId:
          type: string
          description: External ID for AWS IAM role trust policy
    CreateK8sIntegrationResponse:
      type: object
      properties:
        code:
          type: string
          description: Helm installation command
        accessKey:
          type: string
          description: Access key for the integration
    DeleteIntegrationResponse:
      type: object
      properties:
        clusterId:
          type: string
          description: The deleted cluster ID
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
    ExternalIdResponse:
      type: object
      properties:
        externalId:
          type: string
          description: AWS external ID for IAM role trust policy
    AwsCftConfigResponse:
      type: object
      required:
        - bucketUrl
        - region
        - fireflyAccountNumber
        - fireflyEventBusArn
      properties:
        bucketUrl:
          type: string
          format: uri
          description: Base S3 URL for CloudFormation templates
        region:
          type: string
          description: Default AWS region for CloudFormation stack deployment
        fireflyAccountNumber:
          type: string
          description: Firefly account number
        fireflyEventBusArn:
          type: string
          description: Firefly event bus ARN
      example:
        bucketUrl: https://infralight-templates-public.s3.amazonaws.com
        region: us-east-1
        fireflyAccountNumber: '3456345345345'
        fireflyEventBusArn: >-
          arn:aws:events:eu-west-1:3456345345345:event-bus/prod-eu-stablefly-event-bus
    AssetSearchFilters:
      type: object
      properties:
        assetState:
          type: string
          description: Asset state filter (e.g., managed, unmanaged, ghost, drifted)
        assetTypes:
          type: array
          items:
            type: string
          description: List of asset types to filter by
        modifiedSince:
          type: string
          description: Filter assets modified since this date (Format YYYY-MM-DD)
        freeTextSearch:
          type: string
          description: Free text search query
        arns:
          type: array
          items:
            type: string
          description: List of ARNs to filter by
        frns:
          type: array
          items:
            type: string
          description: List of FRNs to filter by
        providerIds:
          type: array
          items:
            type: string
          description: List of provider IDs to filter by
        regions:
          type: array
          items:
            type: string
          description: List of regions to filter by
        names:
          type: array
          items:
            type: string
          description: List of asset names to filter by
        providerTypes:
          type: object
          properties:
            providerType:
              type: array
              items:
                type: string
            providerSubType:
              type: array
              items:
                type: string
            provider:
              type: array
              items:
                type: string
            integrationId:
              type: array
              items:
                type: string
        tags:
          type: array
          items:
            type: string
          description: List of tags to filter by
        iacTypes:
          type: array
          items:
            type: string
          description: List of IaC types to filter by
        deleted:
          type: boolean
          default: false
          description: Include deleted assets
        includeConfiguration:
          type: boolean
          default: true
          description: Include asset configuration in response
        excludeIacTypes:
          type: array
          items:
            type: string
          description: List of IaC types to exclude
        excludeTags:
          type: array
          items:
            type: string
          description: List of tags to exclude
        excludeTypes:
          type: array
          items:
            type: string
          description: List of asset types to exclude
        excludeRegions:
          type: array
          items:
            type: string
          description: List of regions to exclude
        severity:
          type: array
          items:
            $ref: '#/components/schemas/PolicySeverity'
        violatingPoliciesIds:
          type: array
          items:
            type: string
          description: List of policy IDs that are violated
        matchingExclusionRulesIds:
          type: array
          items:
            type: string
          description: List of matching exclusion IDs
        stackIds:
          type: array
          items:
            type: string
          description: List of stack IDs containing the assets
        owners:
          type: array
          items:
            type: string
          description: List of owners
        integrationIds:
          type: array
          items:
            type: string
        hasMutations:
          type: boolean
          default: false
        hasVCSLink:
          type: boolean
          default: false
        hasComments:
          type: boolean
          default: false
        deletedRange:
          type: array
          items:
            type: string
        hasRelationship:
          type: boolean
          default: false
        masterType:
          type: array
          items:
            type: string
            enum:
              - cloud
              - saas
              - kubernetes
        isExcluded:
          type: boolean
          default: false
        query:
          type: string
          description: Query string to search for
    IacCoverageRequest:
      type: object
      properties:
        integrations:
          description: List of integration IDs to filter by
          type: array
          items:
            type: string
    IacCoverageResponse:
      type: object
      properties:
        iacCoverage:
          type: object
          properties:
            codified:
              type: integer
              description: Number of assets that are codified (managed)
            unmanaged:
              type: integer
              description: Number of unmanaged assets
            ghost:
              type: integer
              description: Number of ghost assets
            drifted:
              type: integer
              description: Number of drifted (modified) assets
    PolicySeverity:
      type: string
      enum:
        - CRITICAL
        - HIGH
        - MEDIUM
        - LOW
        - INFO
        - TRACE
    AssetIacStatus:
      type: string
      enum:
        - modified
        - managed
        - child
        - unmanaged
        - ghost
        - undetermined
        - unknown
        - pending
        - deleted
        - created
        - iacIgnored
    UserIdentity:
      type: object
      properties:
        customColor:
          type: string
          description: Custom color associated with the user
        initials:
          type: string
          description: User's initials
        displayName:
          type: string
          description: Display name of the user
        type:
          type: string
          description: Type of user identity
          enum:
            - IAMUser
    Activity:
      type: object
      properties:
        ActionType:
          type: string
          description: Type of action performed
        eventTime:
          type: string
          description: Timestamp of the event
        eventName:
          type: string
          description: Name of the event
        userIdentity:
          $ref: '#/components/schemas/UserIdentity'
        eventId:
          type: string
          description: Event identifier
    Asset:
      type: object
      properties:
        integrationId:
          description: The integration ID
          type: string
        provider:
          type: string
          description: The provider of the asset
        providerId:
          type: string
          description: The provider ID
        assetId:
          type: string
          description: The asset ID
        resourceId:
          description: The resource ID
          type: string
        isExcluded:
          description: Whether the asset is excluded (matched by an exclusion id)
          type: boolean
        lastConfigurationChangeTime:
          description: The time the asset configuration was last changed
          type: string
        updatedAt:
          description: The time the asset was last updated
          type: string
        matchingExclusionRuleIds:
          description: The exclusion rule IDs that match the asset
          type: array
          items:
            type: string
        state:
          $ref: '#/components/schemas/AssetIacStatus'
        isChild:
          description: Whether the asset is a child resource
          type: boolean
        frn:
          description: The FRN of the asset
          type: string
        providerGroupId:
          description: The provider group ID (if applicable)
          type: string
        firstSeen:
          description: The time the asset was first seen
          type: string
        pendingTo:
          description: The pending state of the asset
          type: string
        lastAssetStateChange:
          description: The time the asset's state was last changed
          type: string
        subProvider:
          description: The sub-provider of the asset
          type: string
        classificationsDetails:
          description: The classification details of the asset
          type: object
          properties:
            remediationCommands:
              type: array
              items:
                type: string
            description:
              type: string
            monthlyCost:
              type: object
              properties:
                currency:
                  type: string
                value:
                  type: number
        tags:
          description: The tags of the asset
          type: object
          properties:
            key:
              type: string
            value:
              type: string
        assetType:
          description: The type of the asset
          type: string
        violationPolicyIds:
          description: List of violating governance policy IDs
          type: array
          items:
            type: string
        status:
          type: string
        stateUpdatedTime:
          description: The time the asset's state was last updated
          type: string
        stackIds:
          type: array
        name:
          type: string
        location:
          type: string
        creationDate:
          type: integer
        deleteCommand:
          type: string
        consoleURL:
          type: string
        tagsList:
          type: array
          items:
            description: A tag
            type: string
        arn:
          type: string
        flywheelSummary:
          type: object
          properties:
            requires_replace_items:
              type: string
            requires_replace:
              type: boolean
            drifts:
              type: string
            status:
              type: string
        taggingStatus:
          type: string
          enum:
            - NOT_TAGGED
            - TAGGED
            - IRRELEVANT
        pendingExpiration:
          type: string
        customColumns:
          type: object
          properties:
            key:
              type: string
            value:
              type: string
        service:
          type: string
        lastActivity:
          $ref: '#/components/schemas/Activity'
        providerSubType:
          type: string
        creationTime:
          type: string
        id:
          type: string
        revisionCount:
          type: integer
        iac:
          type: object
          properties:
            type:
              description: Type of IAC
              type: string
            stackName:
              type: string
            stackIds:
              type: array
              items:
                type: string
            activeStackId:
              type: string
            firstSeen:
              type: string
            moduleAddress:
              type: string
            objectName:
              type: string
            objectFullAddresses:
              type: string
            stateLocation:
              description: Location of the state file
              type: string
        vcs:
          type: object
          properties:
            id:
              type: string
            codeLink:
              type: string
            codeFileLink:
              type: string
            provider:
              type: string
            repo:
              type: string
            workingDirectory:
              type: string
    LockResponse:
      nullable: true
      type: object
      properties:
        lockId:
          type: string
          description: Lock identifier in the format accountId/workspaceName
        workspaceId:
          type: string
        owner:
          type: string
          description: Base64-encoded memberId of the lock owner
        createdAt:
          type: string
          format: date-time
    EntitlementSetResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - id
            - type
            - attributes
          properties:
            id:
              type: string
            type:
              type: string
              enum:
                - entitlement-sets
            attributes:
              type: object
              properties:
                operations:
                  type: boolean
    WorkspaceResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - id
            - type
            - attributes
          properties:
            id:
              type: string
            type:
              type: string
              enum:
                - workspaces
            attributes:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                execution-mode:
                  type: string
                  enum:
                    - local
                    - remote
                terraform-version:
                  type: string
                  nullable: true
                locked:
                  type: boolean
    StateVersionResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - id
            - type
            - attributes
          properties:
            id:
              type: string
            type:
              type: string
              enum:
                - state-versions
            attributes:
              type: object
              required:
                - hosted-state-download-url
              properties:
                hosted-state-download-url:
                  type: string
                  format: uri
                serial:
                  type: integer
                terraform-version:
                  type: string
                  nullable: true
    StateVersionUploadResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - id
            - type
            - attributes
          properties:
            id:
              type: string
            type:
              type: string
              enum:
                - state-versions
            attributes:
              type: object
              required:
                - hosted-state-upload-url
              properties:
                hosted-state-upload-url:
                  type: string
                  format: uri
                hosted-json-state-upload-url:
                  type: string
                  format: uri
                hosted-state-download-url:
                  type: string
                  format: uri
    StateVersionUploadRequest:
      type: object
      additionalProperties: true
      required:
        - data
      properties:
        data:
          type: object
          additionalProperties: true
          required:
            - type
            - attributes
          properties:
            type:
              type: string
              enum:
                - state-versions
            attributes:
              type: object
              additionalProperties: true
              required:
                - lineage
                - serial
                - md5
              properties:
                lineage:
                  type: string
                serial:
                  type: integer
                  format: int64
                md5:
                  type: string
                force:
                  type: boolean
                  default: false
                json-state-outputs:
                  type: string
                  format: byte
                  description: Base64-encoded JSON state outputs
                run:
                  type: object
                  description: Optional run association
                  properties:
                    id:
                      type: string
    LockWorkspaceRequest:
      type: object
      additionalProperties: true
      properties:
        data:
          type: object
          additionalProperties: true
          properties:
            type:
              type: string
              enum:
                - workspaces
            attributes:
              type: object
              additionalProperties: true
              properties:
                reason:
                  type: string
    UnlockWorkspaceRequest:
      type: object
      additionalProperties: true
      properties:
        data:
          type: object
          additionalProperties: true
          properties:
            type:
              type: string
              enum:
                - workspaces
    JsonApiError:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - status
              - title
            properties:
              status:
                type: string
                description: HTTP status code as string
              title:
                type: string
                description: Short human-readable summary
              detail:
                type: string
                description: Human-readable explanation
    ResourceConnection:
      type: object
      description: A connected resource with full asset details from Elasticsearch
      required:
        - id
        - frn
        - integrationId
        - accountId
        - assetType
        - type
        - hierarchy
      properties:
        id:
          type: string
          description: >-
            Unique identifier in format
            "integrationId:assetType:region:resourceId"
          example: 60123456789abcdef1234567:aws_instance:us-east-1:i-0123456789abcdef0
        frn:
          type: string
          description: Firefly Resource Name
          example: aws_instance:us-east-1:i-0123456789abcdef0
        assetId:
          type: string
          description: Cloud provider's resource identifier (ARN for AWS)
          example: arn:aws:ec2:us-east-1:012345678912:instance/i-0123456789abcdef0
        resourceId:
          type: string
          description: Provider-specific resource ID
          example: i-0123456789abcdef0
        integrationId:
          type: string
          description: Integration ID of the connected resource
          example: 60123456789abcdef1234567
        accountId:
          type: string
          description: Firefly account ID
          example: 60123456789abcdef1234567
        assetType:
          type: string
          description: Type of the connected asset
          example: aws_instance
        name:
          type: string
          description: Resource name
          example: i-0123456789abcdef0
        region:
          type: string
          description: Cloud region
          example: us-east-1
        provider:
          type: string
          description: Cloud provider
          example: aws
        providerId:
          type: string
          description: Cloud provider account ID
          example: '012345678912'
        providerType:
          type: string
          description: Provider category
          enum:
            - cloud
            - saas
            - kubernetes
          example: cloud
        providerSubType:
          type: string
          description: Provider subcategory
          example: iaas
        service:
          type: string
          description: Cloud service name
          example: ec2
        connectionType:
          type: string
          description: Type of connection between resources
          example: Contains
        hierarchy:
          type: array
          description: Hierarchy path of the resource in the relationship graph
          items:
            type: string
        type:
          type: string
          description: Node type in the relationship graph
          enum:
            - ASSET
            - TRACE
          example: ASSET
        hasOwnerTargets:
          type: boolean
          description: Whether this resource has ownership targets
          example: true
        hasOwnerSources:
          type: boolean
          description: Whether this resource has ownership sources
          example: false
        ownerTargetsList:
          type: array
          description: List of resources this resource owns
          items:
            type: string
        ownerSourcesList:
          type: array
          description: List of resources that own this resource
          items:
            type: string
        hasControllerTargets:
          type: boolean
          description: Whether this resource has controller targets (Kubernetes)
          example: false
        hasControllerSources:
          type: boolean
          description: Whether this resource has controller sources (Kubernetes)
          example: false
        state:
          type: string
          description: Current state of the resource
          example: iacIgnored
          enum:
            - unmanaged
            - managed
            - modified
            - ghost
            - iacIgnored
            - child
        prevState:
          type: string
          description: Previous state of the resource
          example: created
        iacType:
          type: string
          description: Infrastructure as Code type
          example: unmanaged
        isExcluded:
          type: boolean
          description: Whether the resource is excluded from mutations
          example: true
        exclusions:
          type: array
          description: List of exclusion rule IDs applied to this resource
          items:
            type: string
        firstSeen:
          type: string
          description: When the resource was first discovered
          example: 2025-06-29 14:13:27.050209723 +0000 UTC
        updateAt:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2025-01-01T12:34:56.323161114Z'
        inventoryUpdateTime:
          type: string
          format: date-time
          description: Last inventory update time
          example: '2025-01-01T12:34:56.323161114Z'
        lastResourceStateChange:
          type: string
          format: date-time
          description: Last state change timestamp
          example: '2025-06-29T14:15:24.283522147Z'
        tags:
          type: string
          description: JSON string of resource tags
          example: '{"key1": "value1", "key2": "value2"}'
        tagsList:
          type: array
          description: Array of tags
          items:
            type: string
            example: 'key1: value1'
        taggingStatus:
          type: string
          description: Tagging status
          enum:
            - NOT_SUPPORTED
            - NOT_TAGGED
            - TAGGED
        consoleURL:
          type: string
          description: Cloud provider console URL for the resource
          example: >-
            https://us-east-1.console.aws.amazon.com/vpc/home?region=us-east-1#RouteTableDetails:RouteTableId=rtb-12345678
        deleteCommand:
          type: string
          description: CLI command to delete the resource
          example: aws ec2 terminate-instances --instance-ids i-12345678
        stackId:
          type: string
          description: >-
            Identifier of the stack where this resource is located if managed by
            Infrastructure as Code
        stackName:
          type: string
          description: Name of the stack where this resource is located
        stackIds:
          type: array
          description: >-
            List of identifiers of the stacks where this resource is located, if
            managed by multiple stacks
          items:
            type: string
        stacks:
          type: array
          items:
            type: object
            description: Stack where this resource is located
            properties:
              stackId:
                type: string
                description: Identifier of the stack
              stackType:
                type: string
                description: Type of the stack
              stackName:
                type: string
                description: Name of the stack
        metaHash:
          type: string
          description: Hash of the metadata of the resource
        prevSignature:
          type: string
          description: Previous hash signature of the resource
        schemaVersion:
          type: integer
          description: Terraform version of the resource's schema
        revisionsNumber:
          type: integer
          description: Number of mutations revisions of the resource
        hasRevisions:
          type: boolean
          description: Whether the resource has revisions
        isChild:
          type: boolean
          description: Whether the resource is a child of another resource
        isLocked:
          type: boolean
          description: Whether the resource is locked
        isEventDriven:
          type: boolean
          description: Whether the latest resource configuration originated from an event
        isOutOfSync:
          type: boolean
          description: >-
            Whether the resource configuration might be out of sync with the
            remote
        runId:
          type: string
          description: Identifier of the run that created the resource
        accountName:
          type: string
          description: Name of the Firefly account who owns this resource
        arn:
          type: string
          description: ARN of the resource
        nonBijectionFRN:
          type: string
          description: FRN of the resource
    PaginationParams:
      type: object
      properties:
        page:
          type: integer
          description: Page number (1-indexed)
          minimum: 1
          default: 1
        pageSize:
          type: integer
          description: Number of items per page
          minimum: 1
          maximum: 10000
          default: 50
        pageNumber:
          type: integer
          description: Page number (1-indexed) - v1 compatibility alias for page
          minimum: 1
        tablePageSize:
          type: integer
          description: Number of items per page - v1 compatibility alias for pageSize
          minimum: 1
          maximum: 10000
    SortingOptions:
      oneOf:
        - type: object
          properties:
            field:
              type: string
              description: Field name to sort by
            order:
              type: string
              description: Sort direction (asc or desc)
              default: desc
        - type: array
          items:
            type: object
            properties:
              field:
                type: string
              sort:
                type: string
          description: Array of sorting options (v1 compatibility)
    ScreenFilters:
      type: object
      description: >
        Filters for querying stacks. Filter values are matched against stack
        properties.

        Some filters are mapped to nested fields internally:

        - providerIntegrationId → stackProviders.providerIntegrationId

        - providerType → stackProviders.providerType

        - providerAccountId → stackProviders.providerAccountId

        - vcsRepo → metadata.vcsRepo
      additionalProperties: true
      properties:
        stateType:
          type: array
          items:
            type: string
          description: >-
            IAC type filter (terraform, cloudformation, pulumi, helm, k8s,
            opentofu, etc.)
        providerIntegrationId:
          type: array
          items:
            type: string
          description: Integration ID filter (maps to stackProviders.providerIntegrationId)
        providerType:
          type: array
          items:
            type: string
          description: >-
            Provider type filter - aws, gcp, azure, etc. (maps to
            stackProviders.providerType)
        providerAccountId:
          type: array
          items:
            type: string
          description: >-
            Provider account ID filter (maps to
            stackProviders.providerAccountId)
        stackAssetTypes:
          type: array
          items:
            type: string
          description: Asset type filter
        status:
          type: array
          items:
            type: string
          description: Stack status filter
        iacState:
          type: array
          items:
            type: string
          description: >-
            Stack sync state filter - synced, unsynced, drifted (handled via
            meta-index)
        vcsRepo:
          type: array
          items:
            type: string
          description: VCS repository filter (maps to metadata.vcsRepo)
        backendLocation:
          type: array
          items:
            type: string
          description: Backend location filter
        hasIntegratedProviders:
          type: boolean
          description: Filter stacks with integrated providers
        hasNotIntegratedProviders:
          type: boolean
          description: Filter stacks without integrated providers
    IacStack:
      type: object
      properties:
        id:
          type: string
          description: Unique stack identifier
        name:
          type: string
          description: Stack name
        stateType:
          type: string
          enum:
            - terraform
            - cloudformation
            - pulumi
            - helm
            - k8s
          description: IaC type
        status:
          type: string
          description: Stack status
        version:
          type: string
          description: IaC version
        backend:
          type: string
          description: Backend/state storage location
        lastApplied:
          type: string
          format: date-time
          description: Last apply timestamp
        assetCount:
          type: integer
          description: Number of managed assets
        stackProviders:
          type: array
          items:
            $ref: '#/components/schemas/StackProvider'
        metadata:
          type: object
          properties:
            vcsRepo:
              type: string
            vcsPath:
              type: string
            branch:
              type: string
    StackProvider:
      type: object
      properties:
        providerType:
          type: string
          description: Provider type (aws, gcp, azure, etc.)
        providerAccountId:
          type: string
          description: Provider account identifier
        providerIntegrationId:
          type: string
          description: Firefly integration ID
        isIntegrated:
          type: boolean
          description: Whether provider is integrated with Firefly
    Backend:
      type: object
      properties:
        id:
          type: string
          description: Crawler ID
        type:
          type: string
          enum:
            - s3
            - gcs
            - azure-blob
            - terraform-cloud
            - gitlab
            - github
          description: Backend type
        mainLocation:
          type: string
          description: Primary storage location
        lastScan:
          type: string
          format: date-time
          description: Last scan timestamp
        isDeleted:
          type: boolean
        remoteIntegrationId:
          type: string
          description: Associated integration ID
    IacStacksRepository:
      type: object
      properties:
        repoFullName:
          type: string
          description: Full repository name (org/repo)
        maxTimestamp:
          type: number
          description: Last update timestamp (epoch)
        topHit:
          type: object
          properties:
            vcsId:
              type: string
              description: VCS integration ID
            vcsType:
              type: string
              enum:
                - github
                - gitlab
                - bitbucket
                - azure-devops
              description: VCS type
            modulesCount:
              type: integer
              description: Number of modules in repository
            resourcesCount:
              type: integer
              description: Number of resources in repository
    Module:
      type: object
      properties:
        id:
          type: string
          description: Module ID
        moduleFolderPath:
          type: string
          description: Path to module folder
        repoFullName:
          type: string
          description: Repository containing the module
        moduleVcsPath:
          type: string
          description: VCS URL path to module
        vcsType:
          type: string
          enum:
            - github
            - gitlab
            - bitbucket
            - azure-devops
        updateAt:
          type: string
          format: date-time
          description: Last update timestamp
        lastContributor:
          type: string
          description: Last contributor username
        firstContributor:
          type: string
          description: Original author username
        usageCount:
          type: integer
          description: Number of stacks using this module
        version:
          type: string
          description: Module version
        moduleOrigin:
          type: string
          description: Module source origin
        moduleOriginType:
          type: string
          enum:
            - local
            - registry
            - git
          description: Module origin type
    ProviderAggregation:
      type: object
      additionalProperties:
        type: object
        additionalProperties:
          type: object
          properties:
            count:
              type: integer
              description: Number of stacks using this provider
            isIntegrated:
              type: boolean
              description: Whether provider is integrated
    SearchIacStacksRequest:
      allOf:
        - $ref: '#/components/schemas/PaginationParams'
        - type: object
          additionalProperties: true
          properties:
            screenFilters:
              $ref: '#/components/schemas/ScreenFilters'
            freeTextSearch:
              type: string
              description: Free text search query
            sorting:
              $ref: '#/components/schemas/SortingOptions'
    QueryBackendsRequest:
      allOf:
        - $ref: '#/components/schemas/PaginationParams'
        - type: object
          additionalProperties: true
          properties:
            screenFilters:
              $ref: '#/components/schemas/ScreenFilters'
            freeTextSearch:
              type: string
              description: Free text search query
    QueryRepositoriesRequest:
      type: object
      additionalProperties: true
      properties:
        screenFilters:
          $ref: '#/components/schemas/ScreenFilters'
        freeTextSearch:
          type: string
          description: Free text search query
    QueryModulesRequest:
      allOf:
        - $ref: '#/components/schemas/PaginationParams'
        - type: object
          additionalProperties: true
          properties:
            screenFilters:
              type: object
              additionalProperties: true
              description: Module-specific filters
              properties:
                repoFullName:
                  type: array
                  items:
                    type: string
                moduleOriginType:
                  type: array
                  items:
                    type: string
                misconfigurations:
                  type: array
                  items:
                    type: string
            freeTextSearch:
              type: string
              description: Free text search query
            size:
              type: integer
              description: Number of items per page - v1 compatibility alias for pageSize
            sort:
              type: array
              items:
                $ref: '#/components/schemas/SortingOptions'
              description: Sorting configuration
            sortArr:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  sort:
                    type: string
              description: Sorting configuration - v1 compatibility alias for sort
    QueryProvidersRequest:
      type: object
      additionalProperties: true
      properties:
        screenFilters:
          $ref: '#/components/schemas/ScreenFilters'
    SearchIacStacksResponse:
      type: object
      properties:
        hits:
          type: array
          items:
            $ref: '#/components/schemas/IacStack'
          description: List of IaC stacks
        total:
          type: integer
          description: Total number of stacks matching the query
    QueryBackendsResponse:
      type: object
      properties:
        hits:
          type: array
          items:
            $ref: '#/components/schemas/Backend'
          description: List of backends/crawlers
        aggs:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              doc_count:
                type: integer
          description: Aggregations data
        total:
          type: integer
          description: Total number of backends
    QueryModulesResponse:
      type: object
      properties:
        modules:
          type: array
          items:
            $ref: '#/components/schemas/Module'
        total:
          type: integer
          description: Total number of modules
    QueryProvidersResponse:
      type: object
      description: Response containing provider types and URLs aggregations
      properties:
        types:
          allOf:
            - $ref: '#/components/schemas/ProviderAggregation'
          description: Provider types aggregation grouped by type and account
        urls:
          type: object
          description: Provider URLs aggregation
          properties:
            buckets:
              type: array
              items:
                type: object
                properties:
                  key:
                    type: string
                  doc_count:
                    type: integer
  responses:
    BadRequestError:
      description: Bad Request Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Bad Request
    UnauthorizedError:
      description: Unauthorized Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized
    ForbiddenError:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    NotFoundError:
      description: Not Found Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Not Found
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Internal Server Error
    ConflictError:
      description: Conflict Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Conflict
    JsonApiUnauthorizedError:
      description: Unauthorized
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiError'
          example:
            errors:
              - status: '401'
                title: Unauthorized
                detail: The request requires authentication
    JsonApiNotFoundError:
      description: Not found
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiError'
          example:
            errors:
              - status: '404'
                title: Not Found
                detail: The requested resource was not found
    JsonApiConflictError:
      description: Conflict
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiError'
          example:
            errors:
              - status: '409'
                title: Conflict
                detail: The request conflicts with the current state
    JsonApiLockedError:
      description: Already locked
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiError'
          example:
            errors:
              - status: '423'
                title: Locked
                detail: The resource is already locked
    JsonApiInternalServerError:
      description: Internal server error
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiError'
          example:
            errors:
              - status: '500'
                title: Internal Server Error
                detail: An internal server error occurred
  headers:
    X-Total-Count:
      description: The total number of items available
      schema:
        type: integer
        example: 100
    X-Total-Pages:
      description: The total number of pages available
      schema:
        type: integer
        example: 10
x-tagGroups:
  - name: Api Gateway
    tags:
      - Workspaces
  - name: Guardrails API
    tags:
      - Guardrails
  - name: Workspace State API
    tags:
      - Workspace State
  - name: Login API
    tags:
      - Authentication
  - name: VCS API
    tags:
      - VCS
  - name: VCS Events API
    tags:
      - VCS Events
  - name: Projects API
    tags:
      - Projects
  - name: Project Variables API
    tags:
      - projectVariable_other
  - name: Workspace Variables API
    tags:
      - workspaceVariable_other
  - name: Variable Set Variables API
    tags:
      - Variable Sets
  - name: Variable Set Operations API
    tags:
      - Variable Set Operations
  - name: Runners Workspaces API
    tags:
      - Runners Workspaces
  - name: Self-Hosted Runners API
    tags:
      - Self-Hosted Runners
      - self-hosted_other
  - name: OIDC Discovery API
    tags:
      - OIDC Discovery
      - openId-connect_other
  - name: governance
    tags:
      - Governance
  - name: api
    tags:
      - Codification
      - Integrations
      - Config
  - name: Infrastructure API
    tags:
      - Infrastructure
  - name: userService
    tags:
      - User Service
  - name: auditLog
    tags:
      - Audit Log
  - name: backupAndDr
    tags:
      - Backup and DR
  - name: Inventory API
    tags:
      - api_other
  - name: eventCenter
    tags:
      - Event Center
  - name: Terraform Remote Backend API
    tags:
      - Terraform Remote Backend
  - name: Relationships API
    tags:
      - Relationships
  - name: IaC Stacks API
    tags:
      - IaC Stacks
  - name: terralist
    tags:
      - Terralist
