---
openapi: 3.1.0
info:
  title: GPUaaS Public API
  version: 1.0.0-draft
  description: |
    Contract-first public API draft.
    Project context rule:
    - Operations that include `ProjectIdHeader` require `X-Project-ID`.
    - Operations that include `ProjectIdPath` derive project context from path.
    - If an operation carries both path and header project context in future revisions, values must match.
  contact:
    name: GPUaaS Platform Team
    email: platform@gpuaas.local
servers:
- url: http://localhost:8090
  description: Local development
tags:
- name: Health
- name: Auth
- name: Users
- name: Projects
- name: SshKeys
- name: Billing
- name: Payments
- name: Catalog
- name: Nodes
- name: Allocations
- name: AllocationGroups
- name: Storage
- name: Apps
- name: AppArtifacts
- name: V3ReadModels
- name: PlatformReleases
- name: ServiceAccounts
- name: ProjectAccessCredentials
- name: AdminUsers
- name: AdminRoles
- name: AdminAccessCredentials
- name: AdminMaasSites
- name: AdminMaasLifecycle
- name: AdminNodes
- name: AdminSkus
- name: AdminOSImages
- name: AdminApps
- name: AdminAllocations
- name: AdminAudit
- name: AdminPayments
- name: AdminOps
- name: InternalNodes
- name: InternalAppProxy
security:
- bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    nodeBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque-node-internal-token
  parameters:
    XRequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
        maxLength: 128
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 128
    ProjectIdHeader:
      name: X-Project-ID
      in: header
      required: true
      description: Required project context for operations that include this parameter.
        Requests without this header are rejected.
      schema:
        type: string
        format: uuid
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
    PageSize:
      name: page_size
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    BillingFrom:
      name: from
      in: query
      required: false
      schema:
        type: string
        format: date-time
    BillingTo:
      name: to
      in: query
      required: false
      schema:
        type: string
        format: date-time
    BillingUsageSort:
      name: sort
      in: query
      required: false
      schema:
        type: string
        enum:
        - start_time_desc
        - start_time_asc
        - cost_desc
        - cost_asc
        default: start_time_desc
    AllocationIdPath:
      name: allocation_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AllocationGroupIdPath:
      name: allocation_group_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    UserIdPath:
      name: user_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    TenantIdPath:
      name: tenant_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    PlatformRolePath:
      name: role
      in: path
      required: true
      schema:
        type: string
        enum:
        - platform_superadmin
        - platform_ops
        - platform_user
    NodeIdPath:
      name: node_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    MaasSiteIdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    MaasSiteProfileIdPath:
      name: profile_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AccessCredentialIdPath:
      name: credential_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    OnboardingIdPath:
      name: onboarding_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    DecommissionIdPath:
      name: decommission_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SkuPath:
      name: sku
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    OSImageIdPath:
      name: image_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ProjectIdPath:
      name: project_id
      in: path
      required: true
      description: Project context derived from path for project-scoped operations.
      schema:
        type: string
        format: uuid
    OrgIdPath:
      name: org_id
      in: path
      required: true
      description: Tenant context derived from path for tenant-scoped operations.
      schema:
        type: string
        format: uuid
    ServiceAccountIdPath:
      name: service_account_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AppSlugPath:
      name: app_slug
      in: path
      required: true
      schema:
        type: string
        pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
    AppVersionPath:
      name: version
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 64
    AppInstanceIdPath:
      name: app_instance_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    WorkloadIdPath:
      name: workload_id
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 128
    V3TaskIdPath:
      name: task_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    V3StorageBucketIdPath:
      name: bucket_id
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: "^[A-Za-z0-9][A-Za-z0-9:_./-]{0,127}$"
    AppInstanceMemberIdPath:
      name: member_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AppInstanceMemberOperationIdPath:
      name: operation_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AppInstanceRepairOperationIdPath:
      name: repair_operation_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SharedRuntimeIdPath:
      name: shared_runtime_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SharedRuntimeAttachmentIdPath:
      name: attachment_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SharedRuntimeWorkerIdPath:
      name: worker_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SharedRuntimeWorkerOperationIdPath:
      name: operation_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AppArtifactIdPath:
      name: artifact_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SshKeyIdPath:
      name: key_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    InternalNodeIdPath:
      name: node_id
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    InternalTaskIdPath:
      name: task_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    V3StorageGrantIdPath:
      name: grant_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    V3StorageAttachmentIdPath:
      name: attachment_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    V3PlatformSignalKeyPath:
      name: signal_key
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 160
        pattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$"
    V3ProvisioningAttentionKeyPath:
      name: attention_key
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 180
        pattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,179}$"
    V3StorageObjectPathQuery:
      name: path
      in: query
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 1024
  schemas:
    ErrorResponse:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          description: 'Machine-readable error code. Stable across versions. See doc/architecture/Error_Code_Catalog.md
            for the full catalog.

'
          enum:
          - token_missing
          - token_invalid
          - token_expired
          - token_scope_invalid
          - auth_personal_disabled
          - auth_enterprise_required
          - auth_personal_required
          - insufficient_permissions
          - admin_required
          - ownership_required
          - validation_error
          - invalid_request
          - allocation_not_found
          - allocation_not_active
          - allocation_already_releasing
          - allocation_concurrency_limit
          - insufficient_balance
          - sku_unavailable
          - node_not_found
          - node_offline
          - node_in_use
          - node_already_exists
          - user_not_found
          - user_already_exists
          - stripe_signature_invalid
          - refund_window_exceeded
          - storage_object_not_found
          - storage_path_traversal
          - storage_already_exists
          - storage_quota_exceeded
          - sku_not_found
          - app_not_found
          - app_version_not_found
          - app_not_entitled
          - app_instance_not_found
          - app_instance_state_invalid
          - app_instance_quota_exceeded
          - rate_limit_exceeded
          - internal_error
          - upstream_error
          - service_unavailable
        message:
          type: string
        details:
          type: object
          additionalProperties: true
        correlation_id:
          type: string
      required:
      - code
      - message
      - correlation_id
    Pagination:
      type: object
      additionalProperties: false
      properties:
        next_cursor:
          type: string
          nullable: true
        page_size:
          type: integer
      required:
      - next_cursor
      - page_size
    Money:
      type: object
      additionalProperties: false
      properties:
        amount_minor:
          type: integer
          description: Amount in minor units (e.g. cents)
        currency:
          type: string
          pattern: "^[A-Z]{3}$"
          example: USD
      required:
      - amount_minor
      - currency
    HealthResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
      required:
      - ok
    User:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
        role:
          type: string
          enum:
          - user
          - admin
      required:
      - id
      - username
      - role
    PlatformRole:
      type: string
      enum:
      - platform_superadmin
      - platform_ops
      - platform_user
    PlatformCapability:
      type: string
      enum:
      - platform.admin
      - platform.ops.read
      - platform.ops.write
      - platform.ops.runbook.read
      - platform.node.read
      - platform.audit.read
    UserWithBalance:
      allOf:
      - "$ref": "#/components/schemas/User"
      - type: object
        additionalProperties: false
        properties:
          org_id:
            type: string
            format: uuid
            nullable: true
          project_id:
            type: string
            format: uuid
            nullable: true
          org_name:
            type: string
            nullable: true
          project_name:
            type: string
            nullable: true
          platform_roles:
            type: array
            items:
              "$ref": "#/components/schemas/PlatformRole"
          platform_role_source:
            type: string
            enum:
            - users_role
            - bindings
          platform_capabilities:
            type: array
            items:
              "$ref": "#/components/schemas/PlatformCapability"
          balance:
            "$ref": "#/components/schemas/Money"
        required:
        - balance
    Project:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        org_name:
          type: string
        name:
          type: string
        slug:
          type: string
        role:
          type: string
          enum:
          - owner
          - admin
          - member
          - viewer
        is_default:
          type: boolean
        created_at:
          type: string
          format: date-time
      required:
      - id
      - org_id
      - org_name
      - name
      - slug
      - role
      - is_default
      - created_at
    ProjectListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/Project"
      required:
      - items
    CreateProjectRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
      required:
      - name
    CreateProjectResponse:
      type: object
      additionalProperties: false
      properties:
        project:
          "$ref": "#/components/schemas/Project"
      required:
      - project
    UpdateProjectRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
    DeleteProjectResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
        project_id:
          type: string
          format: uuid
      required:
      - ok
      - project_id
    V3ReadModelMeta:
      type: object
      additionalProperties: false
      properties:
        generated_at:
          type: string
          format: date-time
        cache:
          type: string
          enum:
          - hit
          - miss
          - bypass
          - stale
          description: Safe read-model cache state for debugging and tests.
      required:
      - generated_at
      - cache
    V3ShellMode:
      type: string
      enum:
      - user
      - tenant_admin
      - project_admin
      - platform_admin
      - ops
    V3ShellModeOption:
      type: object
      additionalProperties: false
      description: Backend-owned persona mode and default landing route for the v3
        shell.
      properties:
        id:
          "$ref": "#/components/schemas/V3ShellMode"
        label:
          type: string
        default_landing:
          type: string
          description: Absolute frontend route for this mode's default v3 production
            landing page.
        is_active:
          type: boolean
      required:
      - id
      - label
      - default_landing
      - is_active
    V3Region:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
        api_region_code:
          type: string
        label:
          type: string
        is_default:
          type: boolean
        is_available:
          type: boolean
        availability_state:
          type: string
          enum:
          - available
          - planned
          - maintenance
          - disabled
        capacity_scope_hint:
          type: string
          nullable: true
      required:
      - code
      - api_region_code
      - label
      - is_default
      - is_available
      - availability_state
      - capacity_scope_hint
    V3RegionListResponse:
      type: object
      additionalProperties: false
      properties:
        current_region_code:
          type: string
          nullable: true
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3Region"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - current_region_code
      - items
      - meta
    V3ShellContext:
      type: object
      additionalProperties: false
      properties:
        mode:
          "$ref": "#/components/schemas/V3ShellMode"
        available_modes:
          type: array
          items:
            "$ref": "#/components/schemas/V3ShellMode"
        mode_options:
          type: array
          items:
            "$ref": "#/components/schemas/V3ShellModeOption"
        user:
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
              format: uuid
            username:
              type: string
            display_name:
              type: string
          required:
          - id
          - username
          - display_name
        tenant:
          type: object
          additionalProperties: false
          nullable: true
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
          required:
          - id
          - name
        project:
          type: object
          additionalProperties: false
          nullable: true
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            slug:
              type: string
          required:
          - id
          - name
          - slug
        regions:
          type: array
          items:
            "$ref": "#/components/schemas/V3Region"
        balance:
          "$ref": "#/components/schemas/Money"
          nullable: true
        attention:
          type: object
          additionalProperties: false
          properties:
            active_workloads:
              type: integer
              minimum: 0
            needs_action:
              type: integer
              minimum: 0
            active_tasks:
              type: integer
              minimum: 0
            unread_notifications:
              type: integer
              minimum: 0
          required:
          - active_workloads
          - needs_action
          - active_tasks
          - unread_notifications
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - mode
      - available_modes
      - mode_options
      - user
      - tenant
      - project
      - regions
      - balance
      - attention
      - meta
    V3ShellContextResponse:
      type: object
      additionalProperties: false
      properties:
        context:
          "$ref": "#/components/schemas/V3ShellContext"
      required:
      - context
    V3WorkloadKind:
      type: string
      enum:
      - compute
      - jupyter
      - vllm
      - training
      - scheduler
      - kubernetes
      - app
    V3WorkloadStatus:
      type: string
      enum:
      - requested
      - provisioning
      - active
      - idle
      - stopped
      - completed
      - restarting
      - restart_failed
      - releasing
      - released
      - failed
      - release_failed
    V3WorkloadSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        allocation_id:
          type: string
          format: uuid
          nullable: true
        app_instance_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        kind:
          "$ref": "#/components/schemas/V3WorkloadKind"
        status:
          "$ref": "#/components/schemas/V3WorkloadStatus"
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        region_code:
          type: string
          nullable: true
        sku:
          type: string
          nullable: true
        node_id:
          type: string
          format: uuid
          nullable: true
        node_name:
          type: string
          nullable: true
        owner_user_id:
          type: string
          format: uuid
        owner_username:
          type: string
        app_slug:
          type: string
          nullable: true
        app_name:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        active_at:
          type: string
          format: date-time
          nullable: true
        hourly_rate:
          "$ref": "#/components/schemas/Money"
          nullable: true
        accrued_cost:
          "$ref": "#/components/schemas/Money"
          nullable: true
        needs_action:
          type: boolean
          description: Backward-compatible alias for is_actionable. New v3 clients
            should prefer is_actionable.
        action_required:
          type: boolean
          description: True when the workload state represents a recovery condition,
            even if the item has aged into history.
        is_actionable:
          type: boolean
          description: Server-derived actionability flag using control-plane time;
            clients must not recompute actionable_until locally.
        actionable_until:
          type: string
          format: date-time
          nullable: true
          description: Time until which a recovery condition should be shown in live
            attention surfaces. Null means the workload has no time-boxed recovery
            action.
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: Non-null when the row belongs to workload history and is hidden
            from default runtime lists unless include_history=true or an explicit
            status filter is used.
        action_reason:
          type: string
          nullable: true
        primary_action:
          type: string
          enum:
          - open
          - connect
          - open_notebook
          - try_endpoint
          - open_training_ui
          - retry_release
          - review
          - none
        connection_facts:
          "$ref": "#/components/schemas/V3WorkloadConnectionFacts"
        lifecycle_actions:
          type: array
          description: Backend-owned lifecycle affordances for this workload row.
            Clients render these actions and disabled reasons; they must not infer
            lifecycle eligibility from status alone.
          items:
            "$ref": "#/components/schemas/V3WorkloadLifecycleAction"
        operator_state:
          "$ref": "#/components/schemas/V3WorkloadOperatorState"
      required:
      - id
      - allocation_id
      - app_instance_id
      - name
      - kind
      - status
      - project_id
      - project_name
      - region_code
      - sku
      - node_id
      - node_name
      - owner_user_id
      - owner_username
      - app_slug
      - app_name
      - created_at
      - active_at
      - hourly_rate
      - accrued_cost
      - needs_action
      - action_required
      - is_actionable
      - actionable_until
      - archived_at
      - action_reason
      - primary_action
      - connection_facts
      - lifecycle_actions
      - operator_state
    V3WorkloadConnectionFacts:
      type: object
      additionalProperties: false
      description: Copyable connection fields promoted to the workload row so users
        do not need to open a detail page just to find host/IP/SSH/terminal access.
      properties:
        hostname:
          type: string
          nullable: true
        ip_address:
          type: string
          nullable: true
        ssh_command:
          type: string
          nullable: true
        terminal_href:
          type: string
          nullable: true
        app_url:
          type: string
          nullable: true
      required:
      - hostname
      - ip_address
      - ssh_command
      - terminal_href
      - app_url
    V3WorkloadLifecycleAction:
      type: object
      additionalProperties: false
      properties:
        action:
          type: string
          enum:
          - release
          - restart
          - stop
          - start
          - open
        label:
          type: string
        enabled:
          type: boolean
        disabled_reason:
          type: string
          nullable: true
        method:
          type: string
          enum:
          - POST
          - GET
          - none
        href:
          type: string
          nullable: true
        idempotency_required:
          type: boolean
        result:
          "$ref": "#/components/schemas/V3WorkloadLifecycleResultHint"
      required:
      - action
      - label
      - enabled
      - disabled_reason
      - method
      - href
      - idempotency_required
      - result
    V3WorkloadLifecycleResultHint:
      type: object
      additionalProperties: false
      properties:
        task_href:
          type: string
          nullable: true
          description: Stable task pivot if one is already known. Null before a lifecycle
            submission is accepted.
        evidence_href:
          type: string
          nullable: true
          description: Stable evidence pivot if one is already known. Null before
            a lifecycle submission receives its correlation id.
        correlation_id:
          type: string
          nullable: true
      required:
      - task_href
      - evidence_href
      - correlation_id
    V3WorkloadOperatorState:
      type: object
      additionalProperties: false
      description: Backend-owned operator attention and ack/suppression state for
        a workload.
      properties:
        active:
          type: boolean
        attention_key:
          type: string
          nullable: true
          description: Backend-owned attention key. Clients must pass it opaquely
            and never derive it.
        signal_key:
          type: string
          nullable: true
          description: Backend-owned mutation handle for ack/suppression. Clients
            must pass it opaquely and never derive it.
        target_type:
          type: string
        target_id:
          type: string
          nullable: true
        action_family:
          type: string
          nullable: true
        attention_reason:
          type: string
          nullable: true
        review_required:
          type: boolean
        review_state:
          "$ref": "#/components/schemas/V3ProvisioningReviewState"
        ack_fingerprint:
          type: string
          nullable: true
          description: Backend-owned fingerprint for resurface detection. Clients
            must never derive it.
        ack_state:
          "$ref": "#/components/schemas/V3PlatformAckState"
        ack_reason:
          type: string
          nullable: true
        ack_expires_at:
          type: string
          format: date-time
          nullable: true
        ack_actor:
          type: string
          nullable: true
        ack_updated_at:
          type: string
          format: date-time
          nullable: true
      required:
      - active
      - attention_key
      - signal_key
      - target_type
      - target_id
      - action_family
      - attention_reason
      - review_required
      - review_state
      - ack_fingerprint
      - ack_state
      - ack_reason
      - ack_expires_at
      - ack_actor
      - ack_updated_at
    V3WorkloadActionBandItem:
      type: object
      additionalProperties: false
      properties:
        severity:
          type: string
          enum:
          - info
          - warn
          - error
        code:
          type: string
        title:
          type: string
        summary:
          type: string
        workload_id:
          type: string
          minLength: 1
          maxLength: 128
        action_label:
          type: string
        action_href:
          type: string
      required:
      - severity
      - code
      - title
      - summary
      - workload_id
      - action_label
      - action_href
    V3WorkloadListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3WorkloadSummary"
        action_band:
          type: array
          items:
            "$ref": "#/components/schemas/V3WorkloadActionBandItem"
        counts:
          type: object
          additionalProperties: false
          properties:
            active:
              type: integer
              minimum: 0
            provisioning:
              type: integer
              minimum: 0
            needs_action:
              type: integer
              minimum: 0
            released:
              type: integer
              minimum: 0
          required:
          - active
          - provisioning
          - needs_action
          - released
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - action_band
      - counts
      - pagination
      - meta
    V3WorkloadDetailResponse:
      type: object
      additionalProperties: false
      properties:
        workload:
          "$ref": "#/components/schemas/V3WorkloadSummary"
        context:
          type: object
          additionalProperties: false
          properties:
            project:
              type: string
            region:
              type: string
              nullable: true
            node:
              type: string
              nullable: true
            owner:
              type: string
            age_seconds:
              type: integer
              minimum: 0
          required:
          - project
          - region
          - node
          - owner
          - age_seconds
        tabs:
          type: object
          additionalProperties: false
          properties:
            overview:
              type: object
              additionalProperties: true
            connect:
              type: object
              additionalProperties: true
            metrics:
              type: object
              additionalProperties: true
            events:
              type: object
              additionalProperties: true
            storage:
              type: object
              additionalProperties: true
            config:
              type: object
              additionalProperties: true
          required:
          - overview
          - connect
          - metrics
          - events
          - storage
          - config
          "$ref": "#/components/schemas/V3WorkloadDetailTabs"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - workload
      - context
      - tabs
      - meta
    V3TaskStatus:
      type: string
      enum:
      - queued
      - running
      - succeeded
      - failed
      - canceled
      - unknown
    V3TaskResourceKind:
      type: string
      enum:
      - workload
      - allocation
      - app_instance
      - node
      - storage
      - unknown
    V3TaskAction:
      type: object
      additionalProperties: false
      nullable: true
      properties:
        label:
          type: string
        href:
          type: string
        kind:
          type: string
          enum:
          - open_resource
          - retry
          - view_logs
          - none
      required:
      - label
      - href
      - kind
    V3TaskSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - launch
          - release
          - restart
          - lifecycle
          - app_operation
          - unknown
        status:
          "$ref": "#/components/schemas/V3TaskStatus"
        title:
          type: string
        summary:
          type: string
          nullable: true
        resource_kind:
          "$ref": "#/components/schemas/V3TaskResourceKind"
        resource_id:
          type: string
          nullable: true
        resource_name:
          type: string
          nullable: true
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        correlation_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        primary_action:
          "$ref": "#/components/schemas/V3TaskAction"
      required:
      - id
      - kind
      - status
      - title
      - summary
      - resource_kind
      - resource_id
      - resource_name
      - project_id
      - project_name
      - correlation_id
      - created_at
      - updated_at
      - completed_at
      - primary_action
    V3TaskTimelineItem:
      type: object
      additionalProperties: false
      properties:
        kind:
          type: string
          enum:
          - accepted
          - workflow
          - placement
          - node_task
          - completion
          - failure
          - unknown
        name:
          type: string
        status:
          "$ref": "#/components/schemas/V3TaskStatus"
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        duration_seconds:
          type: integer
          minimum: 0
          nullable: true
        summary:
          type: string
          nullable: true
        source:
          type: string
          enum:
          - allocation
          - node_task
          - app_instance
          - synthetic
      required:
      - kind
      - name
      - status
      - started_at
      - completed_at
      - duration_seconds
      - summary
      - source
    V3TaskListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3TaskSummary"
        counts:
          type: object
          additionalProperties: false
          properties:
            queued:
              type: integer
              minimum: 0
            running:
              type: integer
              minimum: 0
            succeeded:
              type: integer
              minimum: 0
            failed:
              type: integer
              minimum: 0
          required:
          - queued
          - running
          - succeeded
          - failed
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - counts
      - pagination
      - meta
    V3TaskDetailResponse:
      type: object
      additionalProperties: false
      properties:
        task:
          "$ref": "#/components/schemas/V3TaskSummary"
        context:
          type: object
          additionalProperties: false
          properties:
            project:
              type: string
            resource_href:
              type: string
              nullable: true
            timeline_source:
              type: string
              enum:
              - allocation_timeline
              - synthetic
          required:
          - project
          - resource_href
          - timeline_source
        timeline:
          type: array
          items:
            "$ref": "#/components/schemas/V3TaskTimelineItem"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - task
      - context
      - timeline
      - meta
    V3ComputeCapacityShape:
      type: string
      enum:
      - baremetal
      - gpu_slice
    V3ComputeAvailabilityState:
      type: string
      enum:
      - available
      - limited
      - unavailable
    V3ComputeResourceClass:
      type: string
      description: 'User-facing SKU resource class. This is broader than capacity_shape:
        it lets the catalog describe future CPU-only and infrastructure classes without
        weakening today''s GPU scheduler invariant that GPU SKUs have a positive gpus_total
        value.

'
      enum:
      - gpu_baremetal
      - gpu_slice
      - cpu_node
      - control_plane
      - storage_optimized
      - accelerator_appliance
    V3ComputeBillingUnit:
      type: string
      enum:
      - gpu_hour
      - node_hour
      - vcpu_hour
      - custom
    V3ComputeSchedulingUnit:
      type: string
      enum:
      - node
      - slice
      - vm
      - container
      - external
    V3ComputeAcceleratorResource:
      type: object
      additionalProperties: false
      properties:
        vendor:
          type: string
        model:
          type: string
          nullable: true
        count:
          type: integer
          minimum: 0
        memory_mib:
          type: integer
          minimum: 0
          nullable: true
        partition_profile:
          type: string
          nullable: true
      required:
      - vendor
      - count
    V3ComputeCPUResource:
      type: object
      additionalProperties: false
      properties:
        vcpu_count:
          type: integer
          minimum: 1
        architecture:
          type: string
          nullable: true
      required:
      - vcpu_count
    V3ComputeMemoryResource:
      type: object
      additionalProperties: false
      properties:
        memory_mib:
          type: integer
          minimum: 1
      required:
      - memory_mib
    V3ComputeStorageResource:
      type: object
      additionalProperties: false
      properties:
        local_storage_mib:
          type: integer
          minimum: 0
        storage_class:
          type: string
          nullable: true
      required:
      - local_storage_mib
    V3ComputeSkuResources:
      type: object
      additionalProperties: false
      properties:
        resource_class:
          "$ref": "#/components/schemas/V3ComputeResourceClass"
        billing_unit:
          "$ref": "#/components/schemas/V3ComputeBillingUnit"
        scheduling_unit:
          "$ref": "#/components/schemas/V3ComputeSchedulingUnit"
        accelerator:
          "$ref": "#/components/schemas/V3ComputeAcceleratorResource"
          nullable: true
        cpu:
          "$ref": "#/components/schemas/V3ComputeCPUResource"
          nullable: true
        memory:
          "$ref": "#/components/schemas/V3ComputeMemoryResource"
          nullable: true
        local_storage:
          "$ref": "#/components/schemas/V3ComputeStorageResource"
          nullable: true
      required:
      - resource_class
      - billing_unit
      - scheduling_unit
    V3ComputeSkuSummary:
      type: object
      additionalProperties: false
      properties:
        sku:
          type: string
        display_name:
          type: string
        vendor:
          type: string
        capacity_shape:
          "$ref": "#/components/schemas/V3ComputeCapacityShape"
        resource_class:
          "$ref": "#/components/schemas/V3ComputeResourceClass"
        resources:
          "$ref": "#/components/schemas/V3ComputeSkuResources"
        gpus_total:
          type: integer
          minimum: 0
        allowed_gpu_counts:
          type: array
          items:
            type: integer
            minimum: 1
        hourly_rate:
          "$ref": "#/components/schemas/Money"
        availability_state:
          "$ref": "#/components/schemas/V3ComputeAvailabilityState"
        available_units:
          type: integer
          minimum: 0
        image_count:
          type: integer
          minimum: 0
        launch_href:
          type: string
      required:
      - sku
      - display_name
      - vendor
      - capacity_shape
      - resource_class
      - resources
      - gpus_total
      - allowed_gpu_counts
      - hourly_rate
      - availability_state
      - available_units
      - image_count
      - launch_href
    V3ComputeImageSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        display_name:
          type: string
        target:
          type: string
          enum:
          - baremetal
          - vm_slice
        driver_strategy:
          type: string
          enum:
          - preinstalled
          - cloud_init
          - none
        compatible_skus:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - active
          - disabled
      required:
      - id
      - slug
      - display_name
      - target
      - driver_strategy
      - compatible_skus
      - status
    V3ComputeCatalogResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3ComputeSkuSummary"
        images:
          type: array
          items:
            "$ref": "#/components/schemas/V3ComputeImageSummary"
        counts:
          type: object
          additionalProperties: false
          properties:
            total:
              type: integer
              minimum: 0
            baremetal:
              type: integer
              minimum: 0
            gpu_slice:
              type: integer
              minimum: 0
            available:
              type: integer
              minimum: 0
          required:
          - total
          - baremetal
          - gpu_slice
          - available
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - images
      - counts
      - pagination
      - meta
    V3LaunchPrecheckSeverity:
      type: string
      enum:
      - ok
      - warn
      - blocker
    V3LaunchPrecheckStatus:
      type: string
      enum:
      - ok
      - warn
      - blocker
      - unknown
    V3LaunchInlineActionKind:
      type: string
      enum:
      - none
      - create_ssh_key
      - create_bucket
      - create_network_policy
      - create_service_account
      - add_funds
      - request_quota
      - select_sku
      - select_image
    V3LaunchPrecheckCheck:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          pattern: "^[a-z0-9][a-z0-9_-]{1,62}$"
        label:
          type: string
        status:
          "$ref": "#/components/schemas/V3LaunchPrecheckStatus"
        severity:
          "$ref": "#/components/schemas/V3LaunchPrecheckSeverity"
        message:
          type: string
        action_label:
          type: string
          nullable: true
        action_href:
          type: string
          nullable: true
        inline_action_kind:
          "$ref": "#/components/schemas/V3LaunchInlineActionKind"
      required:
      - id
      - label
      - status
      - severity
      - message
      - action_label
      - action_href
      - inline_action_kind
    V3LaunchPrecheckEstimate:
      type: object
      additionalProperties: false
      properties:
        hourly_rate:
          "$ref": "#/components/schemas/Money"
          nullable: true
        monthly_estimate:
          "$ref": "#/components/schemas/Money"
          nullable: true
        billing_mode:
          type: string
          enum:
          - on_demand
          - spot
          - reserved
          nullable: true
      required:
      - hourly_rate
      - monthly_estimate
      - billing_mode
    V3ComputeLaunchPrecheckRequest:
      type: object
      additionalProperties: false
      properties:
        sku:
          type: string
          minLength: 1
        capacity_shape:
          "$ref": "#/components/schemas/V3ComputeCapacityShape"
        gpu_count:
          type: integer
          minimum: 1
          nullable: true
        os_image_slug:
          type: string
          nullable: true
        region_code:
          type: string
          nullable: true
        scheduler_type:
          type: string
          enum:
          - bare_metal
          - slurm
          - k8s
          - ray
          nullable: true
        ssh_key_ids:
          type: array
          items:
            type: string
            format: uuid
        storage_bucket_ids:
          type: array
          items:
            type: string
        network_policy_id:
          type: string
          nullable: true
        scheduler_request:
          type: object
          additionalProperties: true
      required:
      - sku
    V3AppLaunchPrecheckRequest:
      type: object
      additionalProperties: false
      properties:
        app_version:
          type: string
          nullable: true
        display_name:
          type: string
          nullable: true
        placement_intent:
          "$ref": "#/components/schemas/AppInstancePlacementIntent"
          nullable: true
        operator_service_account_id:
          type: string
          format: uuid
          nullable: true
        dependencies:
          type: object
          additionalProperties: true
        config:
          type: object
          additionalProperties: true
    V3LaunchPrecheckResponse:
      type: object
      additionalProperties: false
      properties:
        ready:
          type: boolean
        severity:
          "$ref": "#/components/schemas/V3LaunchPrecheckSeverity"
        checks:
          type: array
          items:
            "$ref": "#/components/schemas/V3LaunchPrecheckCheck"
        estimate:
          "$ref": "#/components/schemas/V3LaunchPrecheckEstimate"
        resolved:
          type: object
          additionalProperties: true
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - ready
      - severity
      - checks
      - estimate
      - resolved
      - meta
    V3AppDependency:
      type: string
      enum:
      - ssh
      - storage
      - network
      - service_account
      - api_key
    V3AppKind:
      type: string
      enum:
      - jupyter
      - vllm
      - training
      - vector_db
      - labeling
      - tgi
      - scheduler
      - kubernetes
      - app
    V3AppPublisher:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        tone:
          type: string
          enum:
          - core42
          - project
          - community
      required:
      - name
      - tone
    V3AppEntitlementSummary:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
        reason:
          type: string
          nullable: true
      required:
      - enabled
      - reason
    V3AppRuntimeConfigField:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        type:
          type: string
        description:
          type: string
          nullable: true
        default:
          nullable: true
        enum:
          type: array
          items:
            type: string
      required:
      - name
      - type
      - description
      - default
      - enum
    V3AppRuntimeConfigGroup:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        title:
          type: string
        fields:
          type: array
          items:
            type: string
      required:
      - id
      - title
      - fields
    V3AppRuntimeEndpoint:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        label:
          type: string
        port:
          type: integer
          nullable: true
        protocol:
          type: string
        default_open_path:
          type: string
          nullable: true
        readiness_path:
          type: string
          nullable: true
      required:
      - name
      - label
      - port
      - protocol
      - default_open_path
      - readiness_path
    V3AppRuntimePresentation:
      type: object
      additionalProperties: false
      properties:
        family:
          type: string
        runtime_label:
          type: string
        primary_surface:
          type: string
        target_label:
          type: string
        member_label:
          type: string
          nullable: true
        member_plural_label:
          type: string
          nullable: true
        add_member_label:
          type: string
          nullable: true
        controller_label:
          type: string
          nullable: true
        worker_label:
          type: string
          nullable: true
        config_defaults:
          type: object
          additionalProperties: true
        config_fields:
          type: array
          items:
            "$ref": "#/components/schemas/V3AppRuntimeConfigField"
        config_groups:
          type: array
          items:
            "$ref": "#/components/schemas/V3AppRuntimeConfigGroup"
        endpoints:
          type: array
          items:
            "$ref": "#/components/schemas/V3AppRuntimeEndpoint"
      required:
      - family
      - runtime_label
      - primary_surface
      - target_label
      - member_label
      - member_plural_label
      - add_member_label
      - controller_label
      - worker_label
      - config_defaults
      - config_fields
      - config_groups
      - endpoints
    V3AppCatalogItem:
      type: object
      additionalProperties: false
      properties:
        slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        name:
          type: string
        category:
          type: string
        kind:
          "$ref": "#/components/schemas/V3AppKind"
        publisher:
          "$ref": "#/components/schemas/V3AppPublisher"
        short_description:
          type: string
        long_description:
          type: string
        status:
          type: string
          enum:
          - active
          - deprecated
          - disabled
        version:
          type: string
        versions_available:
          type: array
          items:
            type: string
        primary_surface:
          type: string
        runtime_presentation:
          "$ref": "#/components/schemas/V3AppRuntimePresentation"
        dependencies:
          type: array
          items:
            "$ref": "#/components/schemas/V3AppDependency"
        pricing_hint:
          type: string
        featured:
          type: boolean
        entitlement:
          "$ref": "#/components/schemas/V3AppEntitlementSummary"
        launch_href:
          type: string
        detail_href:
          type: string
      required:
      - slug
      - name
      - category
      - kind
      - publisher
      - short_description
      - long_description
      - status
      - version
      - versions_available
      - primary_surface
      - runtime_presentation
      - dependencies
      - pricing_hint
      - featured
      - entitlement
      - launch_href
      - detail_href
    V3AppVersionSummary:
      type: object
      additionalProperties: false
      properties:
        version:
          type: string
        runtime_backend:
          type: string
          enum:
          - k8s
          - rke2
          - slurm
          - ray
          - bare_metal
        status:
          type: string
          enum:
          - active
          - deprecated
          - disabled
        latest:
          type: boolean
        entitled:
          type: boolean
      required:
      - version
      - runtime_backend
      - status
      - latest
      - entitled
    V3AppCatalogResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3AppCatalogItem"
        featured:
          type: array
          items:
            "$ref": "#/components/schemas/V3AppCatalogItem"
        categories:
          type: array
          items:
            type: string
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - featured
      - categories
      - pagination
      - meta
    V3AppDetailResponse:
      type: object
      additionalProperties: false
      properties:
        app:
          "$ref": "#/components/schemas/V3AppCatalogItem"
        versions:
          type: array
          items:
            "$ref": "#/components/schemas/V3AppVersionSummary"
        permissions:
          type: object
          additionalProperties: false
          properties:
            project_enabled:
              type: boolean
            allowed_versions:
              type: array
              items:
                type: string
            launch_roles:
              type: array
              items:
                type: string
          required:
          - project_enabled
          - allowed_versions
          - launch_roles
        examples:
          type: object
          additionalProperties: false
          properties:
            language:
              type: string
              nullable: true
            code:
              type: string
              nullable: true
          required:
          - language
          - code
        running_workloads:
          type: array
          items:
            "$ref": "#/components/schemas/V3WorkloadSummary"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - app
      - versions
      - permissions
      - examples
      - running_workloads
      - meta
    V3StorageBucketPurpose:
      type: string
      enum:
      - workspace
      - dataset
      - checkpoint
      - artifact
      - generic
    V3StorageFlagSeverity:
      type: string
      enum:
      - info
      - warn
      - error
    V3StorageBackendType:
      type: string
      enum:
      - local_dev
      - weka
      - vast
      - ddn
      - nvme_pool
      - s3_compatible
      - unknown
    V3StorageAccessProtocol:
      type: string
      enum:
      - wekafs
      - posix
      - s3
      - nfs
      - smb
      - csi
    V3StoragePerformanceTier:
      type: string
      enum:
      - standard
      - performance
      - capacity
      - archive
      - unknown
    V3StorageProviderCapability:
      type: object
      additionalProperties: false
      description: 'User-safe storage provider capability hints. This object never
        exposes provider credentials, backend endpoints, mount secrets, cluster IDs,
        or raw volume identifiers.

'
      properties:
        backend_type:
          "$ref": "#/components/schemas/V3StorageBackendType"
        display_name:
          type: string
        performance_tier:
          "$ref": "#/components/schemas/V3StoragePerformanceTier"
        access_protocols:
          type: array
          items:
            type: string
            enum:
            - posix
            - nfs
            - s3
            - smb
            - csi
            - wekafs
        mount_modes:
          type: array
          items:
            type: string
            enum:
            - read_only
            - read_write
            - multi_writer
        multi_attach:
          type: boolean
        encryption:
          type: boolean
        kms_managed:
          type: boolean
        snapshots:
          type: boolean
        versioning:
          type: boolean
        retention:
          type: boolean
        quotas:
          type: boolean
        region_constraints:
          type: array
          items:
            type: string
        fabric_constraints:
          type: array
          items:
            type: string
      required:
      - backend_type
      - display_name
      - performance_tier
      - access_protocols
      - mount_modes
      - multi_attach
      - encryption
      - kms_managed
      - snapshots
      - versioning
      - retention
      - quotas
      - region_constraints
      - fabric_constraints
    V3StorageBucketFlag:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          enum:
          - quota_near_limit
          - unattached
          - failed_mount
          - retention_pending
          - permission_drift
          - lifecycle_drift
        severity:
          "$ref": "#/components/schemas/V3StorageFlagSeverity"
        title:
          type: string
        summary:
          type: string
        action_label:
          type: string
          nullable: true
        action_href:
          type: string
          nullable: true
      required:
      - code
      - severity
      - title
      - summary
      - action_label
      - action_href
    V3StorageBucketUsage:
      type: object
      additionalProperties: false
      properties:
        used_bytes:
          type: integer
          format: int64
          minimum: 0
        quota_bytes:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        percent:
          type: number
          format: double
          minimum: 0
          nullable: true
      required:
      - used_bytes
      - quota_bytes
      - percent
    V3StorageBucketMount:
      type: object
      additionalProperties: false
      properties:
        workload_id:
          type: string
          minLength: 1
          maxLength: 128
        workload_name:
          type: string
        workload_kind:
          "$ref": "#/components/schemas/V3WorkloadKind"
        mount_path:
          type: string
        access_mode:
          type: string
          enum:
          - read_only
          - read_write
        state:
          type: string
          enum:
          - mounted
          - pending
          - failed
          - detached
        mounted_at:
          type: string
          format: date-time
          nullable: true
      required:
      - workload_id
      - workload_name
      - workload_kind
      - mount_path
      - access_mode
      - state
      - mounted_at
    V3StorageAttachmentState:
      type: string
      enum:
      - requested
      - prechecking
      - grant_applying
      - grant_applied
      - mounting
      - mounted
      - failed
      - detaching
      - detached
      - detach_failed
    V3StorageAttachmentAccessMode:
      type: string
      enum:
      - read_only
      - read_write
    V3StorageAttachmentWritePolicy:
      type: string
      enum:
      - single_writer
      - multi_writer
    V3StorageAttachment:
      type: object
      additionalProperties: false
      description: Runtime binding between one project storage namespace and one allocation
        or workload mount. Provider secrets, raw backend mount commands, and cluster
        identifiers are never returned.
      properties:
        id:
          type: string
          format: uuid
        bucket_id:
          type: string
          minLength: 1
          maxLength: 128
        project_id:
          type: string
          format: uuid
        allocation_id:
          type: string
          format: uuid
          nullable: true
        workload_instance_id:
          type: string
          format: uuid
          nullable: true
        node_id:
          type: string
          format: uuid
          nullable: true
        mount_path:
          type: string
          minLength: 1
          maxLength: 256
        access_mode:
          "$ref": "#/components/schemas/V3StorageAttachmentAccessMode"
        write_policy:
          "$ref": "#/components/schemas/V3StorageAttachmentWritePolicy"
        provider_backend:
          "$ref": "#/components/schemas/V3StorageBackendType"
        state:
          "$ref": "#/components/schemas/V3StorageAttachmentState"
        workflow_id:
          type: string
          nullable: true
        failure_code:
          type: string
          nullable: true
        failure_message:
          type: string
          nullable: true
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        requested_at:
          type: string
          format: date-time
        mounted_at:
          type: string
          format: date-time
          nullable: true
        detached_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - bucket_id
      - project_id
      - allocation_id
      - workload_instance_id
      - node_id
      - mount_path
      - access_mode
      - write_policy
      - provider_backend
      - state
      - workflow_id
      - failure_code
      - failure_message
      - requested_by_user_id
      - requested_at
      - mounted_at
      - detached_at
      - updated_at
    V3StorageAttachmentCreateRequest:
      type: object
      additionalProperties: false
      description: Request attachment of one storage namespace to one allocation or
        workload. Exactly one of allocation_id or workload_instance_id must be provided.
      properties:
        allocation_id:
          type: string
          format: uuid
          nullable: true
        workload_instance_id:
          type: string
          format: uuid
          nullable: true
        mount_path:
          type: string
          minLength: 1
          maxLength: 256
        access_mode:
          "$ref": "#/components/schemas/V3StorageAttachmentAccessMode"
        write_policy:
          "$ref": "#/components/schemas/V3StorageAttachmentWritePolicy"
          nullable: true
      required:
      - allocation_id
      - workload_instance_id
      - mount_path
      - access_mode
      - write_policy
    V3StorageAttachmentResponse:
      type: object
      additionalProperties: false
      properties:
        attachment:
          "$ref": "#/components/schemas/V3StorageAttachment"
        evidence:
          "$ref": "#/components/schemas/V3MutationEvidence"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - attachment
      - meta
    V3StorageAttachmentListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3StorageAttachment"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - pagination
      - meta
    V3StorageAccessAudience:
      type: object
      additionalProperties: false
      properties:
        kind:
          type: string
          enum:
          - project_members
          - service_accounts
          - workload_bound
        label:
          type: string
        count:
          type: integer
          minimum: 0
        drift_count:
          type: integer
          minimum: 0
        summary:
          type: string
      required:
      - kind
      - label
      - count
      - drift_count
      - summary
    V3StorageLifecycleSummary:
      type: object
      additionalProperties: false
      properties:
        retention_policy:
          type: string
          enum:
          - keep_forever
          - delete_after_30d
          - delete_after_90d
          - scheduled_delete
        versioning_enabled:
          type: boolean
        auto_snapshot_enabled:
          type: boolean
        scheduled_delete_at:
          type: string
          format: date-time
          nullable: true
      required:
      - retention_policy
      - versioning_enabled
      - auto_snapshot_enabled
      - scheduled_delete_at
    V3StorageObjectPreview:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
        kind:
          type: string
          enum:
          - prefix
          - object
        size_bytes:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
      required:
      - key
      - kind
      - size_bytes
      - updated_at
    V3StorageBucketSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        name:
          type: string
        status:
          type: string
          enum:
          - creating
          - active
          - failed
          - deleting
          - deleted
        purpose:
          "$ref": "#/components/schemas/V3StorageBucketPurpose"
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        owner_user_id:
          type: string
          format: uuid
          nullable: true
        owner_username:
          type: string
          nullable: true
        region_code:
          type: string
          nullable: true
        provider:
          "$ref": "#/components/schemas/V3StorageProviderCapability"
        access_protocol:
          "$ref": "#/components/schemas/V3StorageAccessProtocol"
        encryption:
          type: string
          enum:
          - project_default
          - kms_managed
          - unknown
        usage:
          "$ref": "#/components/schemas/V3StorageBucketUsage"
        mounted_workloads:
          type: array
          items:
            "$ref": "#/components/schemas/V3StorageBucketMount"
        flags:
          type: array
          items:
            "$ref": "#/components/schemas/V3StorageBucketFlag"
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - name
      - status
      - purpose
      - project_id
      - project_name
      - owner_user_id
      - owner_username
      - region_code
      - provider
      - access_protocol
      - encryption
      - usage
      - mounted_workloads
      - flags
      - created_at
      - updated_at
    V3StorageBucketCreateRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
          pattern: "^[A-Za-z0-9][A-Za-z0-9:_-]{0,127}$"
        purpose:
          "$ref": "#/components/schemas/V3StorageBucketPurpose"
        access_protocol:
          "$ref": "#/components/schemas/V3StorageAccessProtocol"
          description: Primary access protocol requested for this storage object.
            Omitted requests default to WEKAFS/POSIX for the first production WEKA
            path.
        quota_gb:
          type: integer
          minimum: 1
          maximum: 1048576
          nullable: true
        encryption:
          type: string
          enum:
          - project_default
          - kms_managed
        retention:
          type: string
          enum:
          - keep_forever
          - keep_30d
          - keep_90d
          - scheduled_delete
        access_audience:
          type: string
          enum:
          - project_members
          - service_accounts
          - workload_bound
        service_account_id:
          type: string
          nullable: true
        mount_intent:
          type: string
          maxLength: 256
          nullable: true
      required:
      - name
      - purpose
      - quota_gb
      - encryption
      - retention
      - access_audience
      - service_account_id
      - mount_intent
    V3StorageBucketCreateResponse:
      type: object
      additionalProperties: false
      properties:
        bucket:
          "$ref": "#/components/schemas/V3StorageBucketSummary"
        open_href:
          type: string
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - bucket
      - open_href
      - meta
    V3StorageBucketUpdateRequest:
      type: object
      additionalProperties: false
      properties:
        purpose:
          "$ref": "#/components/schemas/V3StorageBucketPurpose"
        access_protocol:
          "$ref": "#/components/schemas/V3StorageAccessProtocol"
        quota_gb:
          type: integer
          minimum: 1
          maximum: 1048576
          nullable: true
        encryption:
          type: string
          enum:
          - project_default
          - kms_managed
        retention:
          type: string
          enum:
          - keep_forever
          - keep_30d
          - keep_90d
          - scheduled_delete
        access_audience:
          type: string
          enum:
          - project_members
          - service_accounts
          - workload_bound
        service_account_id:
          type: string
          nullable: true
        mount_intent:
          type: string
          maxLength: 256
          nullable: true
    V3StorageBucketArchiveRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          maxLength: 256
          nullable: true
    V3StorageBucketMutationEvidence:
      type: object
      additionalProperties: false
      properties:
        correlation_id:
          type: string
        audit_action:
          type: string
          enum:
          - storage.bucket.update
          - storage.bucket.archive
          - storage.bucket.delete
        project_id:
          type: string
          format: uuid
        bucket_id:
          type: string
      required:
      - correlation_id
      - audit_action
      - project_id
      - bucket_id
    V3MutationEvidence:
      type: object
      additionalProperties: false
      description: Durable user/operator pivot for a completed V3 mutation. It is
        safe to show in the UI and link to evidence/audit surfaces; it must never
        contain raw provider payloads or secrets.
      properties:
        correlation_id:
          type: string
        audit_action:
          type: string
        evidence_href:
          type: string
          nullable: true
        task_href:
          type: string
          nullable: true
        operation_id:
          type: string
          nullable: true
        target_type:
          type: string
        target_id:
          type: string
      required:
      - correlation_id
      - audit_action
      - evidence_href
      - task_href
      - operation_id
      - target_type
      - target_id
    V3StorageBucketMutationResponse:
      type: object
      additionalProperties: false
      properties:
        bucket:
          "$ref": "#/components/schemas/V3StorageBucketSummary"
        evidence:
          "$ref": "#/components/schemas/V3StorageBucketMutationEvidence"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - bucket
      - evidence
      - meta
    V3StorageActionBandItem:
      type: object
      additionalProperties: false
      properties:
        severity:
          "$ref": "#/components/schemas/V3StorageFlagSeverity"
        code:
          type: string
        title:
          type: string
        summary:
          type: string
        bucket_id:
          type: string
          minLength: 1
          maxLength: 128
        action_label:
          type: string
        action_href:
          type: string
      required:
      - severity
      - code
      - title
      - summary
      - bucket_id
      - action_label
      - action_href
    V3StorageBucketListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3StorageBucketSummary"
        action_band:
          type: array
          items:
            "$ref": "#/components/schemas/V3StorageActionBandItem"
        counts:
          type: object
          additionalProperties: false
          properties:
            total:
              type: integer
              minimum: 0
            attached:
              type: integer
              minimum: 0
            unattached:
              type: integer
              minimum: 0
            flagged:
              type: integer
              minimum: 0
            total_used_bytes:
              type: integer
              format: int64
              minimum: 0
            total_quota_bytes:
              type: integer
              format: int64
              minimum: 0
              nullable: true
          required:
          - total
          - attached
          - unattached
          - flagged
          - total_used_bytes
          - total_quota_bytes
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - action_band
      - counts
      - pagination
      - meta
    V3StorageBucketDetailResponse:
      type: object
      additionalProperties: false
      properties:
        bucket:
          "$ref": "#/components/schemas/V3StorageBucketSummary"
        context:
          type: object
          additionalProperties: false
          properties:
            purpose:
              "$ref": "#/components/schemas/V3StorageBucketPurpose"
            project:
              type: string
            owner:
              type: string
              nullable: true
            encryption:
              type: string
              enum:
              - project_default
              - kms_managed
              - unknown
            usage_percent:
              type: number
              format: double
              minimum: 0
              nullable: true
            created_at:
              type: string
              format: date-time
              nullable: true
          required:
          - purpose
          - project
          - owner
          - encryption
          - usage_percent
          - created_at
        tabs:
          type: object
          additionalProperties: false
          properties:
            overview:
              type: object
              additionalProperties: false
              properties:
                flags:
                  type: array
                  items:
                    "$ref": "#/components/schemas/V3StorageBucketFlag"
                access:
                  type: array
                  items:
                    "$ref": "#/components/schemas/V3StorageAccessAudience"
                lifecycle:
                  "$ref": "#/components/schemas/V3StorageLifecycleSummary"
              required:
              - flags
              - access
              - lifecycle
            objects:
              type: object
              additionalProperties: false
              properties:
                items:
                  type: array
                  items:
                    "$ref": "#/components/schemas/V3StorageObjectPreview"
              required:
              - items
            mounts:
              type: object
              additionalProperties: false
              properties:
                items:
                  type: array
                  items:
                    "$ref": "#/components/schemas/V3StorageBucketMount"
              required:
              - items
            access:
              type: object
              additionalProperties: false
              properties:
                audiences:
                  type: array
                  items:
                    "$ref": "#/components/schemas/V3StorageAccessAudience"
              required:
              - audiences
            lifecycle:
              "$ref": "#/components/schemas/V3StorageLifecycleSummary"
            events:
              type: object
              additionalProperties: false
              properties:
                items:
                  type: array
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      occurred_at:
                        type: string
                        format: date-time
                      actor:
                        type: string
                        nullable: true
                      action:
                        type: string
                      summary:
                        type: string
                    required:
                    - occurred_at
                    - actor
                    - action
                    - summary
              required:
              - items
          required:
          - overview
          - objects
          - mounts
          - access
          - lifecycle
          - events
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - bucket
      - context
      - tabs
      - meta
    V3AccessSeverity:
      type: string
      enum:
      - info
      - warn
      - error
    V3AccessSubjectKind:
      type: string
      enum:
      - user
      - service_account
      - workload
      - platform_role
      - identity_provider
    V3AccessDriftItem:
      type: object
      additionalProperties: false
      properties:
        severity:
          "$ref": "#/components/schemas/V3AccessSeverity"
        code:
          type: string
          enum:
          - expiring_credential
          - stale_member
          - policy_mismatch
          - entitlement_drift
          - missing_owner
          - provider_link_required
        title:
          type: string
        summary:
          type: string
        subject_kind:
          "$ref": "#/components/schemas/V3AccessSubjectKind"
        subject_id:
          type: string
        action_label:
          type: string
          nullable: true
        action_href:
          type: string
          nullable: true
      required:
      - severity
      - code
      - title
      - summary
      - subject_kind
      - subject_id
      - action_label
      - action_href
    V3AccessMembershipRow:
      type: object
      additionalProperties: false
      properties:
        user_id:
          type: string
          format: uuid
        username:
          type: string
        display_name:
          type: string
        tenant_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - billing_viewer
          nullable: true
        project_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - viewer
          nullable: true
        access_source:
          type: string
          enum:
          - project_role
          - tenant_role
          - explicit
          - platform_role
          x-enum-varnames:
          - V3AccessMembershipRowAccessSourceProjectRole
          - V3AccessMembershipRowAccessSourceTenantRole
          - V3AccessMembershipRowAccessSourceExplicit
          - V3AccessMembershipRowAccessSourcePlatformRole
        last_seen_at:
          type: string
          format: date-time
          nullable: true
        drift:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessDriftItem"
      required:
      - user_id
      - username
      - display_name
      - tenant_role
      - project_role
      - access_source
      - last_seen_at
      - drift
    V3AccessServiceAccountRow:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        status:
          type: string
          enum:
          - active
          - disabled
        scopes:
          type: array
          items:
            type: string
        used_by_workloads:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              workload_id:
                type: string
              workload_name:
                type: string
            required:
            - workload_id
            - workload_name
        key_age_days:
          type: integer
          minimum: 0
          nullable: true
        rotation_due_at:
          type: string
          format: date-time
          nullable: true
        drift:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessDriftItem"
      required:
      - id
      - name
      - project_id
      - project_name
      - status
      - scopes
      - used_by_workloads
      - key_age_days
      - rotation_due_at
      - drift
    V3AccessCredentialRow:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
          - ssh_key
          - personal_api_key
          - service_account_key
          - workload_api_key
        subject_kind:
          "$ref": "#/components/schemas/V3AccessSubjectKind"
        subject_id:
          type: string
        label:
          type: string
        fingerprint:
          type: string
          nullable: true
        last_used_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum:
          - active
          - expiring
          - expired
          - disabled
          - revoked
        managed_in:
          type: string
          enum:
          - account
          - access
          - platform
      required:
      - id
      - kind
      - subject_kind
      - subject_id
      - label
      - fingerprint
      - last_used_at
      - expires_at
      - status
      - managed_in
    V3AccessEntitlementRow:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
          - app
          - sku
          - region
        name:
          type: string
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        enabled:
          type: boolean
        allowed_versions:
          type: array
          items:
            type: string
        limits:
          type: object
          additionalProperties: true
        drift:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessDriftItem"
      required:
      - id
      - kind
      - name
      - project_id
      - project_name
      - enabled
      - allowed_versions
      - limits
      - drift
    V3AccessAuditEvent:
      type: object
      additionalProperties: false
      description: Access-family lifecycle/audit event scoped to the active tenant/project
        context.
      properties:
        id:
          type: string
        occurred_at:
          type: string
          format: date-time
        source:
          type: string
          enum:
          - membership
          - service_account
          - credential
          - entitlement
          - identity
          - connectivity
          - audit
        action:
          type: string
        status:
          type: string
          enum:
          - success
          - failure
        severity:
          "$ref": "#/components/schemas/V3AccessSeverity"
        actor:
          type: string
        subject:
          type: string
        target_type:
          type: string
        target_id:
          type: string
          nullable: true
        summary:
          type: string
        correlation_id:
          type: string
        href:
          type: string
          nullable: true
      required:
      - id
      - occurred_at
      - source
      - action
      - status
      - severity
      - actor
      - subject
      - target_type
      - target_id
      - summary
      - correlation_id
      - href
    V3AccessOperation:
      type: object
      additionalProperties: false
      description: Server-owned operation affordance for V3 access lifecycle actions.
        Row-scoped operations use templated hrefs and are disabled until the UI supplies
        the selected target.
      properties:
        key:
          type: string
        source:
          type: string
          enum:
          - membership
          - service_account
          - credential
          - entitlement
          - identity
          - connectivity
        label:
          type: string
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
        href:
          type: string
        target_type:
          type: string
        target_id:
          type: string
          nullable: true
        enabled:
          type: boolean
        disabled_reason:
          type: string
          nullable: true
        danger:
          type: string
          enum:
          - safe
          - low
          - medium
          - high
          - destructive
        audit_action:
          type: string
        result:
          type: string
        latest_actor:
          type: string
          nullable: true
        latest_at:
          type: string
          format: date-time
          nullable: true
        evidence_href:
          type: string
          nullable: true
      required:
      - key
      - source
      - label
      - method
      - href
      - target_type
      - target_id
      - enabled
      - disabled_reason
      - danger
      - audit_action
      - result
      - latest_actor
      - latest_at
      - evidence_href
    V3AccessOverviewResponse:
      type: object
      additionalProperties: false
      properties:
        counts:
          type: object
          additionalProperties: false
          properties:
            members:
              type: integer
              minimum: 0
            service_accounts:
              type: integer
              minimum: 0
            credentials:
              type: integer
              minimum: 0
            entitlements:
              type: integer
              minimum: 0
            drift:
              type: integer
              minimum: 0
          required:
          - members
          - service_accounts
          - credentials
          - entitlements
          - drift
        drift:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessDriftItem"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - counts
      - drift
      - meta
    V3AccessMembershipListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessMembershipRow"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessOperation"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - pagination
      - operations
      - meta
    V3AccessServiceAccountListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessServiceAccountRow"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessOperation"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - pagination
      - operations
      - meta
    V3AccessCredentialListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessCredentialRow"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessOperation"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - pagination
      - operations
      - meta
    V3AccessEntitlementListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessEntitlementRow"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessOperation"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - pagination
      - operations
      - meta
    V3AccessAuditEventListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessAuditEvent"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - pagination
      - meta
    V3AccountAttentionItem:
      type: object
      additionalProperties: false
      properties:
        severity:
          type: string
          enum:
          - info
          - warn
          - error
        code:
          type: string
          enum:
          - missing_mfa
          - stale_ssh_key
          - expiring_api_key
          - duplicate_identity_candidate
          - unfamiliar_session
        title:
          type: string
        summary:
          type: string
        action_label:
          type: string
          nullable: true
        action_href:
          type: string
          nullable: true
      required:
      - severity
      - code
      - title
      - summary
      - action_label
      - action_href
    V3AccountLinkedIdentity:
      type: object
      additionalProperties: false
      properties:
        provider:
          type: string
          enum:
          - password
          - keycloak
          - github
          - huggingface
          - google
          - microsoft
          - saml
          - oidc
        subject:
          type: string
        display_label:
          type: string
        email:
          type: string
          nullable: true
        linked_at:
          type: string
          format: date-time
          nullable: true
        is_primary:
          type: boolean
        status:
          type: string
          enum:
          - linked
          - pending
          - duplicate_candidate
          - disabled
      required:
      - provider
      - subject
      - display_label
      - email
      - linked_at
      - is_primary
      - status
    V3AccountProfile:
      type: object
      additionalProperties: false
      properties:
        user_id:
          type: string
          format: uuid
        username:
          type: string
        display_name:
          type: string
        email:
          type: string
          nullable: true
        tenant_id:
          type: string
          format: uuid
          nullable: true
        tenant_name:
          type: string
          nullable: true
        default_project_id:
          type: string
          format: uuid
          nullable: true
        default_project_name:
          type: string
          nullable: true
        joined_at:
          type: string
          format: date-time
          nullable: true
        linked_identities:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccountLinkedIdentity"
      required:
      - user_id
      - username
      - display_name
      - email
      - tenant_id
      - tenant_name
      - default_project_id
      - default_project_name
      - joined_at
      - linked_identities
    V3AccountCredentialSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
          - ssh_key
          - personal_api_key
        label:
          type: string
        fingerprint:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - active
          - expiring
          - expired
          - revoked
        created_at:
          type: string
          format: date-time
          nullable: true
        last_used_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
        attached_workloads:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              workload_id:
                type: string
              workload_name:
                type: string
            required:
            - workload_id
            - workload_name
      required:
      - id
      - kind
      - label
      - fingerprint
      - status
      - created_at
      - last_used_at
      - expires_at
      - attached_workloads
    V3AccountSession:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        device_label:
          type: string
        browser:
          type: string
          nullable: true
        os:
          type: string
          nullable: true
        ip_address:
          type: string
          nullable: true
        location_label:
          type: string
          nullable: true
        auth_provider:
          type: string
          enum:
          - oidc
          - personal_token
          - service_account
          - password
          - unknown
        signed_in_at:
          type: string
          format: date-time
          nullable: true
        last_seen_at:
          type: string
          format: date-time
          nullable: true
        is_current:
          type: boolean
        risk:
          type: string
          enum:
          - normal
          - attention
          - high
        status:
          type: string
          enum:
          - active
          - expired
          - revoked
        expires_at:
          type: string
          format: date-time
          nullable: true
        revoked_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - device_label
      - browser
      - os
      - ip_address
      - location_label
      - auth_provider
      - signed_in_at
      - last_seen_at
      - is_current
      - risk
      - status
      - expires_at
      - revoked_at
    V3AccountOperation:
      type: object
      additionalProperties: false
      description: Server-owned operation affordance for V3 account security lifecycle
        actions. Row-scoped operations use templated hrefs and are disabled until
        the UI supplies the selected target.
      properties:
        key:
          type: string
        source:
          type: string
          enum:
          - credential
          - session
          - mfa
          - identity
        label:
          type: string
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
        href:
          type: string
        target_type:
          type: string
        target_id:
          type: string
          nullable: true
        enabled:
          type: boolean
        disabled_reason:
          type: string
          nullable: true
        danger:
          type: string
          enum:
          - safe
          - low
          - medium
          - high
          - destructive
        audit_action:
          type: string
        result:
          type: string
        latest_actor:
          type: string
          nullable: true
        latest_at:
          type: string
          format: date-time
          nullable: true
        evidence_href:
          type: string
          nullable: true
      required:
      - key
      - source
      - label
      - method
      - href
      - target_type
      - target_id
      - enabled
      - disabled_reason
      - danger
      - audit_action
      - result
      - latest_actor
      - latest_at
      - evidence_href
    V3AccountSessionRevokeRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          nullable: true
          maxLength: 512
    V3AccountSessionRevokeResponse:
      type: object
      additionalProperties: false
      properties:
        revoked_count:
          type: integer
          minimum: 0
        session_id:
          type: string
          nullable: true
        evidence:
          "$ref": "#/components/schemas/V3MutationEvidence"
      required:
      - revoked_count
      - session_id
      - evidence
    V3AccountOverviewResponse:
      type: object
      additionalProperties: false
      properties:
        profile:
          "$ref": "#/components/schemas/V3AccountProfile"
        counts:
          type: object
          additionalProperties: false
          properties:
            ssh_keys:
              type: integer
              minimum: 0
            personal_api_keys:
              type: integer
              minimum: 0
            active_sessions:
              type: integer
              minimum: 0
            linked_identities:
              type: integer
              minimum: 0
          required:
          - ssh_keys
          - personal_api_keys
          - active_sessions
          - linked_identities
        attention:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccountAttentionItem"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - profile
      - counts
      - attention
      - meta
    V3AccountProfileResponse:
      type: object
      additionalProperties: false
      properties:
        profile:
          "$ref": "#/components/schemas/V3AccountProfile"
        duplicate_identity_candidates:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccountLinkedIdentity"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - profile
      - duplicate_identity_candidates
      - meta
    V3AccountSecurityResponse:
      type: object
      additionalProperties: false
      properties:
        credentials:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccountCredentialSummary"
        mfa:
          type: object
          additionalProperties: false
          properties:
            totp_enabled:
              type: boolean
            webauthn_enabled:
              type: boolean
          required:
          - totp_enabled
          - webauthn_enabled
        attention:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccountAttentionItem"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccountOperation"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - credentials
      - mfa
      - attention
      - operations
      - meta
    V3AccountSessionListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccountSession"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccountOperation"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - operations
      - meta
    AdminBindUserPlatformRoleRequest:
      type: object
      additionalProperties: false
      properties:
        role:
          type: string
          enum:
          - platform_superadmin
          - platform_ops
          - platform_user
      required:
      - role
    AdminUserPlatformRoleListResponse:
      type: object
      additionalProperties: false
      properties:
        user_id:
          type: string
          format: uuid
        items:
          type: array
          items:
            type: string
            enum:
            - platform_superadmin
            - platform_ops
            - platform_user
      required:
      - user_id
      - items
    AdminUserPlatformRoleMutationResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
        user_id:
          type: string
          format: uuid
        role:
          type: string
          enum:
          - platform_superadmin
          - platform_ops
          - platform_user
      required:
      - ok
      - user_id
      - role
    AdminBindUserMembershipRequest:
      type: object
      additionalProperties: false
      properties:
        user_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        tenant_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - billing_viewer
        project_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - viewer
        mode:
          type: string
          enum:
          - strict
          - rehome
          default: strict
          description: |
            strict rejects when user already has an active tenant membership on a different tenant.
            rehome soft-deletes active tenant/project memberships first, then assigns the requested bindings.
        reason:
          type: string
          maxLength: 256
          nullable: true
      required:
      - user_id
      - project_id
      - tenant_role
      - project_role
    MembershipBindingSummary:
      type: object
      additionalProperties: false
      properties:
        tenant_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        tenant_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - billing_viewer
        project_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - viewer
      required:
      - tenant_id
      - project_id
      - user_id
      - tenant_role
      - project_role
    AdminBindUserMembershipResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
        mode:
          type: string
          enum:
          - strict
          - rehome
        rehomed:
          type: boolean
        binding:
          "$ref": "#/components/schemas/MembershipBindingSummary"
      required:
      - ok
      - mode
      - rehomed
      - binding
    V3RemoveAccessMembershipRequest:
      type: object
      additionalProperties: false
      properties:
        project_id:
          type: string
          format: uuid
          description: Project membership to remove, or an anchor project in the tenant
            when scope is tenant.
        scope:
          type: string
          enum:
          - project
          - tenant
          default: project
          description: project removes only the selected project membership; tenant
            removes tenant membership plus all project memberships in the tenant.
        reason:
          type: string
          maxLength: 256
          nullable: true
      required:
      - project_id
    V3AccessMembershipRemovalEvidence:
      type: object
      additionalProperties: false
      properties:
        correlation_id:
          type: string
        audit_action:
          type: string
          enum:
          - tenant.user.membership.remove
        target_user_id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
      required:
      - correlation_id
      - audit_action
      - target_user_id
      - tenant_id
      - project_id
    V3RemoveAccessMembershipResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
        scope:
          type: string
          enum:
          - project
          - tenant
        removed:
          type: boolean
          description: False when the request was already satisfied by a prior removal.
        removed_project_memberships:
          type: integer
          format: int64
          minimum: 0
        removed_tenant_membership:
          type: integer
          format: int64
          minimum: 0
        evidence:
          "$ref": "#/components/schemas/V3AccessMembershipRemovalEvidence"
      required:
      - ok
      - scope
      - removed
      - removed_project_memberships
      - removed_tenant_membership
      - evidence
    AdminTenantSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - personal
          - enterprise
        name:
          type: string
        slug:
          type: string
        created_at:
          type: string
          format: date-time
      required:
      - id
      - type
      - name
      - slug
      - created_at
    AdminTenantListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AdminTenantSummary"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AdminTenantProjectSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        created_at:
          type: string
          format: date-time
      required:
      - id
      - org_id
      - name
      - slug
      - created_at
    AdminTenantProjectListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AdminTenantProjectSummary"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    TenantMemberSummary:
      type: object
      additionalProperties: false
      properties:
        user_id:
          type: string
          format: uuid
        username:
          type: string
        tenant_id:
          type: string
          format: uuid
        tenant_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - billing_viewer
        project_id:
          type: string
          format: uuid
          nullable: true
        project_name:
          type: string
          nullable: true
        project_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - viewer
          nullable: true
      required:
      - user_id
      - username
      - tenant_id
      - tenant_role
    TenantMemberListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/TenantMemberSummary"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    TenantBindUserMembershipRequest:
      type: object
      additionalProperties: false
      properties:
        project_id:
          type: string
          format: uuid
        tenant_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - billing_viewer
          default: member
        project_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - viewer
          default: member
      required:
      - project_id
    TenantCreateUserRequest:
      type: object
      additionalProperties: false
      properties:
        username:
          type: string
          minLength: 1
        password:
          type: string
          minLength: 8
          description: Dev/local credential for tenant-managed account creation.
        project_id:
          type: string
          format: uuid
        tenant_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - billing_viewer
          default: member
        project_role:
          type: string
          enum:
          - owner
          - admin
          - member
          - viewer
          default: member
      required:
      - username
      - password
      - project_id
    SshPublicKey:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        owner_scope:
          type: string
          enum:
          - user
          - project
          description: Ownership scope for the registered SSH public key.
        user_id:
          type: string
          format: uuid
          nullable: true
        project_id:
          type: string
          format: uuid
          nullable: true
        created_by_service_account_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        public_key:
          type: string
        fingerprint:
          type: string
        is_default:
          type: boolean
          description: If true, this key is used by default for new allocations when
            no per-allocation override is provided. Only valid for user-scoped keys.
        last_used_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - owner_scope
      - name
      - public_key
      - fingerprint
      - is_default
      - created_at
    SshPublicKeyRef:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        fingerprint:
          type: string
      required:
      - id
      - name
      - fingerprint
    SshPublicKeyListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/SshPublicKey"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    CreateSshPublicKeyRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
        public_key:
          type: string
          minLength: 32
        set_as_default:
          type: boolean
          default: false
          description: If true, promotes this key to default for future allocations.
            Only supported for user-scoped keys.
      required:
      - name
      - public_key
    CreateSshPublicKeyResponse:
      type: object
      additionalProperties: false
      properties:
        key:
          "$ref": "#/components/schemas/SshPublicKey"
      required:
      - key
    OidcAuthorizeResponse:
      type: object
      additionalProperties: false
      properties:
        authorization_url:
          type: string
          format: uri
        state:
          type: string
        pkce_required:
          type: boolean
          default: true
        org_id:
          type: string
          format: uuid
          nullable: true
          description: 'Resolved tenant context for federation-aware authorize flows
            when deterministically known.

'
      required:
      - authorization_url
      - state
      - pkce_required
    OidcExchangeRequest:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          minLength: 8
        code_verifier:
          type: string
          minLength: 32
        redirect_uri:
          type: string
          format: uri
        state:
          type: string
          minLength: 8
          description: Opaque callback state returned from authorize flow.
      required:
      - code
      - code_verifier
      - redirect_uri
      - state
    AuthSessionResponse:
      type: object
      additionalProperties: false
      properties:
        access_token:
          type: string
        expires_in_seconds:
          type: integer
          minimum: 1
        refresh_token:
          type: string
          nullable: true
        account_type:
          "$ref": "#/components/schemas/AccountType"
        org_id:
          type: string
          format: uuid
          description: Resolved tenant context included in issued token/session.
        user:
          "$ref": "#/components/schemas/UserWithBalance"
      required:
      - access_token
      - expires_in_seconds
      - account_type
      - org_id
      - user
    OidcExchangeResponse:
      allOf:
      - "$ref": "#/components/schemas/AuthSessionResponse"
      description: Compatibility alias for auth session response (retained for codegen/protocol
        naming continuity).
    IdentityProviderType:
      type: string
      enum:
      - oidc
      - saml
      - social
    IdentityLinkState:
      type: string
      enum:
      - active
      - pending_conflict
      - revoked
    IdentityLinkProof:
      type: string
      enum:
      - current_session
      - admin_approval
      - invite
    UserIdentityLink:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        provider_type:
          "$ref": "#/components/schemas/IdentityProviderType"
        provider_name:
          type: string
          minLength: 1
        issuer:
          type: string
          minLength: 1
        subject_hint:
          type: string
          description: Redacted provider subject hint for user display; never a raw
            token.
        external_username:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true
        email_verified:
          type: boolean
        state:
          "$ref": "#/components/schemas/IdentityLinkState"
        is_primary:
          type: boolean
        created_at:
          type: string
          format: date-time
      required:
      - id
      - user_id
      - provider_type
      - provider_name
      - issuer
      - subject_hint
      - email_verified
      - state
      - is_primary
      - created_at
    UserIdentityLinkListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/UserIdentityLink"
      required:
      - items
    CreateIdentityLinkRequest:
      type: object
      additionalProperties: false
      properties:
        provider_type:
          "$ref": "#/components/schemas/IdentityProviderType"
        provider_name:
          type: string
          minLength: 1
        issuer:
          type: string
          minLength: 1
        subject:
          type: string
          minLength: 1
          description: Provider subject from a verified callback or approved recovery
            flow.
        external_username:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true
        email_verified:
          type: boolean
          default: false
        proof:
          "$ref": "#/components/schemas/IdentityLinkProof"
      required:
      - provider_type
      - provider_name
      - issuer
      - subject
      - proof
    CreateIdentityLinkResponse:
      type: object
      additionalProperties: false
      properties:
        link:
          "$ref": "#/components/schemas/UserIdentityLink"
      required:
      - link
    SamlAuthorizeResponse:
      type: object
      additionalProperties: false
      properties:
        redirect_url:
          type: string
          format: uri
        state:
          type: string
          description: Opaque state token that must be forwarded as `RelayState` in
            SAML flow and echoed back to callback.
        protocol:
          type: string
          enum:
          - saml
        org_id:
          type: string
          format: uuid
          nullable: true
          description: Resolved tenant context when deterministically known.
      required:
      - redirect_url
      - state
      - protocol
    SamlCallbackRequest:
      type: object
      additionalProperties: false
      properties:
        SAMLResponse:
          type: string
          minLength: 16
          description: Base64-encoded SAML assertion payload (HTTP POST binding field
            name).
        RelayState:
          type: string
          minLength: 8
          description: Opaque state token issued by `/api/v1/auth/saml/authorize`
            (`state` field) and returned via SAML POST binding.
      required:
      - SAMLResponse
      - RelayState
    TenantFederationProvider:
      type: object
      additionalProperties: false
      description: |
        Planned tenant federation provider configuration contract for enterprise SSO (OIDC/SAML).
        Note: schema is defined now for contract-first readiness; tenant-admin CRUD endpoints are pending.
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        provider_type:
          type: string
          enum:
          - oidc
          - saml
        provider_name:
          type: string
          minLength: 1
          maxLength: 128
        enabled:
          type: boolean
        issuer:
          type: string
          nullable: true
          description: OIDC issuer; required for oidc providers.
        saml_entity_id:
          type: string
          nullable: true
          description: SAML entity id; required for saml providers.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - org_id
      - provider_type
      - provider_name
      - enabled
      - created_at
      - updated_at
    TenantFederationDomainBinding:
      type: object
      additionalProperties: false
      description: |
        Optional domain binding used for server-side tenant federation resolution.
        Note: schema is defined now for contract-first readiness; tenant-admin CRUD endpoints are pending.
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        domain:
          type: string
          minLength: 3
        idp_id:
          type: string
          format: uuid
        verification_state:
          type: string
          enum:
          - pending
          - verified
          - failed
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - org_id
      - domain
      - idp_id
      - verification_state
      - created_at
      - updated_at
    CreateTenantFederationProviderRequest:
      type: object
      additionalProperties: false
      description: Planned write contract for tenant-admin federation provider creation.
      properties:
        provider_type:
          type: string
          enum:
          - oidc
          - saml
        provider_name:
          type: string
          minLength: 1
          maxLength: 128
        enabled:
          type: boolean
          default: true
        issuer:
          type: string
          nullable: true
        client_id:
          type: string
          nullable: true
        client_secret:
          type: string
          nullable: true
          description: Accepted in plaintext on write; server encrypts before storage
            into `client_secret_enc`.
        authorization_endpoint:
          type: string
          format: uri
          nullable: true
        token_endpoint:
          type: string
          format: uri
          nullable: true
        jwks_uri:
          type: string
          format: uri
          nullable: true
        saml_entity_id:
          type: string
          nullable: true
        saml_sso_url:
          type: string
          format: uri
          nullable: true
        saml_x509_cert_pem:
          type: string
          nullable: true
          description: Accepted in plaintext PEM on write; server encrypts before
            storage into `saml_x509_cert_enc`.
      required:
      - provider_type
      - provider_name
    UpdateTenantFederationProviderRequest:
      type: object
      additionalProperties: false
      description: |
        Planned write contract for tenant-admin federation provider updates.
        PATCH semantics: only provided fields are updated.
      properties:
        provider_name:
          type: string
          minLength: 1
          maxLength: 128
        enabled:
          type: boolean
        issuer:
          type: string
          nullable: true
        client_id:
          type: string
          nullable: true
        client_secret:
          type: string
          nullable: true
          description: Accepted in plaintext on write; server encrypts before storage
            into `client_secret_enc`.
        authorization_endpoint:
          type: string
          format: uri
          nullable: true
        token_endpoint:
          type: string
          format: uri
          nullable: true
        jwks_uri:
          type: string
          format: uri
          nullable: true
        saml_entity_id:
          type: string
          nullable: true
        saml_sso_url:
          type: string
          format: uri
          nullable: true
        saml_x509_cert_pem:
          type: string
          nullable: true
          description: Accepted in plaintext PEM on write; server encrypts before
            storage into `saml_x509_cert_enc`.
    UsageRecord:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        usage_source:
          type: string
          enum:
          - allocation
          - app_runtime
        usage_unit:
          type: string
        allocation_id:
          type: string
          format: uuid
          nullable: true
        app_instance_id:
          type: string
          format: uuid
          nullable: true
        requested_by_user_id:
          type: string
          format: uuid
        sku:
          type: string
        control_plane_component:
          type: boolean
        operating_mode:
          type: string
          enum:
          - tenant_dedicated
          - platform_managed
          nullable: true
        control_plane_scope:
          type: string
          enum:
          - project
          - tenant
          - platform
          nullable: true
        runtime_backend:
          type: string
          enum:
          - k8s
          - rke2
          - slurm
          - ray
          - bare_metal
          nullable: true
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
          nullable: true
        last_billed_at:
          type: string
          format: date-time
          nullable: true
        cost:
          "$ref": "#/components/schemas/Money"
      required:
      - id
      - usage_source
      - usage_unit
      - requested_by_user_id
      - sku
      - control_plane_component
      - start_time
      - cost
    UsageListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/UsageRecord"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    Sku:
      type: object
      additionalProperties: false
      properties:
        sku:
          type: string
        vendor:
          type: string
        name:
          type: string
        gpus_total:
          type: integer
          minimum: 1
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        allowed_gpu_counts:
          type: array
          items:
            type: integer
            minimum: 1
          description: Approved GPU counts for selectable slice products. Empty for
            fixed-size baremetal products.
        price_per_gpu_hour:
          "$ref": "#/components/schemas/Money"
      required:
      - sku
      - vendor
      - name
      - gpus_total
      - price_per_gpu_hour
    SkuListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/Sku"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    NodeSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        resource_name:
          type: string
          description: Canonical resource identifier in core42:aicloud format.
        sku:
          type: string
        gpus_total:
          type: integer
        status:
          type: string
          enum:
          - registered
          - bootstrap_issued
          - enrolling
          - active
          - cordoned
          - offline
          - quarantined
          - draining
          - retired
          - removing
        occupancy_status:
          type: string
          enum:
          - available
          - assigned
          - reserved
          - restarting
          - restart_failed
          - releasing
          - cleanup
          - unavailable
        in_use:
          type: boolean
        slot_summary:
          "$ref": "#/components/schemas/NodeSlotSummary"
          nullable: true
        region_code:
          type: string
        onboarding_mode:
          type: string
          enum:
          - manual
          - maas
      required:
      - id
      - sku
      - gpus_total
      - status
      - occupancy_status
      - in_use
      - region_code
      - onboarding_mode
    CapacityShape:
      type: string
      enum:
      - baremetal
      - gpu_slice
    AllocationPlacementStatus:
      type: string
      enum:
      - unplaced
      - reserved
      - provisioning
      - active
      - releasing
      - released
      - failed
    NodeSlotSummary:
      type: object
      additionalProperties: false
      properties:
        total:
          type: integer
          minimum: 0
        available:
          type: integer
          minimum: 0
        schedulable_available:
          type: integer
          minimum: 0
          description: Available slots that satisfy current scheduler topology and
            exclusivity filters. Marketplace clients use this value; raw `available`
            remains an operator inventory count.
        reserved:
          type: integer
          minimum: 0
        provisioning:
          type: integer
          minimum: 0
        active:
          type: integer
          minimum: 0
        releasing:
          type: integer
          minimum: 0
        cleanup:
          type: integer
          minimum: 0
        cleanup_blocked:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
        disabled:
          type: integer
          minimum: 0
        by_sku:
          type: array
          description: Slot capacity grouped by the schedulable SKU carried by slot
            metadata. Used to keep slice slots separate from the physical bare-metal
            node SKU.
          items:
            "$ref": "#/components/schemas/NodeSlotSkuSummary"
      required:
      - total
      - available
      - reserved
      - provisioning
      - active
      - releasing
      - cleanup
      - cleanup_blocked
      - failed
      - disabled
    NodeSlotSkuSummary:
      type: object
      additionalProperties: false
      properties:
        sku:
          type: string
        total:
          type: integer
          minimum: 0
        available:
          type: integer
          minimum: 0
        schedulable_available:
          type: integer
          minimum: 0
          description: Available slots for this SKU that satisfy current scheduler
            topology and exclusivity filters. Marketplace clients use this value;
            raw `available` remains an operator inventory count.
        reserved:
          type: integer
          minimum: 0
        provisioning:
          type: integer
          minimum: 0
        active:
          type: integer
          minimum: 0
        releasing:
          type: integer
          minimum: 0
        cleanup:
          type: integer
          minimum: 0
        cleanup_blocked:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
        disabled:
          type: integer
          minimum: 0
      required:
      - sku
      - total
      - available
      - reserved
      - provisioning
      - active
      - releasing
      - cleanup
      - cleanup_blocked
      - failed
      - disabled
    NodeResourceSlotStatus:
      type: string
      enum:
      - available
      - reserved
      - provisioning
      - active
      - releasing
      - cleanup
      - cleanup_blocked
      - failed
      - disabled
    AdminUpsertNodeResourceSlotStatus:
      type: string
      description: Operator-settable slot states. Runtime lifecycle states are system-owned
        and returned only through NodeResourceSlotStatus.
      enum:
      - available
      - reserved
      - active
      - cleanup
      - cleanup_blocked
      - disabled
    NodeResourceSlot:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        node_id:
          type: string
          format: uuid
        parent_slot_id:
          type: string
          format: uuid
          nullable: true
        slot_index:
          type: integer
          minimum: 0
        status:
          "$ref": "#/components/schemas/NodeResourceSlotStatus"
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        sharing_model:
          type: string
          nullable: true
          enum:
          - exclusive_device
          description: Current implemented slots are whole-GPU exclusive devices.
            Fractional, MIG, vGPU, MPS, and time-sliced products remain design-only
            and are not accepted by the v1 admin slot API.
        profile_name:
          type: string
          nullable: true
          description: Reserved vendor/runtime profile name for future partition,
            vGPU, or share profiles.
        accelerator_vendor:
          type: string
          nullable: true
        accelerator_model:
          type: string
          nullable: true
        gpu_index:
          type: integer
          nullable: true
        gpu_uuid:
          type: string
          nullable: true
        pci_address:
          type: string
          nullable: true
        numa_node:
          type: integer
          nullable: true
        nvme_device:
          type: string
          nullable: true
        nvme_wwn:
          type: string
          nullable: true
        fabric_kind:
          type: string
          nullable: true
          enum:
          - ib
          - roce
          - ethernet
        fabric_device:
          type: string
          nullable: true
        vcpu_count:
          type: integer
          nullable: true
          minimum: 1
        memory_mib:
          type: integer
          nullable: true
          minimum: 1
        gpu_memory_mib:
          type: integer
          nullable: true
          minimum: 1
          description: Reserved accelerator memory quantity for future fractional/shared
            GPU inventory.
        compute_milli:
          type: integer
          nullable: true
          minimum: 1
          description: Reserved compute-share quantity where 1000 represents one nominal
            whole accelerator unit for future products.
        max_claims:
          type: integer
          nullable: true
          minimum: 1
          description: Reserved maximum colocated claims for future shared GPU inventory.
            Current slots remain single-claim.
        mac_address:
          type: string
          nullable: true
        private_ip:
          type: string
          nullable: true
        health_state:
          type: string
          nullable: true
        health_detail:
          type: object
          additionalProperties: true
        capacity_metadata:
          type: object
          description: Slot approval metadata. For schedulable whole-GPU slice slots,
            `storage_ownership` must be `slice` and `destructive_wipe_policy` must
            name the approved cleanup method, for example `blkdiscard`, `nvme_format`,
            or a site-specific secure erase profile. Schedulable slice slots also
            require `fabric_claim_mode=per_slot_vf` plus a non-empty `fabric_vf_pci_address`
            that identifies the isolated fabric attachment assigned to that slot.
            `fabric_device` may still carry the parent BF/IB device for operator context,
            but it is not sufficient for concurrent slice placement.
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - node_id
      - slot_index
      - status
      - capacity_shape
      - created_at
      - updated_at
    NodeResourceSlotListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/NodeResourceSlot"
      required:
      - items
    AdminUpsertNodeResourceSlot:
      type: object
      additionalProperties: false
      properties:
        parent_slot_id:
          type: string
          format: uuid
          nullable: true
        slot_index:
          type: integer
          minimum: 0
        status:
          "$ref": "#/components/schemas/AdminUpsertNodeResourceSlotStatus"
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        sharing_model:
          type: string
          nullable: true
          enum:
          - exclusive_device
          description: Current implemented slots are whole-GPU exclusive devices.
            Fractional, MIG, vGPU, MPS, and time-sliced products remain design-only
            and are not accepted by the v1 admin slot API.
        profile_name:
          type: string
          nullable: true
          description: Reserved vendor/runtime profile name for future partition,
            vGPU, or share profiles.
        accelerator_vendor:
          type: string
          nullable: true
        accelerator_model:
          type: string
          nullable: true
        gpu_index:
          type: integer
          nullable: true
        gpu_uuid:
          type: string
          nullable: true
        pci_address:
          type: string
          nullable: true
        numa_node:
          type: integer
          nullable: true
        nvme_device:
          type: string
          nullable: true
        nvme_wwn:
          type: string
          nullable: true
        fabric_kind:
          type: string
          nullable: true
          enum:
          - ib
          - roce
          - ethernet
        fabric_device:
          type: string
          nullable: true
        vcpu_count:
          type: integer
          nullable: true
          minimum: 1
        memory_mib:
          type: integer
          nullable: true
          minimum: 1
        gpu_memory_mib:
          type: integer
          nullable: true
          minimum: 1
          description: Reserved accelerator memory quantity for future fractional/shared
            GPU inventory.
        compute_milli:
          type: integer
          nullable: true
          minimum: 1
          description: Reserved compute-share quantity where 1000 represents one nominal
            whole accelerator unit for future products.
        max_claims:
          type: integer
          nullable: true
          minimum: 1
          description: Reserved maximum colocated claims for future shared GPU inventory.
            Current slots remain single-claim.
        mac_address:
          type: string
          nullable: true
        private_ip:
          type: string
          nullable: true
        health_state:
          type: string
          nullable: true
        health_detail:
          type: object
          additionalProperties: true
        capacity_metadata:
          type: object
          description: Slot approval metadata. Setting an exclusive whole-GPU slot
            to `available` requires `storage_ownership` to be `slice` and a non-empty
            `destructive_wipe_policy`; mounted baremetal/share devices must remain
            disabled or cleanup_blocked until infra completes the mode transition.
            Whole-GPU slice slots also require `fabric_claim_mode=per_slot_vf` and
            a non-empty `fabric_vf_pci_address` before they can be saved as `available`.
            Missing values, `exclusive_device`, and `shared_host` are not schedulable
            for the VM-slice product.
          additionalProperties: true
      required:
      - slot_index
      - status
      - capacity_shape
    AdminUpsertNodeResourceSlotsRequest:
      type: object
      additionalProperties: false
      properties:
        slots:
          type: array
          minItems: 1
          maxItems: 64
          items:
            "$ref": "#/components/schemas/AdminUpsertNodeResourceSlot"
      required:
      - slots
    NodeSliceTopologyDiscovery:
      type: object
      additionalProperties: false
      properties:
        task_id:
          type: string
          format: uuid
        node_id:
          type: string
          format: uuid
        task_type:
          type: string
          enum:
          - slice.topology_discover
        status:
          type: string
          enum:
          - queued
          - dispatched
          - completed
          - failed
          - rejected
          - expired
        correlation_id:
          type: string
        issued_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        dispatched_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        error:
          type: string
          nullable: true
        output:
          type: object
          nullable: true
          additionalProperties: true
          description: Raw advisory candidate map from `slice.topology_discover`;
            must be admin-approved into `node_resource_slots` before scheduling.
      required:
      - task_id
      - node_id
      - task_type
      - status
      - correlation_id
      - issued_at
      - expires_at
    NodeSliceTopologyDiscoveryResponse:
      type: object
      additionalProperties: false
      properties:
        item:
          nullable: true
          allOf:
          - "$ref": "#/components/schemas/NodeSliceTopologyDiscovery"
      required:
      - item
    OSImageTarget:
      type: string
      enum:
      - baremetal
      - vm_slice
      x-enum-varnames:
      - OSImageTargetBaremetal
      - OSImageTargetVmSlice
    OSImageFormat:
      type: string
      enum:
      - raw
      - qcow2
      - iso
      - maas
    OSImageStatus:
      type: string
      enum:
      - active
      - disabled
      - deprecated
    OSImageDriverStrategy:
      type: string
      enum:
      - preinstalled
      - cloud-init
      - none
    OSImage:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
          minLength: 2
        display_name:
          type: string
          minLength: 1
        target:
          "$ref": "#/components/schemas/OSImageTarget"
        image_format:
          "$ref": "#/components/schemas/OSImageFormat"
        source_uri:
          type: string
          minLength: 1
        digest_sha256:
          type: string
          pattern: "^[a-f0-9]{64}$"
        default_username:
          type: string
          minLength: 1
        accelerator_vendor:
          type: string
          nullable: true
        driver_strategy:
          "$ref": "#/components/schemas/OSImageDriverStrategy"
        compatible_skus:
          type: array
          items:
            type: string
            minLength: 1
        status:
          "$ref": "#/components/schemas/OSImageStatus"
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - slug
      - display_name
      - target
      - image_format
      - source_uri
      - digest_sha256
      - default_username
      - driver_strategy
      - compatible_skus
      - status
      - created_at
      - updated_at
    OSImageListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/OSImage"
        next_cursor:
          type: string
          nullable: true
      required:
      - items
    AdminCreateOSImageRequest:
      type: object
      additionalProperties: false
      properties:
        slug:
          type: string
          minLength: 2
        display_name:
          type: string
          minLength: 1
        target:
          "$ref": "#/components/schemas/OSImageTarget"
        image_format:
          "$ref": "#/components/schemas/OSImageFormat"
        source_uri:
          type: string
          minLength: 1
        digest_sha256:
          type: string
          pattern: "^[a-f0-9]{64}$"
        default_username:
          type: string
          minLength: 1
        accelerator_vendor:
          type: string
          nullable: true
        driver_strategy:
          "$ref": "#/components/schemas/OSImageDriverStrategy"
        compatible_skus:
          type: array
          items:
            type: string
            minLength: 1
        status:
          "$ref": "#/components/schemas/OSImageStatus"
        metadata:
          type: object
          additionalProperties: true
      required:
      - slug
      - display_name
      - target
      - image_format
      - source_uri
      - digest_sha256
      - default_username
    AdminUpdateOSImageRequest:
      type: object
      additionalProperties: false
      properties:
        slug:
          type: string
          minLength: 2
        display_name:
          type: string
          minLength: 1
        target:
          "$ref": "#/components/schemas/OSImageTarget"
        image_format:
          "$ref": "#/components/schemas/OSImageFormat"
        source_uri:
          type: string
          minLength: 1
        digest_sha256:
          type: string
          pattern: "^[a-f0-9]{64}$"
        default_username:
          type: string
          minLength: 1
        accelerator_vendor:
          type: string
          nullable: true
        driver_strategy:
          "$ref": "#/components/schemas/OSImageDriverStrategy"
        compatible_skus:
          type: array
          items:
            type: string
            minLength: 1
        status:
          "$ref": "#/components/schemas/OSImageStatus"
        metadata:
          type: object
          additionalProperties: true
    NodeAdmin:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        resource_name:
          type: string
          description: Canonical resource identifier in core42:aicloud format.
        sku:
          type: string
        gpus_total:
          type: integer
        status:
          type: string
          enum:
          - registered
          - bootstrap_issued
          - enrolling
          - active
          - cordoned
          - offline
          - quarantined
          - draining
          - retired
          - removing
        occupancy_status:
          type: string
          enum:
          - available
          - assigned
          - reserved
          - restarting
          - restart_failed
          - releasing
          - cleanup
          - unavailable
        in_use:
          type: boolean
        slot_summary:
          "$ref": "#/components/schemas/NodeSlotSummary"
          nullable: true
        region_code:
          type: string
        onboarding_mode:
          type: string
          enum:
          - manual
          - maas
        host:
          type: string
        hostname:
          type: string
          nullable: true
        port:
          type: integer
        ssh_username:
          type: string
        agent_version:
          type: string
          nullable: true
          description: Latest node-agent build version reported by the enrolled node.
        agent_commit:
          type: string
          nullable: true
          description: Latest node-agent git commit reported by the enrolled node.
        agent_built_at:
          type: string
          nullable: true
          description: Latest node-agent build timestamp reported by the enrolled
            node.
        agent_reported_at:
          type: string
          format: date-time
          nullable: true
          description: Time the control plane last observed node-agent build metadata.
        agent_lifecycle:
          "$ref": "#/components/schemas/NodeAgentLifecycleState"
          nullable: true
        current_allocation:
          "$ref": "#/components/schemas/NodeOccupancy"
          nullable: true
      required:
      - id
      - sku
      - gpus_total
      - status
      - occupancy_status
      - in_use
      - region_code
      - onboarding_mode
      - host
      - port
      - ssh_username
    AdminNodeLifecycleRecoveryAction:
      type: string
      enum:
      - task_already_queued
      - task_in_progress
      - task_requeued
      - task_recreated
    AdminResumeNodeLifecycleResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
        node_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - draining
          - removing
        task_type:
          type: string
          enum:
          - node.drain
          - node.uninstall
        recovery_action:
          "$ref": "#/components/schemas/AdminNodeLifecycleRecoveryAction"
      required:
      - ok
      - node_id
      - status
      - task_type
      - recovery_action
    NodeOccupancy:
      type: object
      additionalProperties: false
      properties:
        allocation_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        username_on_node:
          type: string
          description: Stable per-user node username sourced from user POSIX identity
            mapping.
        status:
          type: string
          enum:
          - active
          - releasing
          - release_failed
      required:
      - allocation_id
      - user_id
      - username_on_node
      - status
    NodeSummaryListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/NodeSummary"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    NodeAdminListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/NodeAdmin"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    NodeAgentDeliveryMode:
      type: string
      enum:
      - reimage
      - manual_install
      - rebootstrap
    NodeAgentLifecycleScenario:
      type: string
      enum:
      - bootstrap_install
      - in_place_upgrade
      - repair_reinstall
      - certificate_repair
      - drift_reconcile
    NodeAgentLifecycleStatus:
      type: string
      enum:
      - pending
      - running
      - completed
      - failed_retryable
      - failed_manual_intervention
      - cancelled
    NodeAgentUpgradeSafetyPolicy:
      type: string
      enum:
      - idle_only
      - drain_then_upgrade
      - force
    NodeAgentDriftState:
      type: string
      enum:
      - in_sync
      - version_drift
      - config_drift
      - certificate_only_repair_needed
      - unknown
    NodeAgentLifecycleState:
      type: object
      additionalProperties: false
      properties:
        desired_agent_version:
          type: string
          nullable: true
        reported_agent_version:
          type: string
          nullable: true
        desired_delivery_mode:
          "$ref": "#/components/schemas/NodeAgentDeliveryMode"
          nullable: true
        drift_state:
          "$ref": "#/components/schemas/NodeAgentDriftState"
        last_delivery_attempt_at:
          type: string
          format: date-time
          nullable: true
        last_delivery_result:
          type: string
          nullable: true
        last_delivery_correlation_id:
          type: string
          nullable: true
      required:
      - drift_state
    AdminStartNodeAgentLifecycleRequest:
      type: object
      additionalProperties: false
      properties:
        mode:
          "$ref": "#/components/schemas/NodeAgentDeliveryMode"
        scenario:
          "$ref": "#/components/schemas/NodeAgentLifecycleScenario"
        target_version:
          type: string
          nullable: true
          description: Required for `bootstrap_install` and `in_place_upgrade`; optional
            for repair-only scenarios.
        safety_policy:
          "$ref": "#/components/schemas/NodeAgentUpgradeSafetyPolicy"
        reason:
          type: string
          nullable: true
      required:
      - mode
      - scenario
      - safety_policy
    NodeAgentLifecycleRun:
      type: object
      additionalProperties: false
      properties:
        lifecycle_id:
          type: string
          format: uuid
        node_id:
          type: string
          format: uuid
        mode:
          "$ref": "#/components/schemas/NodeAgentDeliveryMode"
        scenario:
          "$ref": "#/components/schemas/NodeAgentLifecycleScenario"
        status:
          "$ref": "#/components/schemas/NodeAgentLifecycleStatus"
        desired_agent_version:
          type: string
          nullable: true
        reported_agent_version:
          type: string
          nullable: true
        safety_policy:
          "$ref": "#/components/schemas/NodeAgentUpgradeSafetyPolicy"
        error_code:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
        error_details:
          type: object
          additionalProperties: true
        correlation_id:
          type: string
        requested_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
      required:
      - lifecycle_id
      - node_id
      - mode
      - scenario
      - status
      - safety_policy
      - error_details
      - correlation_id
      - requested_at
      - updated_at
    AdminStartNodeAgentLifecycleResponse:
      type: object
      additionalProperties: false
      properties:
        lifecycle:
          "$ref": "#/components/schemas/NodeAgentLifecycleRun"
      required:
      - lifecycle
    MaasSiteStatus:
      type: string
      enum:
      - active
      - disabled
    MaasSiteProfileStatus:
      type: string
      enum:
      - active
      - disabled
    MaasSitePolicy:
      type: object
      additionalProperties: false
      properties:
        fabric_mode:
          type: string
          enum:
          - ethernet
          - roce
          - ib
        strict_pxe_preflight:
          type: boolean
        enable_phase2_roce:
          type: boolean
        require_hw_sync:
          type: boolean
        hardware_sync_interval:
          type: string
          minLength: 1
          maxLength: 32
        release_fallback_no_erase:
          type: boolean
        enable_deploy_retry_on_datasource_failure:
          type: boolean
        max_deploy_retry_attempts:
          type: integer
          minimum: 0
          maximum: 10
        auto_claim_single_new_machine:
          type: boolean
        batch_max_parallel:
          type: integer
          minimum: 1
          maximum: 100
        site_bootstrap_bundle_ref:
          type: string
          nullable: true
          maxLength: 512
          description: Canonical infra-owned first-boot site bootstrap bundle reference.
        commissioning_bundle_ref:
          type: string
          nullable: true
          maxLength: 512
          description: Optional infra-owned commissioning or MAAS script bundle reference
            reserved for future site automation.
        post_deploy_validation_bundle_ref:
          type: string
          nullable: true
          maxLength: 512
          description: Optional post-deploy validation bundle reference reserved for
            future hardware or fabric checks.
        fabric_controller_bundle_ref:
          type: string
          nullable: true
          maxLength: 512
          description: Optional future fabric-controller integration bundle reference,
            for example UFM or PKEY orchestration hooks.
        extra_cloud_init_bundle_path:
          type: string
          nullable: true
          maxLength: 512
          deprecated: true
          description: Deprecated legacy alias for `site_bootstrap_bundle_ref`. Accepted
            only for backward compatibility.
        enrollment_token_ttl_seconds:
          type: integer
          minimum: 60
          maximum: 86400
      required:
      - fabric_mode
      - strict_pxe_preflight
      - enable_phase2_roce
      - require_hw_sync
      - hardware_sync_interval
      - release_fallback_no_erase
      - enable_deploy_retry_on_datasource_failure
      - max_deploy_retry_attempts
      - auto_claim_single_new_machine
      - batch_max_parallel
      - enrollment_token_ttl_seconds
    MaasSiteCredentialStatus:
      type: object
      additionalProperties: false
      properties:
        api_token_configured:
          type: boolean
        default_power_credentials_configured:
          type: boolean
        deploy_password_configured:
          type: boolean
        api_token_vault_path:
          type: string
        default_power_creds_vault_path:
          type: string
        deploy_password_vault_path:
          type: string
        configured_at:
          type: string
          format: date-time
          nullable: true
      required:
      - api_token_configured
      - default_power_credentials_configured
      - deploy_password_configured
      - api_token_vault_path
      - default_power_creds_vault_path
      - deploy_password_vault_path
    MaasSiteProbeResult:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
        version:
          type: string
          nullable: true
        subversion:
          type: string
          nullable: true
        capabilities:
          type: array
          items:
            type: string
        probed_at:
          type: string
          format: date-time
        error:
          type: string
          nullable: true
      required:
      - ok
      - capabilities
      - probed_at
    MaasSite:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        region_code:
          type: string
        api_base_url:
          type: string
          format: uri
        pxe_iface:
          type: string
        pxe_vlan_vid:
          type: integer
          minimum: 1
          maximum: 4094
        node_pxe_iface:
          type: string
        distro_series:
          type: string
        architecture:
          type: string
        deploy_user:
          type: string
          minLength: 1
          maxLength: 64
        deploy_ssh_iface:
          type: string
          minLength: 1
          maxLength: 64
        upstream_dns_servers:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 255
        status:
          "$ref": "#/components/schemas/MaasSiteStatus"
        default_profile_id:
          type: string
          format: uuid
          nullable: true
        profile_count:
          type: integer
          minimum: 0
        credentials:
          "$ref": "#/components/schemas/MaasSiteCredentialStatus"
        policy:
          "$ref": "#/components/schemas/MaasSitePolicy"
        last_probe:
          allOf:
          - "$ref": "#/components/schemas/MaasSiteProbeResult"
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        disabled_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - name
      - region_code
      - api_base_url
      - pxe_iface
      - pxe_vlan_vid
      - node_pxe_iface
      - distro_series
      - architecture
      - deploy_user
      - deploy_ssh_iface
      - upstream_dns_servers
      - status
      - profile_count
      - credentials
      - policy
      - created_at
      - updated_at
    MaasSiteProfile:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        site_id:
          type: string
          format: uuid
        name:
          type: string
        status:
          "$ref": "#/components/schemas/MaasSiteProfileStatus"
        is_default:
          type: boolean
        pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
        pxe_vlan_vid:
          type: integer
          minimum: 1
          maximum: 4094
          nullable: true
        node_pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
        distro_series:
          type: string
          minLength: 1
          maxLength: 64
        architecture:
          type: string
          minLength: 1
          maxLength: 64
        policy:
          allOf:
          - "$ref": "#/components/schemas/MaasSitePolicy"
          description: Profile-scoped MAAS lifecycle policy bundle.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        disabled_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - site_id
      - name
      - status
      - is_default
      - distro_series
      - architecture
      - policy
      - created_at
      - updated_at
    MaasSiteProfileListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/MaasSiteProfile"
      required:
      - items
    MaasSiteListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/MaasSite"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    MaasDiscoveryCandidateState:
      type: string
      enum:
      - candidate
      - known_node
      - existing_onboarding
    MaasDiscoveryCandidateReviewState:
      type: string
      enum:
      - active
      - ignored
      - suppressed
    MaasDiscoveryCandidateSKUHint:
      type: object
      additionalProperties: false
      properties:
        sku:
          type: string
          nullable: true
        confidence:
          type: string
        reason:
          type: string
      required:
      - confidence
      - reason
    MaasDiscoveryCandidateGPUDevice:
      type: object
      additionalProperties: false
      properties:
        vendor_name:
          type: string
        product_name:
          type: string
        pci_address:
          type: string
          nullable: true
      required:
      - vendor_name
      - product_name
    MaasGPUaaSProfileIntent:
      type: string
      enum:
      - slice_vm
      - baremetal
      - unprofiled
      - conflict
    MaasDiscoveryCandidateEnrichment:
      type: object
      additionalProperties: false
      properties:
        maas_system_id:
          type: string
        hostname:
          type: string
        tag_names:
          type: array
          items:
            type: string
        gpuaas_profile_intent:
          "$ref": "#/components/schemas/MaasGPUaaSProfileIntent"
        power_address:
          type: string
          nullable: true
        power_driver:
          type: string
          nullable: true
        power_user:
          type: string
          nullable: true
        sku_hint:
          "$ref": "#/components/schemas/MaasDiscoveryCandidateSKUHint"
        gpu_devices:
          type: array
          items:
            "$ref": "#/components/schemas/MaasDiscoveryCandidateGPUDevice"
      required:
      - maas_system_id
      - hostname
      - tag_names
      - gpuaas_profile_intent
      - sku_hint
      - gpu_devices
    MaasDiscoveryCandidate:
      type: object
      additionalProperties: false
      properties:
        maas_system_id:
          type: string
        hostname:
          type: string
        architecture:
          type: string
        maas_status:
          type: string
        power_state:
          type: string
          nullable: true
        power_address:
          type: string
          nullable: true
        tag_names:
          type: array
          items:
            type: string
        gpuaas_profile_intent:
          "$ref": "#/components/schemas/MaasGPUaaSProfileIntent"
        interface_count:
          type: integer
          minimum: 0
        blockdevice_count:
          type: integer
          minimum: 0
        state:
          "$ref": "#/components/schemas/MaasDiscoveryCandidateState"
        node_id:
          type: string
          format: uuid
          nullable: true
        node_status:
          type: string
          nullable: true
        onboarding_id:
          type: string
          format: uuid
          nullable: true
        onboarding_status:
          "$ref": "#/components/schemas/MaasWorkflowStatus"
          nullable: true
        review_state:
          "$ref": "#/components/schemas/MaasDiscoveryCandidateReviewState"
        review_reason:
          type: string
          nullable: true
        reviewed_at:
          type: string
          format: date-time
          nullable: true
        matched_profile_ids:
          type: array
          items:
            type: string
            format: uuid
        matched_profile_names:
          type: array
          items:
            type: string
        sku_hint:
          "$ref": "#/components/schemas/MaasDiscoveryCandidateSKUHint"
        already_managed_by_gpuaas:
          type: boolean
      required:
      - maas_system_id
      - hostname
      - architecture
      - maas_status
      - tag_names
      - gpuaas_profile_intent
      - interface_count
      - blockdevice_count
      - state
      - review_state
      - review_reason
      - reviewed_at
      - matched_profile_ids
      - matched_profile_names
      - sku_hint
      - already_managed_by_gpuaas
    MaasDiscoveryCandidateListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/MaasDiscoveryCandidate"
      required:
      - items
    AdminUpdateMaasDiscoveryCandidateDecisionRequest:
      type: object
      additionalProperties: false
      properties:
        review_state:
          "$ref": "#/components/schemas/MaasDiscoveryCandidateReviewState"
        reason:
          type: string
          nullable: true
          maxLength: 500
      required:
      - review_state
    MaasDiscoveryCandidateDecision:
      type: object
      additionalProperties: false
      properties:
        site_id:
          type: string
          format: uuid
        maas_system_id:
          type: string
        review_state:
          "$ref": "#/components/schemas/MaasDiscoveryCandidateReviewState"
        review_reason:
          type: string
          nullable: true
        reviewed_at:
          type: string
          format: date-time
      required:
      - site_id
      - maas_system_id
      - review_state
      - reviewed_at
    AdminCreateMaasSiteRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        region_code:
          type: string
          minLength: 1
          maxLength: 64
        api_base_url:
          type: string
          format: uri
        pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
        pxe_vlan_vid:
          type: integer
          minimum: 1
          maximum: 4094
        node_pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
        distro_series:
          type: string
          minLength: 1
          maxLength: 64
          default: ubuntu/noble
        architecture:
          type: string
          minLength: 1
          maxLength: 64
          default: amd64/generic
        deploy_user:
          type: string
          minLength: 1
          maxLength: 64
          default: hpcadmin
        deploy_ssh_iface:
          type: string
          minLength: 1
          maxLength: 64
          default: eno8303
        upstream_dns_servers:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 255
        policy:
          "$ref": "#/components/schemas/MaasSitePolicy"
      required:
      - name
      - region_code
      - api_base_url
      - pxe_iface
      - pxe_vlan_vid
      - node_pxe_iface
    AdminUpdateMaasSiteRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        region_code:
          type: string
          minLength: 1
          maxLength: 64
        api_base_url:
          type: string
          format: uri
        pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
        pxe_vlan_vid:
          type: integer
          minimum: 1
          maximum: 4094
        node_pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
        distro_series:
          type: string
          minLength: 1
          maxLength: 64
        architecture:
          type: string
          minLength: 1
          maxLength: 64
        deploy_user:
          type: string
          minLength: 1
          maxLength: 64
        deploy_ssh_iface:
          type: string
          minLength: 1
          maxLength: 64
        upstream_dns_servers:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 255
        status:
          "$ref": "#/components/schemas/MaasSiteStatus"
        policy:
          "$ref": "#/components/schemas/MaasSitePolicy"
    AdminWriteMaasSiteCredentialsRequest:
      type: object
      additionalProperties: false
      properties:
        api_token:
          type: string
          minLength: 1
        default_power_username:
          type: string
          minLength: 1
          maxLength: 128
        default_power_password:
          type: string
          minLength: 1
          maxLength: 4096
        deploy_password:
          type: string
          minLength: 1
          maxLength: 4096
      required:
      - api_token
      - default_power_username
      - default_power_password
      - deploy_password
    AdminWriteMaasSiteCredentialsResponse:
      type: object
      additionalProperties: false
      properties:
        site:
          "$ref": "#/components/schemas/MaasSite"
        probe:
          "$ref": "#/components/schemas/MaasSiteProbeResult"
      required:
      - site
      - probe
    AdminBulkUpsertMaasRoceAssignmentsRequest:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          minItems: 1
          items:
            "$ref": "#/components/schemas/AdminUpsertMaasRoceAssignmentItem"
      required:
      - items
    AdminUpsertMaasRoceAssignmentItem:
      type: object
      additionalProperties: false
      properties:
        hostname:
          type: string
          minLength: 1
          maxLength: 255
        interface:
          type: string
          minLength: 1
          maxLength: 64
        ipv4_cidr:
          type: string
          minLength: 1
          maxLength: 64
      required:
      - hostname
      - interface
      - ipv4_cidr
    AdminSetMaasRoceAssignmentStatusRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          minLength: 1
          maxLength: 500
          nullable: true
    AdminCreateMaasSiteProfileRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
        pxe_vlan_vid:
          type: integer
          minimum: 1
          maximum: 4094
          nullable: true
        node_pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
        distro_series:
          type: string
          minLength: 1
          maxLength: 64
        architecture:
          type: string
          minLength: 1
          maxLength: 64
        policy:
          "$ref": "#/components/schemas/MaasSitePolicy"
      required:
      - name
    AdminUpdateMaasSiteProfileRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        status:
          "$ref": "#/components/schemas/MaasSiteProfileStatus"
        pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
        pxe_vlan_vid:
          type: integer
          minimum: 1
          maximum: 4094
          nullable: true
        node_pxe_iface:
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
        distro_series:
          type: string
          minLength: 1
          maxLength: 64
        architecture:
          type: string
          minLength: 1
          maxLength: 64
        policy:
          "$ref": "#/components/schemas/MaasSitePolicy"
    MaasOnboardingNodeInput:
      type: object
      additionalProperties: false
      properties:
        hostname:
          type: string
          minLength: 1
          maxLength: 255
        ipmi_ip:
          type: string
          minLength: 1
          maxLength: 64
      required:
      - hostname
      - ipmi_ip
    AdminStartMaasOnboardingRequest:
      type: object
      additionalProperties: false
      properties:
        site_id:
          type: string
          format: uuid
        profile_id:
          type: string
          format: uuid
        sku_id:
          type: string
          minLength: 1
          maxLength: 128
        hostname:
          type: string
          minLength: 1
          maxLength: 255
        ipmi_ip:
          type: string
          minLength: 1
          maxLength: 64
      required:
      - site_id
      - profile_id
      - sku_id
      - hostname
      - ipmi_ip
    AdminStartMaasOnboardingResponse:
      type: object
      additionalProperties: false
      properties:
        onboarding_id:
          type: string
          format: uuid
        status:
          "$ref": "#/components/schemas/MaasWorkflowStatus"
      required:
      - onboarding_id
      - status
    AdminStartMaasBatchOnboardingRequest:
      type: object
      additionalProperties: false
      properties:
        site_id:
          type: string
          format: uuid
        profile_id:
          type: string
          format: uuid
        sku_id:
          type: string
          minLength: 1
          maxLength: 128
        nodes:
          type: array
          minItems: 1
          items:
            "$ref": "#/components/schemas/MaasOnboardingNodeInput"
      required:
      - site_id
      - profile_id
      - sku_id
      - nodes
    AdminStartMaasBatchOnboardingItem:
      type: object
      additionalProperties: false
      properties:
        hostname:
          type: string
          minLength: 1
          maxLength: 255
        onboarding_id:
          type: string
          format: uuid
        status:
          "$ref": "#/components/schemas/MaasWorkflowStatus"
      required:
      - hostname
      - onboarding_id
      - status
    AdminStartMaasBatchOnboardingResponse:
      type: object
      additionalProperties: false
      properties:
        batch_id:
          type: string
          format: uuid
        onboardings:
          type: array
          items:
            "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingItem"
      required:
      - batch_id
      - onboardings
    MaasWorkflowStatus:
      type: string
      enum:
      - pending
      - running
      - completed
      - failed_retryable
      - failed_manual_intervention
      - cancelled
      - compensating
      - reconciled
    MaasWorkflowEventStatus:
      type: string
      enum:
      - started
      - succeeded
      - failed
      - compensated
      - skipped
    MaasOnboardingEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        stage:
          type: string
        attempt:
          type: integer
          minimum: 0
        status:
          "$ref": "#/components/schemas/MaasWorkflowEventStatus"
        message:
          type: string
          nullable: true
        details:
          type: object
          additionalProperties: true
        occurred_at:
          type: string
          format: date-time
      required:
      - id
      - stage
      - attempt
      - status
      - details
      - occurred_at
    MaasOnboarding:
      type: object
      additionalProperties: false
      properties:
        onboarding_id:
          type: string
          format: uuid
        batch_id:
          type: string
          format: uuid
          nullable: true
        node_id:
          type: string
          format: uuid
          nullable: true
        site_id:
          type: string
          format: uuid
        profile_id:
          type: string
          format: uuid
          nullable: true
        sku_id:
          type: string
          minLength: 1
          maxLength: 128
        hostname:
          type: string
        ipmi_ip:
          type: string
        pxe_mac:
          type: string
          nullable: true
        maas_system_id:
          type: string
          nullable: true
        management_interface:
          type: string
          nullable: true
        management_ip:
          type: string
          nullable: true
        management_subnet_cidr:
          type: string
          nullable: true
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        current_stage:
          type: string
        current_attempt:
          type: integer
          minimum: 0
        status:
          "$ref": "#/components/schemas/MaasWorkflowStatus"
        error_code:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
        error_details:
          type: object
          additionalProperties: true
        workflow_id:
          type: string
        workflow_run_id:
          type: string
          nullable: true
        requested_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
        attention_key:
          type: string
          description: Backend-owned operator attention key used by provisioning review
            mutations.
        review_required:
          type: boolean
          description: True when this workflow represents an open operator attention
            item.
        review_state:
          "$ref": "#/components/schemas/V3ProvisioningReviewState"
        reviewed_at:
          type: string
          format: date-time
          nullable: true
        reviewed_by:
          type: string
          nullable: true
        review_note:
          type: string
          nullable: true
        attention_reason:
          type: string
          nullable: true
        next_action:
          type: string
          nullable: true
        superseded_by_workflow_id:
          type: string
          nullable: true
      required:
      - onboarding_id
      - site_id
      - sku_id
      - hostname
      - ipmi_ip
      - current_stage
      - current_attempt
      - status
      - error_details
      - workflow_id
      - requested_at
      - updated_at
      - attention_key
      - review_required
      - review_state
      - reviewed_at
      - reviewed_by
      - review_note
      - attention_reason
      - next_action
      - superseded_by_workflow_id
    MaasOnboardingDetail:
      allOf:
      - "$ref": "#/components/schemas/MaasOnboarding"
      - type: object
        additionalProperties: false
        properties:
          attention_key:
            type: string
            description: Backend-owned operator attention key used by provisioning
              review mutations.
          review_required:
            type: boolean
            description: True when this workflow detail represents an open operator
              attention item.
          review_state:
            "$ref": "#/components/schemas/V3ProvisioningReviewState"
          reviewed_at:
            type: string
            format: date-time
            nullable: true
          reviewed_by:
            type: string
            nullable: true
          review_note:
            type: string
            nullable: true
          attention_reason:
            type: string
            nullable: true
          next_action:
            type: string
            nullable: true
          superseded_by_workflow_id:
            type: string
            nullable: true
          events:
            type: array
            items:
              "$ref": "#/components/schemas/MaasOnboardingEvent"
        required:
        - attention_key
        - review_required
        - review_state
        - reviewed_at
        - reviewed_by
        - review_note
        - attention_reason
        - next_action
        - superseded_by_workflow_id
        - events
    MaasOnboardingInstallOutput:
      type: object
      additionalProperties: false
      properties:
        onboarding_id:
          type: string
          format: uuid
        maas_system_id:
          type: string
        source:
          type: string
          enum:
          - current_installation
        content_type:
          type: string
        output:
          type: string
        fetched_at:
          type: string
          format: date-time
      required:
      - onboarding_id
      - maas_system_id
      - source
      - content_type
      - output
      - fetched_at
    MaasDecommissionInstallOutput:
      type: object
      additionalProperties: false
      properties:
        decommission_id:
          type: string
          format: uuid
        maas_system_id:
          type: string
        source:
          type: string
          enum:
          - current_installation
        content_type:
          type: string
        output:
          type: string
        fetched_at:
          type: string
          format: date-time
      required:
      - decommission_id
      - maas_system_id
      - source
      - content_type
      - output
      - fetched_at
    MaasEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
        level:
          type: string
        type:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
      required:
      - id
      - level
      - type
      - description
      - created_at
    MaasOnboardingEvents:
      type: object
      additionalProperties: false
      properties:
        onboarding_id:
          type: string
          format: uuid
        maas_system_id:
          type: string
        level:
          type: string
          nullable: true
        limit:
          type: integer
        events:
          type: array
          items:
            "$ref": "#/components/schemas/MaasEvent"
        fetched_at:
          type: string
          format: date-time
      required:
      - onboarding_id
      - maas_system_id
      - limit
      - events
      - fetched_at
    MaasOnboardingListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/MaasOnboarding"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    MaasDecommissionEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        stage:
          type: string
        attempt:
          type: integer
          minimum: 0
        status:
          "$ref": "#/components/schemas/MaasWorkflowEventStatus"
        message:
          type: string
          nullable: true
        details:
          type: object
          additionalProperties: true
        occurred_at:
          type: string
          format: date-time
      required:
      - id
      - stage
      - attempt
      - status
      - details
      - occurred_at
    MaasDecommission:
      type: object
      additionalProperties: false
      properties:
        decommission_id:
          type: string
          format: uuid
        node_id:
          type: string
          format: uuid
        site_id:
          type: string
          format: uuid
          nullable: true
        maas_system_id:
          type: string
          nullable: true
        management_interface:
          type: string
          nullable: true
        management_ip:
          type: string
          nullable: true
        management_subnet_cidr:
          type: string
          nullable: true
        mode:
          type: string
          enum:
          - soft_reset
          - reimage
          - full_decommission
          - storage_cleanup
        status:
          "$ref": "#/components/schemas/MaasWorkflowStatus"
        current_stage:
          type: string
        current_attempt:
          type: integer
          minimum: 0
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        error_code:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
        error_details:
          type: object
          additionalProperties: true
        workflow_id:
          type: string
        workflow_run_id:
          type: string
          nullable: true
        requested_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
        attention_key:
          type: string
          description: Backend-owned operator attention key used by provisioning review
            mutations.
        review_required:
          type: boolean
          description: True when this workflow represents an open operator attention
            item.
        review_state:
          "$ref": "#/components/schemas/V3ProvisioningReviewState"
        reviewed_at:
          type: string
          format: date-time
          nullable: true
        reviewed_by:
          type: string
          nullable: true
        review_note:
          type: string
          nullable: true
        attention_reason:
          type: string
          nullable: true
        next_action:
          type: string
          nullable: true
        superseded_by_workflow_id:
          type: string
          nullable: true
      required:
      - decommission_id
      - node_id
      - mode
      - status
      - current_stage
      - current_attempt
      - error_details
      - workflow_id
      - requested_at
      - updated_at
      - attention_key
      - review_required
      - review_state
      - reviewed_at
      - reviewed_by
      - review_note
      - attention_reason
      - next_action
      - superseded_by_workflow_id
    MaasDecommissionDetail:
      allOf:
      - "$ref": "#/components/schemas/MaasDecommission"
      - type: object
        additionalProperties: false
        properties:
          attention_key:
            type: string
            description: Backend-owned operator attention key used by provisioning
              review mutations.
          review_required:
            type: boolean
            description: True when this workflow detail represents an open operator
              attention item.
          review_state:
            "$ref": "#/components/schemas/V3ProvisioningReviewState"
          reviewed_at:
            type: string
            format: date-time
            nullable: true
          reviewed_by:
            type: string
            nullable: true
          review_note:
            type: string
            nullable: true
          attention_reason:
            type: string
            nullable: true
          next_action:
            type: string
            nullable: true
          superseded_by_workflow_id:
            type: string
            nullable: true
          events:
            type: array
            items:
              "$ref": "#/components/schemas/MaasDecommissionEvent"
        required:
        - attention_key
        - review_required
        - review_state
        - reviewed_at
        - reviewed_by
        - review_note
        - attention_reason
        - next_action
        - superseded_by_workflow_id
        - events
    MaasDecommissionEvents:
      type: object
      additionalProperties: false
      properties:
        decommission_id:
          type: string
          format: uuid
        maas_system_id:
          type: string
        level:
          type: string
          nullable: true
        limit:
          type: integer
        events:
          type: array
          items:
            "$ref": "#/components/schemas/MaasEvent"
        fetched_at:
          type: string
          format: date-time
      required:
      - decommission_id
      - maas_system_id
      - limit
      - events
      - fetched_at
    MaasDecommissionListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/MaasDecommission"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AdminStartMaasDecommissionRequest:
      type: object
      additionalProperties: false
      properties:
        mode:
          type: string
          enum:
          - soft_reset
          - reimage
          - full_decommission
          - storage_cleanup
      required:
      - mode
    AdminStartMaasDecommissionResponse:
      type: object
      additionalProperties: false
      properties:
        decommission_id:
          type: string
          format: uuid
        status:
          "$ref": "#/components/schemas/MaasWorkflowStatus"
      required:
      - decommission_id
      - status
    MaasRoceAssignment:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        site_id:
          type: string
          format: uuid
        hostname:
          type: string
        interface:
          type: string
        ipv4_cidr:
          type: string
        status:
          "$ref": "#/components/schemas/MaasRoceAssignmentStatus"
        disabled_at:
          type: string
          format: date-time
          nullable: true
        disabled_by_user_id:
          type: string
          format: uuid
          nullable: true
        disable_reason:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - site_id
      - hostname
      - interface
      - ipv4_cidr
      - status
      - created_at
      - updated_at
    MaasRoceAssignmentStatus:
      type: string
      enum:
      - enabled
      - disabled
    MaasRoceAssignmentListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/MaasRoceAssignment"
      required:
      - items
    MaasReconciliationStatus:
      type: object
      additionalProperties: false
      properties:
        total_nodes:
          type: integer
          minimum: 0
        drifted_nodes:
          type: integer
          minimum: 0
        unresolved_drift_nodes:
          type: integer
          minimum: 0
        reconciled_nodes:
          type: integer
          minimum: 0
        workflow_engine:
          "$ref": "#/components/schemas/MaasReconciliationWorkflowEngineStatus"
        generated_at:
          type: string
          format: date-time
      required:
      - total_nodes
      - drifted_nodes
      - unresolved_drift_nodes
      - reconciled_nodes
      - generated_at
    MaasReconciliationWorkflowEngineStatus:
      type: object
      additionalProperties: false
      properties:
        engine:
          type: string
        connected:
          type: boolean
        schedule_id:
          type: string
        schedule_present:
          type: boolean
        paused:
          type: boolean
        note:
          type: string
          nullable: true
        num_actions:
          type: integer
          minimum: 0
        num_actions_missed_catchup:
          type: integer
          minimum: 0
        num_actions_skipped_overlap:
          type: integer
          minimum: 0
        running_workflow_ids:
          type: array
          items:
            type: string
        recent_workflow_ids:
          type: array
          items:
            type: string
        last_action_scheduled_at:
          type: string
          format: date-time
          nullable: true
        last_action_started_at:
          type: string
          format: date-time
          nullable: true
        next_action_at:
          type: string
          format: date-time
          nullable: true
        error_message:
          type: string
          nullable: true
        checked_at:
          type: string
          format: date-time
      required:
      - engine
      - connected
      - schedule_id
      - schedule_present
      - paused
      - num_actions
      - num_actions_missed_catchup
      - num_actions_skipped_overlap
      - running_workflow_ids
      - recent_workflow_ids
      - checked_at
    MaasDriftRecord:
      type: object
      additionalProperties: false
      properties:
        node_id:
          type: string
          format: uuid
        site_id:
          type: string
          format: uuid
        maas_system_id:
          type: string
        host:
          type: string
        hostname:
          type: string
          nullable: true
        last_maas_status:
          type: string
          nullable: true
        last_maas_power_state:
          type: string
          nullable: true
        last_maas_ips:
          type: array
          items:
            type: string
        last_reconciled_at:
          type: string
          format: date-time
          nullable: true
        drift_detected:
          type: boolean
        drift_details:
          type: object
          additionalProperties: true
        drift_resolved_at:
          type: string
          format: date-time
          nullable: true
      required:
      - node_id
      - site_id
      - maas_system_id
      - host
      - last_maas_ips
      - drift_detected
      - drift_details
    MaasDriftListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/MaasDriftRecord"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AdminNodeEnrollmentTokenResponse:
      type: object
      additionalProperties: false
      properties:
        node_id:
          type: string
          format: uuid
        enrollment_token:
          type: string
          minLength: 1
        expires_in_seconds:
          type: integer
          minimum: 1
        expires_at:
          type: string
          format: date-time
        bootstrap_bundle:
          "$ref": "#/components/schemas/NodeBootstrapBundle"
      required:
      - node_id
      - enrollment_token
      - expires_in_seconds
      - expires_at
      - bootstrap_bundle
    AdminNodeReenrollmentResponse:
      type: object
      additionalProperties: false
      properties:
        node_id:
          type: string
          format: uuid
        enrollment_token:
          type: string
          minLength: 1
        expires_in_seconds:
          type: integer
          minimum: 1
        expires_at:
          type: string
          format: date-time
        recovery_bundle:
          "$ref": "#/components/schemas/NodeReenrollmentBundle"
      required:
      - node_id
      - enrollment_token
      - expires_in_seconds
      - expires_at
      - recovery_bundle
    NodeReenrollmentBundle:
      type: object
      additionalProperties: false
      properties:
        api_url:
          type: string
          format: uri
        terminal_api_url:
          type: string
          format: uri
          nullable: true
        trust_bundle_version:
          type: string
        env_file_path:
          type: string
        cert_path:
          type: string
        key_path:
          type: string
        node_cert_ca_bundle_path:
          type: string
        restart_command:
          type: string
      required:
      - api_url
      - trust_bundle_version
      - env_file_path
      - cert_path
      - key_path
      - node_cert_ca_bundle_path
      - restart_command
    NodeBootstrapBundle:
      type: object
      additionalProperties: false
      properties:
        api_url:
          type: string
          format: uri
        task_signing_pubkeys:
          type: string
          nullable: true
        ca_bundle_pem:
          type: string
          nullable: true
        ca_fingerprint_sha256:
          type: string
          nullable: true
        trust_bundle_version:
          type: string
        ca_bundle_path:
          type: string
        node_cert_ca_bundle_path:
          type: string
        cert_path:
          type: string
        key_path:
          type: string
        package:
          "$ref": "#/components/schemas/NodeBootstrapPackage"
      required:
      - api_url
      - trust_bundle_version
      - ca_bundle_path
      - node_cert_ca_bundle_path
      - cert_path
      - key_path
      - package
    NodeBootstrapPackage:
      type: object
      additionalProperties: false
      properties:
        oci_ref:
          type: string
        digest:
          type: string
        tag:
          type: string
          nullable: true
        registry_api_base_url:
          type: string
          format: uri
          nullable: true
        pull_delivery_mode:
          type: string
          enum:
          - manual
          - vault_wrapped_token
        pull_wrapped_token:
          type: string
          nullable: true
        pull_unwrap_url:
          type: string
          format: uri
          nullable: true
        pull_expires_at:
          type: string
          format: date-time
          nullable: true
        install_root:
          type: string
        env_file_path:
          type: string
        systemd_unit_name:
          type: string
        install_entrypoint:
          type: string
        env_template_path:
          type: string
        service_unit_path:
          type: string
        binary_path:
          type: string
      required:
      - oci_ref
      - digest
      - pull_delivery_mode
      - install_root
      - env_file_path
      - systemd_unit_name
      - install_entrypoint
      - env_template_path
      - service_unit_path
      - binary_path
    NodeBootstrapRegistryCredential:
      type: object
      additionalProperties: false
      properties:
        registry_host:
          type: string
          minLength: 1
        registry_api_base_url:
          type: string
          format: uri
        username:
          type: string
          minLength: 1
        password:
          type: string
          minLength: 1
      required:
      - registry_host
      - registry_api_base_url
      - username
      - password
    AdminNodeBootstrapScriptResponse:
      type: object
      additionalProperties: false
      properties:
        node_id:
          type: string
          format: uuid
        bootstrap_token:
          type: string
          minLength: 1
        expires_in_seconds:
          type: integer
          minimum: 1
        expires_at:
          type: string
          format: date-time
        mode:
          type: string
          enum:
          - manual
          - cloud_init
        script:
          type: string
          minLength: 1
        script_sha256:
          type: string
          minLength: 1
        metadata:
          "$ref": "#/components/schemas/NodeBootstrapScriptMetadata"
      required:
      - node_id
      - bootstrap_token
      - expires_in_seconds
      - expires_at
      - mode
      - script
      - script_sha256
      - metadata
    NodeBootstrapScriptMetadata:
      type: object
      additionalProperties: false
      properties:
        trust_bundle_version:
          type: string
        package_ref:
          type: string
        package_digest:
          type: string
        package_download_url:
          type: string
          format: uri
      required:
      - trust_bundle_version
      - package_ref
      - package_digest
      - package_download_url
    NodeBootstrapProgressRequest:
      type: object
      additionalProperties: false
      properties:
        phase:
          type: string
          enum:
          - site_bootstrap
          - node_bootstrap
          - node_enrollment
        state:
          type: string
          enum:
          - started
          - running
          - in_progress
          - succeeded
          - completed
          - done
          - failed
          - error
          - skipped
        message:
          type: string
        details:
          type: object
          additionalProperties: true
      required:
      - phase
      - state
    NodeBootstrapProgressResponse:
      type: object
      additionalProperties: false
      properties:
        recorded:
          type: boolean
        onboarding_id:
          type: string
          format: uuid
          nullable: true
        attempt:
          type: integer
          minimum: 0
      required:
      - recorded
    Allocation:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        resource_name:
          type: string
          description: Canonical resource identifier in core42:aicloud format.
        requested_by_user_id:
          type: string
          format: uuid
        requested_by_username:
          type: string
          nullable: true
          description: Operator-facing username for the requesting user. Canonical
            identity remains requested_by_user_id.
        requested_by_display_name:
          type: string
          nullable: true
          description: Optional human display name for the requesting user when the
            identity source provides one.
        org_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
          nullable: true
          description: Human project label for operator read models. Canonical scope
            remains project_id.
        node_id:
          type: string
          format: uuid
          nullable: true
        node_hostname:
          type: string
          nullable: true
          description: Human node label for operator read models. Canonical node identity
            remains node_id.
        scheduler_type:
          type: string
          enum:
          - bare_metal
          - slurm
          - k8s
          - ray
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        placement_status:
          "$ref": "#/components/schemas/AllocationPlacementStatus"
        placement_metadata:
          type: object
          additionalProperties: true
          description: Opaque placement read-model metadata. It must not be used as
            the source of scheduling correctness.
        placement_claims:
          type: array
          items:
            "$ref": "#/components/schemas/AllocationPlacementClaim"
          description: Admin read model of durable placement claims. Claims are the
            source of placement correctness for baremetal and slice allocations.
        sku:
          type: string
        gpus_total:
          type: integer
        status:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
        failure_reason:
          type: string
          nullable: true
        provisioning_started_at:
          type: string
          format: date-time
          nullable: true
        active_at:
          type: string
          format: date-time
          nullable: true
        restart_failed_at:
          type: string
          format: date-time
          nullable: true
        restart_failed_reason:
          type: string
          nullable: true
        released_at:
          type: string
          format: date-time
          nullable: true
        release_failed_at:
          type: string
          format: date-time
          nullable: true
        release_failed_reason:
          type: string
          nullable: true
        connection:
          "$ref": "#/components/schemas/AllocationConnection"
          nullable: true
        ssh_keys:
          type: array
          items:
            "$ref": "#/components/schemas/SshPublicKeyRef"
          description: SSH public keys installed for this allocation user account.
        created_at:
          type: string
          format: date-time
      required:
      - id
      - requested_by_user_id
      - org_id
      - project_id
      - scheduler_type
      - sku
      - gpus_total
      - status
      - ssh_keys
      - created_at
    AllocationPlacementClaim:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        allocation_id:
          type: string
          format: uuid
        node_id:
          type: string
          format: uuid
        slot_id:
          type: string
          format: uuid
          nullable: true
        claim_kind:
          type: string
          enum:
          - node_exclusive
          - slot
        status:
          type: string
          enum:
          - reserved
          - provisioning
          - active
          - releasing
          - released
          - failed
        resource_snapshot:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        released_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - allocation_id
      - node_id
      - claim_kind
      - status
      - resource_snapshot
      - created_at
    AllocationConnection:
      type: object
      additionalProperties: false
      properties:
        host:
          type: string
        hostname:
          type: string
          nullable: true
        port:
          type: integer
          minimum: 1
          maximum: 65535
        username_on_node:
          type: string
          description: Stable per-user node username sourced from user POSIX identity
            mapping.
      required:
      - host
      - port
      - username_on_node
    AllocationListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/Allocation"
        limits:
          "$ref": "#/components/schemas/AllocationLimits"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - limits
      - pagination
    AllocationGroupKind:
      type: string
      enum:
      - batch
      - cluster
      - app_runtime
      - shared_runtime
      description: Coarse product intent for a parent group of normal allocations.
        Runtime-specific topology stays in app/runtime-owned contracts.
    AllocationGroupStatus:
      type: string
      enum:
      - requested
      - provisioning
      - active
      - degraded
      - releasing
      - released
      - failed
      - release_failed
      description: Aggregate group status derived from member allocation states and
        group-level release intent. It does not replace member allocation status.
    AllocationGroupOwnerKind:
      type: string
      enum:
      - user_request
      - app_instance
      - shared_app_runtime
    AllocationGroupOwner:
      type: object
      additionalProperties: false
      properties:
        owner_kind:
          "$ref": "#/components/schemas/AllocationGroupOwnerKind"
        owner_id:
          type: string
          format: uuid
          nullable: true
          description: Owning app/runtime id when owner_kind is not user_request.
      required:
      - owner_kind
      - owner_id
    AllocationGroupMemberSummary:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        allocation_group_id:
          type: string
          format: uuid
        allocation_id:
          type: string
          format: uuid
        member_role:
          type: string
          nullable: true
          description: Runtime or product role label such as controller, worker, server,
            or agent. The role meaning is adapter/product-owned.
        ordinal:
          type: integer
          minimum: 0
        required:
          type: boolean
          description: Whether this member is required for the group to be fully active.
        status:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
          description: Current status of the bound allocation.
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        sku:
          type: string
        gpus_total:
          type: integer
        node_id:
          type: string
          format: uuid
          nullable: true
        connection:
          "$ref": "#/components/schemas/AllocationConnection"
          nullable: true
        created_at:
          type: string
          format: date-time
        active_at:
          type: string
          format: date-time
          nullable: true
        released_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - allocation_group_id
      - allocation_id
      - ordinal
      - required
      - status
      - sku
      - gpus_total
      - created_at
    AllocationGroup:
      type: object
      additionalProperties: false
      description: Project-scoped parent resource for a set of normal single-node
        allocations. Member allocations remain the source of billing, placement, connection,
        and release truth.
      properties:
        id:
          type: string
          format: uuid
        resource_name:
          type: string
          description: Canonical resource identifier in core42:aicloud format.
        org_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        requested_by_user_id:
          type: string
          format: uuid
        group_kind:
          "$ref": "#/components/schemas/AllocationGroupKind"
        display_name:
          type: string
          minLength: 1
        status:
          "$ref": "#/components/schemas/AllocationGroupStatus"
        owner:
          "$ref": "#/components/schemas/AllocationGroupOwner"
        desired_member_count:
          type: integer
          minimum: 1
        required_member_count:
          type: integer
          minimum: 0
        active_member_count:
          type: integer
          minimum: 0
        failed_member_count:
          type: integer
          minimum: 0
        releasing_member_count:
          type: integer
          minimum: 0
        released_member_count:
          type: integer
          minimum: 0
        members:
          type: array
          items:
            "$ref": "#/components/schemas/AllocationGroupMemberSummary"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        released_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - resource_name
      - org_id
      - project_id
      - requested_by_user_id
      - group_kind
      - display_name
      - status
      - owner
      - desired_member_count
      - required_member_count
      - active_member_count
      - failed_member_count
      - releasing_member_count
      - released_member_count
      - members
      - created_at
      - updated_at
    AllocationGroupListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AllocationGroup"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    CreateAllocationGroupMemberIntent:
      type: object
      additionalProperties: false
      properties:
        member_role:
          type: string
          nullable: true
          description: Optional role label for the member allocation.
        requested_count:
          type: integer
          minimum: 1
          default: 1
        required:
          type: boolean
          default: true
      required:
      - requested_count
    CreateAllocationGroupRequest:
      type: object
      additionalProperties: false
      description: Request a parent group and one or more normal member allocations.
        The implementation may create members synchronously or continue provisioning
        asynchronously, but each member remains a standard allocation.
      properties:
        display_name:
          type: string
          minLength: 1
        group_kind:
          "$ref": "#/components/schemas/AllocationGroupKind"
        owner:
          "$ref": "#/components/schemas/AllocationGroupOwner"
        sku:
          type: string
          minLength: 1
        scheduler_type:
          type: string
          enum:
          - bare_metal
          - slurm
          - k8s
          - ray
          default: bare_metal
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        member_intents:
          type: array
          minItems: 1
          maxItems: 20
          items:
            "$ref": "#/components/schemas/CreateAllocationGroupMemberIntent"
        ssh_key_ids:
          type: array
          description: Optional SSH key set applied to each created member allocation.
          minItems: 1
          maxItems: 20
          uniqueItems: true
          items:
            type: string
            format: uuid
          nullable: true
        scheduler_request:
          type: object
          additionalProperties: true
      required:
      - display_name
      - group_kind
      - sku
      - scheduler_type
      - member_intents
    CreateAllocationGroupResponse:
      type: object
      additionalProperties: false
      properties:
        allocation_group:
          "$ref": "#/components/schemas/AllocationGroup"
        requested_member_count:
          type: integer
          minimum: 1
        created_member_count:
          type: integer
          minimum: 0
      required:
      - allocation_group
      - requested_member_count
      - created_member_count
    ReleaseAllocationGroupRequest:
      type: object
      additionalProperties: false
      properties:
        release_strategy:
          type: string
          enum:
          - all_members
          - active_or_failed_members
          default: all_members
          description: Controls which member allocations receive release requests.
        reason:
          type: string
          nullable: true
          maxLength: 500
      required:
      - release_strategy
    ReleaseAllocationGroupResponse:
      type: object
      additionalProperties: false
      properties:
        allocation_group:
          "$ref": "#/components/schemas/AllocationGroup"
        release_requested_member_count:
          type: integer
          minimum: 0
      required:
      - allocation_group
      - release_requested_member_count
    AllocationTimelineItem:
      type: object
      additionalProperties: false
      properties:
        kind:
          type: string
          enum:
          - allocation_state
          - placement_claim
          - node_task
        name:
          type: string
        status:
          type: string
          enum:
          - pending
          - running
          - succeeded
          - failed
          - skipped
          - unknown
        task_id:
          type: string
          format: uuid
          nullable: true
        node_id:
          type: string
          format: uuid
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        duration_seconds:
          type: integer
          minimum: 0
          nullable: true
        summary:
          type: string
          nullable: true
      required:
      - kind
      - name
      - status
      - task_id
      - node_id
      - started_at
      - completed_at
      - duration_seconds
      - summary
    AllocationTimelineResponse:
      type: object
      additionalProperties: false
      properties:
        allocation_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
        generated_at:
          type: string
          format: date-time
        next_cursor:
          type: string
          nullable: true
          description: Opaque cursor for the next page of older timeline items.
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AllocationTimelineItem"
      required:
      - allocation_id
      - status
      - generated_at
      - next_cursor
      - items
    AllocationLimits:
      type: object
      additionalProperties: false
      properties:
        max_concurrent_allocations:
          type: integer
          minimum: 1
        current_concurrent_allocations:
          type: integer
          minimum: 0
        available_allocation_slots:
          type: integer
          minimum: 0
      required:
      - max_concurrent_allocations
      - current_concurrent_allocations
      - available_allocation_slots
    AdminIntegerPolicyBounds:
      type: object
      additionalProperties: false
      properties:
        min_value:
          type: integer
          nullable: true
        max_value:
          type: integer
          nullable: true
      required:
      - min_value
      - max_value
    AdminAllocationConcurrencyPolicy:
      type: object
      additionalProperties: false
      properties:
        policy_key:
          type: string
          enum:
          - allocation.max_concurrent_per_user
        description:
          type: string
        value_type:
          type: string
          enum:
          - integer
        scope_type:
          type: string
          enum:
          - global
        value:
          type: integer
          minimum: 1
        default_value:
          type: integer
          minimum: 1
        bounds:
          "$ref": "#/components/schemas/AdminIntegerPolicyBounds"
        effective_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        created_by_user_id:
          type: string
          format: uuid
          nullable: true
        reason:
          type: string
          nullable: true
        correlation_id:
          type: string
          nullable: true
      required:
      - policy_key
      - description
      - value_type
      - scope_type
      - value
      - default_value
      - bounds
      - effective_at
      - created_at
    AdminSetAllocationConcurrencyPolicyRequest:
      type: object
      additionalProperties: false
      properties:
        value:
          type: integer
          minimum: 1
        reason:
          type: string
          nullable: true
          maxLength: 500
      required:
      - value
    AdminBackfillAllocationPlacementClaimsResponse:
      type: object
      additionalProperties: false
      properties:
        candidate_count:
          type: integer
          minimum: 0
        inserted_count:
          type: integer
          minimum: 0
        skipped_count:
          type: integer
          minimum: 0
      required:
      - candidate_count
      - inserted_count
      - skipped_count
    CreateAllocationRequest:
      type: object
      additionalProperties: false
      properties:
        node_id:
          type: string
          format: uuid
          nullable: true
        requested_count:
          type: integer
          minimum: 1
          maximum: 20
          default: 1
          description: Number of independent allocations to request in one API call.
            Each successful result creates a separate single-node allocation.
        ssh_key_ids:
          type: array
          description: Optional per-allocation SSH key set. If omitted, the user's
            active default SSH key is used.
          minItems: 1
          maxItems: 20
          uniqueItems: true
          items:
            type: string
            format: uuid
          nullable: true
        runtime_bundle_id:
          type: string
          format: uuid
          nullable: true
          description: Optional managed runtime bundle to associate with each created
            allocation. The bundle is platform-owned state layered above raw allocation
            provisioning and does not govern arbitrary user SSH-installed packages.
        runtime_bundle_slug:
          type: string
          nullable: true
          description: Optional managed runtime bundle slug. If both id and slug are
            provided, id wins.
        scheduler_type:
          type: string
          enum:
          - bare_metal
          - slurm
          - k8s
          - ray
          default: bare_metal
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
          description: Requested capacity shape. Defaults to baremetal until slice
            SKUs are enabled.
        gpu_count:
          type: integer
          minimum: 1
          description: Requested GPU count for selectable slice products. For fixed
            baremetal products, the SKU determines the count.
        scheduler_request:
          type: object
          additionalProperties: true
      required:
      - scheduler_type
    SetAllocationSshKeysRequest:
      type: object
      additionalProperties: false
      properties:
        ssh_key_ids:
          type: array
          description: Registered SSH key IDs to attach to this allocation. For active
            allocations, the resolved public keys are asynchronously synchronized
            to the existing allocation runtime user's authorized_keys file on the
            node.
          minItems: 1
          maxItems: 20
          uniqueItems: true
          items:
            type: string
            format: uuid
      required:
      - ssh_key_ids
    ManagedRuntimeBundle:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        display_name:
          type: string
        version:
          type: string
        support_level:
          type: string
          enum:
          - supported
          - preview
          - deprecated
        status:
          type: string
          enum:
          - active
          - deprecated
          - disabled
        install_root:
          type: string
        activation_hint:
          type: string
        description:
          type: string
        compatible_accelerators:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - slug
      - display_name
      - version
      - support_level
      - status
      - install_root
      - activation_hint
      - description
      - compatible_accelerators
      - metadata
      - created_at
      - updated_at
    ManagedRuntimeBundleListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/ManagedRuntimeBundle"
      required:
      - items
    AllocationRuntimeBundleStatus:
      type: string
      enum:
      - pending
      - queued
      - active
      - failed
      - removed
    AllocationRuntimeBundle:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        allocation_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        bundle:
          "$ref": "#/components/schemas/ManagedRuntimeBundle"
        status:
          "$ref": "#/components/schemas/AllocationRuntimeBundleStatus"
        apply_task_id:
          type: string
          format: uuid
          nullable: true
        failure_reason:
          type: string
          nullable: true
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        requested_at:
          type: string
          format: date-time
        applied_at:
          type: string
          format: date-time
          nullable: true
        removed_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - allocation_id
      - project_id
      - bundle
      - status
      - requested_at
      - updated_at
    AllocationRuntimeBundleListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AllocationRuntimeBundle"
      required:
      - items
    ApplyAllocationRuntimeBundleRequest:
      type: object
      additionalProperties: false
      properties:
        bundle_id:
          type: string
          format: uuid
          nullable: true
        bundle_slug:
          type: string
          nullable: true
      minProperties: 1
    ApplyAllocationRuntimeBundleResponse:
      type: object
      additionalProperties: false
      properties:
        runtime:
          "$ref": "#/components/schemas/AllocationRuntimeBundle"
      required:
      - runtime
    AllocationAccessGrantStatus:
      type: string
      enum:
      - active
      - revoked
    AllocationAccessGrantRuntimeSyncStatus:
      type: string
      enum:
      - pending
      - queued
      - not_required
      - failed
    AllocationAccessGrant:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        allocation_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        grantee_user_id:
          type: string
          format: uuid
        grantee_username:
          type: string
        ssh_key:
          "$ref": "#/components/schemas/SshPublicKeyRef"
        status:
          "$ref": "#/components/schemas/AllocationAccessGrantStatus"
        runtime_sync_status:
          "$ref": "#/components/schemas/AllocationAccessGrantRuntimeSyncStatus"
        runtime_sync_task_id:
          type: string
          format: uuid
          nullable: true
        runtime_sync_error:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
        created_by_user_id:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
        revoked_by_user_id:
          type: string
          format: uuid
          nullable: true
        revoked_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - allocation_id
      - project_id
      - grantee_user_id
      - grantee_username
      - ssh_key
      - status
      - runtime_sync_status
      - created_at
    AllocationAccessGrantListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AllocationAccessGrant"
      required:
      - items
    CreateAllocationAccessGrantRequest:
      type: object
      additionalProperties: false
      properties:
        grantee_user_id:
          type: string
          format: uuid
          description: Project member receiving access. The referenced SSH key must
            be this user's personal key.
        ssh_key_id:
          type: string
          format: uuid
          description: Personal SSH public key owned by the grantee.
        reason:
          type: string
          maxLength: 500
          nullable: true
      required:
      - grantee_user_id
      - ssh_key_id
    CreateAllocationAccessGrantResponse:
      type: object
      additionalProperties: false
      properties:
        grant:
          "$ref": "#/components/schemas/AllocationAccessGrant"
      required:
      - grant
    RevokeAllocationAccessGrantResponse:
      type: object
      additionalProperties: false
      properties:
        grant:
          "$ref": "#/components/schemas/AllocationAccessGrant"
      required:
      - grant
    CreateAllocationResponse:
      type: object
      additionalProperties: false
      properties:
        allocation:
          "$ref": "#/components/schemas/Allocation"
        allocations:
          type: array
          description: Created allocations for this request. For single-create callers,
            `allocation` is the first item in this array.
          items:
            "$ref": "#/components/schemas/Allocation"
        requested_count:
          type: integer
          minimum: 1
        created_count:
          type: integer
          minimum: 1
        failed_count:
          type: integer
          minimum: 0
      required:
      - allocation
      - allocations
      - requested_count
      - created_count
      - failed_count
    ReleaseAllocationResponse:
      type: object
      additionalProperties: false
      properties:
        allocation:
          "$ref": "#/components/schemas/Allocation"
        operation:
          "$ref": "#/components/schemas/V3WorkloadLifecycleMutationResult"
      required:
      - allocation
    RestartAllocationResponse:
      type: object
      additionalProperties: false
      properties:
        allocation:
          "$ref": "#/components/schemas/Allocation"
        operation:
          "$ref": "#/components/schemas/V3WorkloadLifecycleMutationResult"
      required:
      - allocation
    V3WorkloadLifecycleMutationResult:
      type: object
      additionalProperties: false
      description: Traceable lifecycle submission result returned by workload release
        and restart mutations.
      properties:
        ok:
          type: boolean
        operation:
          type: string
          enum:
          - release
          - restart
        workload_id:
          type: string
          format: uuid
        allocation_id:
          type: string
          format: uuid
        previous_status:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - idle
          - stopped
          - completed
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
          nullable: true
        status:
          "$ref": "#/components/schemas/V3WorkloadStatus"
        correlation_id:
          type: string
        task_href:
          type: string
        evidence_href:
          type: string
      required:
      - ok
      - operation
      - workload_id
      - allocation_id
      - previous_status
      - status
      - correlation_id
      - task_href
      - evidence_href
    AllocationMetrics:
      type: object
      additionalProperties: false
      properties:
        netdata_up:
          type: boolean
        cpu_utilization_pct:
          type: number
          nullable: true
        memory_utilization_pct:
          type: number
          nullable: true
        gpu_utilization_pct:
          type: number
          nullable: true
        gpu_memory_utilization_pct:
          type: number
          nullable: true
        gpu_memory_used_mib:
          type: number
          nullable: true
        gpu_memory_total_mib:
          type: number
          nullable: true
        gpu_power_w:
          type: number
          nullable: true
        gpu_temperature_c:
          type: number
          nullable: true
        gpu_ecc_errors:
          type: integer
          nullable: true
        disk_read_mib_per_s:
          type: number
          nullable: true
        disk_write_mib_per_s:
          type: number
          nullable: true
        network_receive_mib_per_s:
          type: number
          nullable: true
        network_transmit_mib_per_s:
          type: number
          nullable: true
        fabric_receive_mib_per_s:
          type: number
          nullable: true
        fabric_transmit_mib_per_s:
          type: number
          nullable: true
        load1:
          type: number
          nullable: true
        cpu_some_pressure_pct:
          type: number
          nullable: true
        memory_some_pressure_pct:
          type: number
          nullable: true
        io_some_pressure_pct:
          type: number
          nullable: true
        last_error:
          type: string
          nullable: true
        sampled_at:
          type: string
          format: date-time
      required:
      - netdata_up
      - cpu_utilization_pct
      - memory_utilization_pct
      - gpu_utilization_pct
      - gpu_memory_utilization_pct
      - gpu_memory_used_mib
      - gpu_memory_total_mib
      - gpu_power_w
      - gpu_temperature_c
      - gpu_ecc_errors
      - disk_read_mib_per_s
      - disk_write_mib_per_s
      - network_receive_mib_per_s
      - network_transmit_mib_per_s
      - fabric_receive_mib_per_s
      - fabric_transmit_mib_per_s
      - load1
      - cpu_some_pressure_pct
      - memory_some_pressure_pct
      - io_some_pressure_pct
      - last_error
      - sampled_at
    AllocationMetricsCapabilities:
      type: object
      additionalProperties: false
      properties:
        has_gpu_metrics:
          type: boolean
        has_gpu_device_metrics:
          type: boolean
        has_network_interface_metrics:
          type: boolean
        has_fabric_metrics:
          type: boolean
        has_pressure_metrics:
          type: boolean
        has_power_metrics:
          type: boolean
        has_temperature_metrics:
          type: boolean
        has_ecc_metrics:
          type: boolean
      required:
      - has_gpu_metrics
      - has_gpu_device_metrics
      - has_network_interface_metrics
      - has_fabric_metrics
      - has_pressure_metrics
      - has_power_metrics
      - has_temperature_metrics
      - has_ecc_metrics
    AllocationMetricsGPUDevice:
      type: object
      additionalProperties: false
      properties:
        device_id:
          type: string
        name:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        utilization_pct:
          type: number
          nullable: true
        memory_utilization_pct:
          type: number
          nullable: true
        memory_used_mib:
          type: number
          nullable: true
        memory_total_mib:
          type: number
          nullable: true
        power_w:
          type: number
          nullable: true
        temperature_c:
          type: number
          nullable: true
        ecc_errors:
          type: integer
          nullable: true
        health_status:
          type: string
          nullable: true
          enum:
          - healthy
          - warning
          - critical
          - unknown
          - 
      required:
      - device_id
      - name
      - model
      - utilization_pct
      - memory_utilization_pct
      - memory_used_mib
      - memory_total_mib
      - power_w
      - temperature_c
      - ecc_errors
      - health_status
    AllocationMetricsNetworkInterface:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        role:
          type: string
          enum:
          - fabric
          - public
          - storage
          - unknown
        transport_type:
          type: string
          enum:
          - ethernet
          - roce
          - infiniband
          - unknown
        rx_mib_per_s:
          type: number
          nullable: true
        tx_mib_per_s:
          type: number
          nullable: true
        rx_packets_per_s:
          type: number
          nullable: true
        tx_packets_per_s:
          type: number
          nullable: true
        drops_per_s:
          type: number
          nullable: true
        link_speed_mbps:
          type: number
          nullable: true
        utilization_pct:
          type: number
          nullable: true
        operstate:
          type: string
          nullable: true
        carrier_up:
          type: boolean
          nullable: true
      required:
      - name
      - role
      - transport_type
      - rx_mib_per_s
      - tx_mib_per_s
      - rx_packets_per_s
      - tx_packets_per_s
      - drops_per_s
      - link_speed_mbps
      - utilization_pct
      - operstate
      - carrier_up
    AllocationMetricsResponse:
      type: object
      additionalProperties: false
      properties:
        allocation_id:
          type: string
          format: uuid
        node_id:
          type: string
          format: uuid
          nullable: true
        node_host:
          type: string
          nullable: true
        netdata_url:
          type: string
          nullable: true
          description: Browser-facing platform proxy URL for the allocation's Netdata
            dashboard when available.
        status:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
        metrics:
          "$ref": "#/components/schemas/AllocationMetrics"
        capabilities:
          "$ref": "#/components/schemas/AllocationMetricsCapabilities"
        gpu_devices:
          type: array
          items:
            "$ref": "#/components/schemas/AllocationMetricsGPUDevice"
        network_interfaces:
          type: array
          items:
            "$ref": "#/components/schemas/AllocationMetricsNetworkInterface"
      required:
      - allocation_id
      - status
      - metrics
      - capabilities
      - gpu_devices
      - network_interfaces
    AllocationMetricsPoint:
      type: object
      additionalProperties: false
      properties:
        ts:
          type: string
          format: date-time
        value:
          type: number
          nullable: true
      required:
      - ts
      - value
    AllocationMetricsTimeseriesResponse:
      type: object
      additionalProperties: false
      properties:
        allocation_id:
          type: string
          format: uuid
        node_id:
          type: string
          format: uuid
          nullable: true
        node_host:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
        window_seconds:
          type: integer
          minimum: 60
          maximum: 86400
        points:
          type: object
          additionalProperties: false
          properties:
            cpu:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            memory:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            gpu:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            gpu_memory:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            disk_read:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            disk_write:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            network_in:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            network_out:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            fabric_in:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            fabric_out:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            load1:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            cpu_pressure:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            memory_pressure:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
            io_pressure:
              type: array
              items:
                "$ref": "#/components/schemas/AllocationMetricsPoint"
          required:
          - cpu
          - memory
          - gpu
          - gpu_memory
          - disk_read
          - disk_write
          - network_in
          - network_out
          - fabric_in
          - fabric_out
          - load1
          - cpu_pressure
          - memory_pressure
          - io_pressure
      required:
      - allocation_id
      - status
      - window_seconds
      - points
    CreateChargeSessionRequest:
      type: object
      additionalProperties: false
      properties:
        amount_minor:
          type: integer
          minimum: 1
          description: Amount in minor units (e.g., cents).
        currency:
          type: string
          pattern: "^[A-Z]{3}$"
          default: USD
      required:
      - amount_minor
      - currency
    SessionUrlResponse:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
      required:
      - url
    StorageItem:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        resource_name:
          type: string
          description: Canonical resource identifier in core42:aicloud format.
        type:
          type: string
          enum:
          - dir
          - file
        size_bytes:
          type: integer
          nullable: true
        mtime_ms:
          type: integer
          nullable: true
      required:
      - name
      - type
    StorageListResponse:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
        items:
          type: array
          items:
            "$ref": "#/components/schemas/StorageItem"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - path
      - items
      - pagination
    StorageMkdirRequest:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          minLength: 1
      required:
      - path
    StorageRenameRequest:
      type: object
      additionalProperties: false
      properties:
        from:
          type: string
          minLength: 1
        to:
          type: string
          minLength: 1
      required:
      - from
      - to
    AdminCreateUserRequest:
      type: object
      additionalProperties: false
      properties:
        username:
          type: string
          minLength: 1
        oidc_issuer:
          type: string
          minLength: 3
          nullable: true
        oidc_subject:
          type: string
          minLength: 3
          nullable: true
        password:
          type: string
          minLength: 1
          nullable: true
          description: Dev/bootstrap-only local credential path. OIDC anchors are
            primary for production.
        role:
          type: string
          enum:
          - user
          - admin
          default: user
      required:
      - username
      anyOf:
      - required:
        - oidc_issuer
        - oidc_subject
      - required:
        - password
    AdminCreateUserResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
      required:
      - id
    AdminAdjustBalanceRequest:
      type: object
      additionalProperties: false
      properties:
        direction:
          type: string
          enum:
          - credit
          - debit
        amount_minor:
          type: integer
          minimum: 1
        currency:
          type: string
          pattern: "^[A-Z]{3}$"
          default: USD
        reason:
          type: string
      required:
      - direction
      - amount_minor
      - currency
      - reason
    AdminCreateRefundRequest:
      type: object
      additionalProperties: false
      properties:
        amount_minor:
          type: integer
          minimum: 1
        currency:
          type: string
          pattern: "^[A-Z]{3}$"
          default: USD
        reason:
          type: string
          minLength: 3
        payment_reference:
          type: string
          description: Provider payment/session reference for traceability.
        mode:
          type: string
          enum:
          - auto_policy
          - force_internal_credit
          default: auto_policy
          description: |
            auto_policy applies hybrid refund policy:
            provider refund in-window, internal credit fallback out-of-window.
      required:
      - amount_minor
      - currency
      - reason
    AdminCreateRefundResponse:
      type: object
      additionalProperties: false
      properties:
        refund_id:
          type: string
          format: uuid
        outcome:
          type: string
          nullable: true
          enum:
          - provider_refund
          - internal_credit
        status:
          type: string
          enum:
          - accepted
          - completed
          - failed
        amount:
          "$ref": "#/components/schemas/Money"
        policy_applied:
          type: object
          additionalProperties: false
          properties:
            refund_window_days:
              type: integer
            in_window:
              type: boolean
            unused_balance_rule_applied:
              type: boolean
          required:
          - refund_window_days
          - in_window
          - unused_balance_rule_applied
      required:
      - refund_id
      - status
      - amount
      - policy_applied
    PaymentSession:
      type: object
      additionalProperties: false
      description: Tracks a Stripe checkout session from initiation through credit
        posting.
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        initiated_by_user_id:
          type: string
          format: uuid
        stripe_checkout_session_id:
          type: string
        stripe_payment_intent_id:
          type: string
          nullable: true
        requested_amount:
          "$ref": "#/components/schemas/Money"
        credited_amount:
          allOf:
          - "$ref": "#/components/schemas/Money"
          nullable: true
          description: Actual credited amount from Stripe webhook; should equal requested_amount.
        status:
          type: string
          enum:
          - initiated
          - checkout_completed
          - credited
          - failed_reconcile
          - expired
        initiated_at:
          type: string
          format: date-time
        checkout_completed_at:
          type: string
          format: date-time
          nullable: true
        credited_at:
          type: string
          format: date-time
          nullable: true
        failed_at:
          type: string
          format: date-time
          nullable: true
        failure_reason:
          type: string
          nullable: true
        ledger_entry_id:
          type: string
          format: uuid
          nullable: true
        correlation_id:
          type: string
        created_at:
          type: string
          format: date-time
      required:
      - id
      - org_id
      - initiated_by_user_id
      - stripe_checkout_session_id
      - requested_amount
      - status
      - initiated_at
      - correlation_id
      - created_at
    AdminReconcilePaymentSessionRequest:
      type: object
      additionalProperties: false
      properties:
        action:
          type: string
          enum:
          - post_credit
          - mark_expired
          - mark_failed
        amount_minor:
          type: integer
          minimum: 1
          description: Optional override for post_credit; defaults to credited amount
            or requested amount.
        reason:
          type: string
          minLength: 3
        failure_reason:
          type: string
          description: Operator-visible failure reason when action is mark_failed.
      required:
      - action
      - reason
    RefundRequest:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        amount:
          "$ref": "#/components/schemas/Money"
        reason:
          type: string
        payment_reference:
          type: string
          nullable: true
        mode:
          type: string
          enum:
          - auto_policy
          - force_internal_credit
        outcome:
          type: string
          nullable: true
          enum:
          - provider_refund
          - internal_credit
        status:
          type: string
          enum:
          - accepted
          - completed
          - failed
        provider_refund_id:
          type: string
          nullable: true
        internal_ledger_entry_id:
          type: string
          format: uuid
          nullable: true
        correlation_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - org_id
      - user_id
      - amount
      - reason
      - mode
      - status
      - correlation_id
      - created_at
      - updated_at
    RefundListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/RefundRequest"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    BillingReconciliationSummary:
      type: object
      additionalProperties: false
      properties:
        checked_at:
          type: string
          format: date-time
        missing_open_usage_count:
          type: integer
          minimum: 0
        orphan_open_usage_count:
          type: integer
          minimum: 0
        unbilled_closed_usage_count:
          type: integer
          minimum: 0
        sample_allocation_id:
          type: string
          format: uuid
          nullable: true
        sample_usage_id:
          type: string
          format: uuid
          nullable: true
        severity:
          type: string
          enum:
          - ok
          - warn
          - error
      required:
      - checked_at
      - missing_open_usage_count
      - orphan_open_usage_count
      - unbilled_closed_usage_count
      - severity
    BillingReconciliationRun:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        status:
          type: string
          enum:
          - running
          - completed
          - failed
        summary:
          "$ref": "#/components/schemas/BillingReconciliationSummary"
        failure_reason:
          type: string
          nullable: true
        correlation_id:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - status
      - summary
      - correlation_id
      - created_at
    BillingReconciliationListResponse:
      type: object
      additionalProperties: false
      properties:
        current:
          "$ref": "#/components/schemas/BillingReconciliationSummary"
        runs:
          type: array
          items:
            "$ref": "#/components/schemas/BillingReconciliationRun"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - current
      - runs
      - pagination
    BillingDiagnosticsResponse:
      type: object
      additionalProperties: false
      properties:
        correlation_id:
          type: string
        payment_sessions:
          type: array
          items:
            "$ref": "#/components/schemas/PaymentSession"
        refunds:
          type: array
          items:
            "$ref": "#/components/schemas/RefundRequest"
        usage_records:
          type: array
          items:
            "$ref": "#/components/schemas/UsageRecord"
        ledger_entries:
          type: array
          items:
            "$ref": "#/components/schemas/BillingLedgerEntry"
        audit_logs:
          type: array
          items:
            "$ref": "#/components/schemas/BillingAuditEvidence"
      required:
      - correlation_id
      - payment_sessions
      - refunds
      - usage_records
      - ledger_entries
      - audit_logs
    BillingLedgerEntry:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        entry_type:
          type: string
        amount:
          "$ref": "#/components/schemas/Money"
        reference_type:
          type: string
          nullable: true
        reference_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
      required:
      - id
      - user_id
      - entry_type
      - amount
      - created_at
    BillingAuditEvidence:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        actor_user_id:
          type: string
          format: uuid
          nullable: true
        actor_role:
          type: string
        action:
          type: string
        target_type:
          type: string
        target_id:
          type: string
        result:
          type: string
        correlation_id:
          type: string
        occurred_at:
          type: string
          format: date-time
      required:
      - id
      - actor_role
      - action
      - target_type
      - target_id
      - result
      - correlation_id
      - occurred_at
    ServiceAccount:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
          nullable: true
        purpose:
          type: string
          enum:
          - operator
          - controller
          - automation
          description: 'User-facing intent for the service account. `controller` identities
            are platform/app-controller credentials and must not be offered as app
            operator runtime identities.

'
          default: operator
        state:
          type: string
          enum:
          - active
          - disabled
          - deleted
        created_by_user_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        disabled_at:
          type: string
          format: date-time
          nullable: true
        deleted_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - org_id
      - project_id
      - name
      - slug
      - state
      - created_by_user_id
      - created_at
    ServiceAccountListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/ServiceAccount"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    CreateServiceAccountRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
        slug:
          type: string
          minLength: 1
          maxLength: 128
        description:
          type: string
          nullable: true
          maxLength: 512
        purpose:
          type: string
          enum:
          - operator
          - controller
          - automation
      required:
      - name
      - slug
    CreateServiceAccountResponse:
      type: object
      additionalProperties: false
      properties:
        service_account:
          "$ref": "#/components/schemas/ServiceAccount"
        initial_credential:
          "$ref": "#/components/schemas/ServiceAccountCredentialSecret"
      required:
      - service_account
      - initial_credential
    RotateServiceAccountCredentialResponse:
      type: object
      additionalProperties: false
      properties:
        service_account:
          "$ref": "#/components/schemas/ServiceAccount"
        credential:
          "$ref": "#/components/schemas/ServiceAccountCredentialSecret"
      required:
      - service_account
      - credential
    ServiceAccountCredentialSecret:
      type: object
      additionalProperties: false
      description: One-time credential material. client_secret is returned only on
        create/rotate.
      properties:
        key_id:
          type: string
        client_secret:
          type: string
        algorithm:
          type: string
        created_at:
          type: string
          format: date-time
      required:
      - key_id
      - client_secret
      - algorithm
      - created_at
    ServiceAccountTokenRequest:
      type: object
      additionalProperties: false
      properties:
        service_account_id:
          type: string
          format: uuid
        key_id:
          type: string
          minLength: 1
          maxLength: 128
        client_secret:
          type: string
          minLength: 16
          maxLength: 512
          description: Plaintext credential secret; server verifies against encrypted
            credential record.
        audience:
          type: string
          minLength: 1
          maxLength: 256
        scope:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 128
      required:
      - service_account_id
      - key_id
      - client_secret
    ServiceAccountTokenResponse:
      type: object
      additionalProperties: false
      properties:
        access_token:
          type: string
        expires_in_seconds:
          type: integer
          minimum: 1
        token_type:
          type: string
          enum:
          - Bearer
      required:
      - access_token
      - expires_in_seconds
      - token_type
    SharedRuntimeOperatorTokenRequest:
      type: object
      additionalProperties: false
      description: 'Token request for a delegated tenant-shared runtime operator identity.

'
      properties:
        shared_runtime_id:
          type: string
          format: uuid
        key_id:
          type: string
          minLength: 1
          maxLength: 128
        client_secret:
          type: string
          minLength: 16
          maxLength: 512
          description: Plaintext delegated operator secret; server verifies against
            encrypted credential record.
        audience:
          type: string
          minLength: 1
          maxLength: 256
        scope:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 128
      required:
      - shared_runtime_id
      - key_id
      - client_secret
    SharedRuntimeOperatorTokenResponse:
      type: object
      additionalProperties: false
      properties:
        access_token:
          type: string
        expires_in_seconds:
          type: integer
          minimum: 1
        token_type:
          type: string
          enum:
          - Bearer
      required:
      - access_token
      - expires_in_seconds
      - token_type
    SharedRuntimeOperatorTokenClaims:
      type: object
      additionalProperties: false
      description: 'Claim shape for delegated shared-runtime operator tokens.

'
      properties:
        sub:
          type: string
          minLength: 1
        actor_type:
          type: string
          enum:
          - shared_runtime_operator
        org_id:
          type: string
          format: uuid
        shared_runtime_id:
          type: string
          format: uuid
        scope:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 128
        iss:
          type: string
          minLength: 1
        aud:
          type: string
          minLength: 1
        iat:
          type: integer
          minimum: 0
        exp:
          type: integer
          minimum: 0
        jti:
          type: string
          minLength: 1
      required:
      - sub
      - actor_type
      - org_id
      - shared_runtime_id
      - iss
      - aud
      - iat
      - exp
      - jti
    AccessCredentialScopeType:
      type: string
      enum:
      - platform
      - tenant
      - project
    AccessCredentialOperationalDomain:
      type: string
      enum:
      - platform-control
      - platform-ops
      - tenant-runtime
    AccessCredentialKind:
      type: string
      enum:
      - ssh_key
      - password
      - token
      - certificate_bundle
    AccessCredentialCustodyBackend:
      type: string
      enum:
      - vault
    AccessCredentialDeliveryMode:
      type: string
      enum:
      - vault_ref
      - vault_wrapped_token
    AccessCredentialStatus:
      type: string
      enum:
      - active
      - disabled
      - rotation_pending
      - expired
      - deleted
    AccessCredentialData:
      type: object
      additionalProperties:
        type: string
      minProperties: 1
      description: Generic secret payload stored under the credential custody backend.
        Keys are app- and kind-specific.
    AccessCredentialBinding:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        credential_id:
          type: string
          format: uuid
        resource_type:
          type: string
          maxLength: 128
        resource_id:
          type: string
          maxLength: 255
        purpose:
          type: string
          maxLength: 128
          description: Binding purpose such as app_bootstrap_ssh.
        usage_tags:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
        created_at:
          type: string
          format: date-time
      required:
      - id
      - credential_id
      - resource_type
      - resource_id
      - purpose
      - usage_tags
      - created_at
    AdminAccessCredential:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        description:
          type: string
          nullable: true
        scope_type:
          "$ref": "#/components/schemas/AccessCredentialScopeType"
        scope_id:
          type: string
          format: uuid
          nullable: true
        resource_type:
          type: string
          nullable: true
          maxLength: 128
        resource_id:
          type: string
          nullable: true
          maxLength: 255
        bindings:
          type: array
          items:
            "$ref": "#/components/schemas/AccessCredentialBinding"
        operational_domain:
          "$ref": "#/components/schemas/AccessCredentialOperationalDomain"
        credential_kind:
          "$ref": "#/components/schemas/AccessCredentialKind"
        usage_tags:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
        principal_username:
          type: string
          nullable: true
          maxLength: 255
          description: Optional username paired with the credential for registry/basic-auth
            style use cases.
        custody_backend:
          "$ref": "#/components/schemas/AccessCredentialCustodyBackend"
        custody_instance:
          type: string
          minLength: 1
          maxLength: 128
        delivery_mode:
          "$ref": "#/components/schemas/AccessCredentialDeliveryMode"
        vault_path:
          type: string
          nullable: true
          description: Backend reference for Vault-backed custody. Metadata only;
            not a secret reveal surface.
        status:
          "$ref": "#/components/schemas/AccessCredentialStatus"
        last_validated_at:
          type: string
          format: date-time
          nullable: true
        last_used_at:
          type: string
          format: date-time
          nullable: true
        rotation_due_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - display_name
      - scope_type
      - operational_domain
      - credential_kind
      - usage_tags
      - custody_backend
      - custody_instance
      - delivery_mode
      - status
      - created_at
      - updated_at
    ProjectAccessCredential:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        description:
          type: string
          nullable: true
        scope_type:
          "$ref": "#/components/schemas/AccessCredentialScopeType"
        scope_id:
          type: string
          format: uuid
          nullable: true
        resource_type:
          type: string
          nullable: true
          maxLength: 128
        resource_id:
          type: string
          nullable: true
          maxLength: 255
        bindings:
          type: array
          items:
            "$ref": "#/components/schemas/AccessCredentialBinding"
        operational_domain:
          "$ref": "#/components/schemas/AccessCredentialOperationalDomain"
        credential_kind:
          "$ref": "#/components/schemas/AccessCredentialKind"
        usage_tags:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
        principal_username:
          type: string
          nullable: true
          maxLength: 255
          description: Optional username paired with the credential for SSH or basic-auth
            style use cases.
        custody_backend:
          "$ref": "#/components/schemas/AccessCredentialCustodyBackend"
        custody_instance:
          type: string
          minLength: 1
          maxLength: 128
        delivery_mode:
          "$ref": "#/components/schemas/AccessCredentialDeliveryMode"
        vault_path:
          type: string
          nullable: true
          description: Backend reference for Vault-backed custody. Metadata only;
            not a secret reveal surface.
        status:
          "$ref": "#/components/schemas/AccessCredentialStatus"
        last_validated_at:
          type: string
          format: date-time
          nullable: true
        last_used_at:
          type: string
          format: date-time
          nullable: true
        rotation_due_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - display_name
      - scope_type
      - operational_domain
      - credential_kind
      - usage_tags
      - custody_backend
      - custody_instance
      - delivery_mode
      - status
      - created_at
      - updated_at
    ProjectAccessCredentialListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/ProjectAccessCredential"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AdminAccessCredentialListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AdminAccessCredential"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AdminCreateAccessCredentialRequest:
      type: object
      additionalProperties: false
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 128
        description:
          type: string
          nullable: true
          maxLength: 512
        scope_type:
          "$ref": "#/components/schemas/AccessCredentialScopeType"
        scope_id:
          type: string
          format: uuid
          nullable: true
        resource_type:
          type: string
          nullable: true
          maxLength: 128
        resource_id:
          type: string
          nullable: true
          maxLength: 255
        operational_domain:
          "$ref": "#/components/schemas/AccessCredentialOperationalDomain"
        credential_kind:
          "$ref": "#/components/schemas/AccessCredentialKind"
        usage_tags:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
            maxLength: 64
        principal_username:
          type: string
          nullable: true
          maxLength: 255
        custody_backend:
          "$ref": "#/components/schemas/AccessCredentialCustodyBackend"
        custody_instance:
          type: string
          minLength: 1
          maxLength: 128
        delivery_mode:
          "$ref": "#/components/schemas/AccessCredentialDeliveryMode"
        credential_data:
          "$ref": "#/components/schemas/AccessCredentialData"
      required:
      - display_name
      - scope_type
      - operational_domain
      - credential_kind
      - usage_tags
      - custody_backend
      - custody_instance
      - delivery_mode
      - credential_data
    AdminCreateAccessCredentialResponse:
      type: object
      additionalProperties: false
      properties:
        credential:
          "$ref": "#/components/schemas/AdminAccessCredential"
      required:
      - credential
    AdminUpdateAccessCredentialRequest:
      type: object
      additionalProperties: false
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 128
        description:
          type: string
          nullable: true
          maxLength: 512
        resource_type:
          type: string
          nullable: true
          maxLength: 128
        resource_id:
          type: string
          nullable: true
          maxLength: 255
        usage_tags:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
        principal_username:
          type: string
          nullable: true
          maxLength: 255
        status:
          description: Metadata-level enable/disable control. Secret material changes
            must use rotate.
          allOf:
          - "$ref": "#/components/schemas/AccessCredentialStatus"
    AdminRotateAccessCredentialRequest:
      type: object
      additionalProperties: false
      properties:
        principal_username:
          type: string
          nullable: true
          maxLength: 255
        rotation_reason:
          type: string
          nullable: true
          maxLength: 512
        credential_data:
          "$ref": "#/components/schemas/AccessCredentialData"
      required:
      - credential_data
    ProjectCreateAccessCredentialRequest:
      type: object
      additionalProperties: false
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 128
        description:
          type: string
          nullable: true
          maxLength: 512
        resource_type:
          type: string
          nullable: true
          maxLength: 128
        resource_id:
          type: string
          nullable: true
          maxLength: 255
        operational_domain:
          "$ref": "#/components/schemas/AccessCredentialOperationalDomain"
        credential_kind:
          "$ref": "#/components/schemas/AccessCredentialKind"
        usage_tags:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
            maxLength: 64
        principal_username:
          type: string
          nullable: true
          maxLength: 255
        custody_backend:
          "$ref": "#/components/schemas/AccessCredentialCustodyBackend"
        custody_instance:
          type: string
          minLength: 1
          maxLength: 128
        delivery_mode:
          "$ref": "#/components/schemas/AccessCredentialDeliveryMode"
        credential_data:
          "$ref": "#/components/schemas/AccessCredentialData"
      required:
      - display_name
      - operational_domain
      - credential_kind
      - usage_tags
      - custody_backend
      - custody_instance
      - delivery_mode
      - credential_data
    ProjectCreateAccessCredentialResponse:
      type: object
      additionalProperties: false
      properties:
        credential:
          "$ref": "#/components/schemas/ProjectAccessCredential"
      required:
      - credential
    ProjectUpdateAccessCredentialRequest:
      type: object
      additionalProperties: false
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 128
          nullable: true
        description:
          type: string
          nullable: true
          maxLength: 512
        resource_type:
          type: string
          nullable: true
          maxLength: 128
        resource_id:
          type: string
          nullable: true
          maxLength: 255
        usage_tags:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
        principal_username:
          type: string
          nullable: true
          maxLength: 255
        status:
          type: string
          enum:
          - active
          - disabled
          - rotation_pending
          - expired
          - deleted
          nullable: true
    ProjectRotateAccessCredentialRequest:
      type: object
      additionalProperties: false
      properties:
        principal_username:
          type: string
          nullable: true
          maxLength: 255
        rotation_reason:
          type: string
          nullable: true
          maxLength: 512
        credential_data:
          "$ref": "#/components/schemas/AccessCredentialData"
      required:
      - credential_data
    ProjectDeliverAccessCredentialRequest:
      type: object
      additionalProperties: false
      properties:
        wrap_ttl_seconds:
          type: integer
          minimum: 1
          maximum: 3600
          description: Optional wrapped delivery TTL. Only used for `vault_wrapped_token`.
    AccessCredentialDelivery:
      type: object
      additionalProperties: false
      properties:
        mode:
          "$ref": "#/components/schemas/AccessCredentialDeliveryMode"
        vault_path:
          type: string
          nullable: true
        wrapped_token:
          type: string
          nullable: true
        unwrap_url:
          type: string
          nullable: true
          description: Vault unwrap endpoint for wrapped delivery flows.
        expires_at:
          type: string
          format: date-time
          nullable: true
      required:
      - mode
    ProjectDeliverAccessCredentialResponse:
      type: object
      additionalProperties: false
      properties:
        credential:
          "$ref": "#/components/schemas/ProjectAccessCredential"
        delivery:
          "$ref": "#/components/schemas/AccessCredentialDelivery"
      required:
      - credential
      - delivery
    AdminCreateNodeRequest:
      type: object
      additionalProperties: false
      properties:
        host:
          type: string
          minLength: 3
        hostname:
          type: string
          minLength: 3
          nullable: true
        port:
          type: integer
          minimum: 1
          maximum: 65535
          default: 22
        sku:
          type: string
          minLength: 1
        gpus_total:
          type: integer
          minimum: 1
        region_code:
          type: string
          default: region-maas-1
        onboarding_mode:
          type: string
          enum:
          - manual
          - maas
          default: manual
          description: Registration mode. manual = operator installs bootstrap bundle.
            maas = legacy/bootstrap MAAS path; prefer dedicated `/api/v1/admin/onboardings`
            endpoints for new MAAS onboarding flows.
        probe:
          type: boolean
          default: true
      required:
      - host
      - sku
      - gpus_total
    AdminSku:
      type: object
      additionalProperties: false
      properties:
        sku:
          type: string
          minLength: 1
        vendor:
          type: string
          minLength: 1
        display_name:
          type: string
          minLength: 1
        gpus_total:
          type: integer
          minimum: 1
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        allowed_gpu_counts:
          type: array
          items:
            type: integer
            minimum: 1
          description: Approved GPU counts for selectable slice products.
        resource_profile:
          type: object
          additionalProperties: true
          description: SKU-level capacity and topology hints such as default vCPU,
            memory, fabric, and allowed topology groups.
        active:
          type: boolean
        price_per_gpu_hour:
          type: object
          additionalProperties: false
          properties:
            amount_minor:
              type: integer
              minimum: 0
            currency:
              type: string
              minLength: 3
              maxLength: 3
          required:
          - amount_minor
          - currency
      required:
      - sku
      - vendor
      - display_name
      - gpus_total
      - active
      - price_per_gpu_hour
    AdminCreateSkuRequest:
      type: object
      additionalProperties: false
      properties:
        sku:
          type: string
          minLength: 1
        vendor:
          type: string
          minLength: 1
        display_name:
          type: string
          minLength: 1
        gpus_total:
          type: integer
          minimum: 1
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        allowed_gpu_counts:
          type: array
          items:
            type: integer
            minimum: 1
        resource_profile:
          type: object
          additionalProperties: true
        price_per_gpu_hour:
          type: object
          additionalProperties: false
          properties:
            amount_minor:
              type: integer
              minimum: 0
            currency:
              type: string
              minLength: 3
              maxLength: 3
          required:
          - amount_minor
          - currency
      required:
      - sku
      - vendor
      - display_name
      - gpus_total
      - price_per_gpu_hour
    AdminUpdateSkuRequest:
      type: object
      additionalProperties: false
      properties:
        vendor:
          type: string
          minLength: 1
        display_name:
          type: string
          minLength: 1
        gpus_total:
          type: integer
          minimum: 1
        capacity_shape:
          "$ref": "#/components/schemas/CapacityShape"
        allowed_gpu_counts:
          type: array
          items:
            type: integer
            minimum: 1
        resource_profile:
          type: object
          additionalProperties: true
        price_per_gpu_hour:
          type: object
          additionalProperties: false
          properties:
            amount_minor:
              type: integer
              minimum: 0
            currency:
              type: string
              minLength: 3
              maxLength: 3
          required:
          - amount_minor
          - currency
      required:
      - vendor
      - display_name
      - gpus_total
      - price_per_gpu_hour
    AdminSkuListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AdminSku"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AuditLogEntry:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        actor_user_id:
          type: string
          format: uuid
          nullable: true
        actor_service_account_id:
          type: string
          format: uuid
          nullable: true
        actor_role:
          type: string
          enum:
          - user
          - admin
          - service_account
          - system
        action:
          type: string
        target_type:
          type: string
        target_id:
          type: string
          nullable: true
        result:
          type: string
          enum:
          - success
          - failure
        correlation_id:
          type: string
        occurred_at:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
        presentation:
          "$ref": "#/components/schemas/AuditLogPresentation"
      required:
      - id
      - actor_role
      - action
      - target_type
      - result
      - correlation_id
      - occurred_at
    AuditLogPresentation:
      type: object
      additionalProperties: false
      description: Backend-owned display model for audit/evidence surfaces. Raw audit
        fields remain authoritative.
      properties:
        actor_label:
          type: string
        target_label:
          type: string
        target_type_label:
          type: string
        action_label:
          type: string
        action_category:
          type: string
        action_family:
          type: string
        summary:
          type: string
        result_label:
          type: string
        severity:
          type: string
          enum:
          - info
          - success
          - warning
          - error
          - critical
        safe_details:
          type: object
          additionalProperties: true
          description: Allowlisted metadata suitable for operator display. Raw metadata
            remains available for authorized debugging.
        debug_refs:
          type: object
          additionalProperties: false
          properties:
            correlation_id:
              type: string
            trace_id:
              type: string
              nullable: true
            request_id:
              type: string
              nullable: true
            actor_ref:
              type: string
              nullable: true
            target_ref:
              type: string
              nullable: true
          required:
          - correlation_id
      required:
      - actor_label
      - target_label
      - target_type_label
      - action_label
      - action_category
      - action_family
      - summary
      - result_label
      - severity
      - debug_refs
    AuditLogListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AuditLogEntry"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AdminOverviewResponse:
      type: object
      additionalProperties: false
      properties:
        total_nodes:
          type: integer
          minimum: 0
        online_nodes:
          type: integer
          minimum: 0
        active_allocations:
          type: integer
          minimum: 0
        total_users:
          type: integer
          minimum: 0
        generated_at:
          type: string
          format: date-time
      required:
      - total_nodes
      - online_nodes
      - active_allocations
      - total_users
      - generated_at
    AdminOpsOverviewResponse:
      type: object
      additionalProperties: false
      description: Aggregated operational telemetry snapshot for the admin ops dashboard.
      properties:
        generated_at:
          type: string
          format: date-time
        stale_seconds:
          type: integer
          minimum: 0
        service_health:
          type: object
          additionalProperties: false
          properties:
            api_ok:
              type: boolean
            billing_worker_ok:
              type: boolean
            provisioning_worker_ok:
              type: boolean
            outbox_relay_ok:
              type: boolean
            outbox_relay_runbook_id:
              type: string
              nullable: true
          required:
          - api_ok
          - billing_worker_ok
          - provisioning_worker_ok
          - outbox_relay_ok
          - outbox_relay_runbook_id
        queue_depth:
          type: object
          additionalProperties: false
          properties:
            outbox_pending:
              type: integer
              minimum: 0
            dlq_pending:
              type: integer
              minimum: 0
            dlq_runbook_id:
              type: string
              nullable: true
          required:
          - outbox_pending
          - dlq_pending
          - dlq_runbook_id
        throughput_5m:
          type: object
          additionalProperties: false
          properties:
            allocations_activated:
              type: integer
              minimum: 0
            allocations_released:
              type: integer
              minimum: 0
            payments_credited:
              type: integer
              minimum: 0
          required:
          - allocations_activated
          - allocations_released
          - payments_credited
        error_rate_5m:
          type: object
          additionalProperties: false
          properties:
            api_5xx_per_min:
              type: number
              minimum: 0
            worker_failures_per_min:
              type: number
              minimum: 0
            api_5xx_runbook_id:
              type: string
              nullable: true
            worker_failures_runbook_id:
              type: string
              nullable: true
          required:
          - api_5xx_per_min
          - worker_failures_per_min
          - api_5xx_runbook_id
          - worker_failures_runbook_id
        control_plane:
          type: object
          additionalProperties: false
          properties:
            nats_connected:
              type: boolean
            api_ratelimit_fail_open_total:
              type: integer
              minimum: 0
            api_idempotency_replays_served_total:
              type: integer
              minimum: 0
            terminal_token_consumed_ok_total:
              type: integer
              minimum: 0
            terminal_token_replay_rejected_total:
              type: integer
              minimum: 0
            ws_notifications_active_connections:
              type: integer
              minimum: 0
            ws_notifications_write_errors_total:
              type: integer
              minimum: 0
            platform_role_list_requests_total:
              type: integer
              minimum: 0
            platform_role_bind_requests_total:
              type: integer
              minimum: 0
            platform_role_revoke_requests_total:
              type: integer
              minimum: 0
            platform_role_mutation_success_total:
              type: integer
              minimum: 0
            platform_role_mutation_failure_total:
              type: integer
              minimum: 0
            platform_role_admin_denied_total:
              type: integer
              minimum: 0
            platform_role_service_unavailable_total:
              type: integer
              minimum: 0
          required:
          - nats_connected
          - api_ratelimit_fail_open_total
          - api_idempotency_replays_served_total
          - terminal_token_consumed_ok_total
          - terminal_token_replay_rejected_total
          - ws_notifications_active_connections
          - ws_notifications_write_errors_total
          - platform_role_list_requests_total
          - platform_role_bind_requests_total
          - platform_role_revoke_requests_total
          - platform_role_mutation_success_total
          - platform_role_mutation_failure_total
          - platform_role_admin_denied_total
          - platform_role_service_unavailable_total
        node_metrics:
          type: object
          additionalProperties: false
          properties:
            summary:
              type: object
              additionalProperties: false
              properties:
                total_nodes:
                  type: integer
                  minimum: 0
                active_nodes:
                  type: integer
                  minimum: 0
                sampled_nodes:
                  type: integer
                  minimum: 0
                netdata_reachable_nodes:
                  type: integer
                  minimum: 0
                gpu_reporting_nodes:
                  type: integer
                  minimum: 0
              required:
              - total_nodes
              - active_nodes
              - sampled_nodes
              - netdata_reachable_nodes
              - gpu_reporting_nodes
            sample:
              type: array
              maxItems: 20
              items:
                type: object
                additionalProperties: false
                properties:
                  node_id:
                    type: string
                    format: uuid
                  host:
                    type: string
                  status:
                    type: string
                  netdata_up:
                    type: boolean
                  cpu_utilization_pct:
                    type: number
                    nullable: true
                  gpu_utilization_pct:
                    type: number
                    nullable: true
                  gpu_memory_utilization_pct:
                    type: number
                    nullable: true
                  last_error:
                    type: string
                    nullable: true
                  sampled_at:
                    type: string
                    format: date-time
                required:
                - node_id
                - host
                - status
                - netdata_up
                - cpu_utilization_pct
                - gpu_utilization_pct
                - gpu_memory_utilization_pct
                - last_error
                - sampled_at
          required:
          - summary
          - sample
      required:
      - generated_at
      - stale_seconds
      - service_health
      - queue_depth
      - throughput_5m
      - error_rate_5m
      - control_plane
      - node_metrics
    AdminRuntimeMetadataResponse:
      type: object
      additionalProperties: false
      description: Live runtime metadata for platform-control services visible to
        platform operators.
      properties:
        generated_at:
          type: string
          format: date-time
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AdminRuntimeMetadataItem"
      required:
      - generated_at
      - items
    AdminRuntimeMetadataItem:
      type: object
      additionalProperties: false
      properties:
        service_name:
          type: string
          description: Kubernetes deployment or logical runtime service name.
        component:
          type: string
          description: Runtime component within the service, for example api.
        runtime_kind:
          type: string
          enum:
          - go_service
          - web
          - worker
          - controller
          - unknown
        version:
          type: string
          description: Build version linked into the running binary when available.
        commit:
          type: string
          description: Git commit linked into the running binary or supplied by deployment
            metadata.
        built_at:
          type: string
          description: Build timestamp linked into the running binary when available.
        image_ref:
          type: string
          nullable: true
          description: Deployed image reference from runtime metadata when available.
        image_digest:
          type: string
          nullable: true
          description: Deployed image digest, or digest parsed from image_ref when
            available.
        pipeline_id:
          type: string
          nullable: true
          description: CI pipeline id that deployed the runtime when available.
        deployed_at:
          type: string
          nullable: true
          description: Deployment timestamp from platform-control rollout metadata
            when available.
        source:
          type: string
          description: Source of the metadata. The first slice reports the API service
            itself.
      required:
      - service_name
      - component
      - runtime_kind
      - version
      - commit
      - built_at
      - image_ref
      - image_digest
      - pipeline_id
      - deployed_at
      - source
    AdminFleetTelemetryWindow:
      type: object
      additionalProperties: false
      properties:
        range:
          type: string
          enum:
          - 15m
          - 1h
          - 6h
          - 24h
        window_seconds:
          type: integer
          minimum: 1
        points:
          type: integer
          minimum: 1
      required:
      - range
      - window_seconds
      - points
    AdminFleetTelemetryOverview:
      type: object
      additionalProperties: false
      properties:
        total_nodes:
          type: integer
          minimum: 0
        active_nodes:
          type: integer
          minimum: 0
        total_allocations:
          type: integer
          minimum: 0
        active_allocations:
          type: integer
          minimum: 0
        storage_bytes:
          type: integer
          minimum: 0
        sampled_nodes:
          type: integer
          minimum: 0
        reporting_nodes:
          type: integer
          minimum: 0
      required:
      - total_nodes
      - active_nodes
      - total_allocations
      - active_allocations
      - storage_bytes
      - sampled_nodes
      - reporting_nodes
    AdminFleetTelemetryRollups:
      type: object
      additionalProperties: false
      properties:
        cpu_utilization_pct:
          type: number
          nullable: true
        gpu_utilization_pct:
          type: number
          nullable: true
        memory_utilization_pct:
          type: number
          nullable: true
        storage_bytes:
          type: number
          minimum: 0
      required:
      - cpu_utilization_pct
      - gpu_utilization_pct
      - memory_utilization_pct
      - storage_bytes
    AdminFleetTelemetryPoint:
      type: object
      additionalProperties: false
      properties:
        ts:
          type: string
          format: date-time
        value:
          type: number
          nullable: true
      required:
      - ts
      - value
    AdminFleetTelemetryTimeseries:
      type: object
      additionalProperties: false
      properties:
        cpu:
          type: array
          items:
            "$ref": "#/components/schemas/AdminFleetTelemetryPoint"
        gpu:
          type: array
          items:
            "$ref": "#/components/schemas/AdminFleetTelemetryPoint"
        memory:
          type: array
          items:
            "$ref": "#/components/schemas/AdminFleetTelemetryPoint"
        storage:
          type: array
          items:
            "$ref": "#/components/schemas/AdminFleetTelemetryPoint"
      required:
      - cpu
      - gpu
      - memory
      - storage
    AdminFleetTelemetryTenantDimension:
      type: object
      additionalProperties: false
      properties:
        org_id:
          type: string
          format: uuid
        org_name:
          type: string
        active_allocations:
          type: integer
          minimum: 0
        storage_bytes:
          type: integer
          minimum: 0
      required:
      - org_id
      - org_name
      - active_allocations
      - storage_bytes
    AdminFleetTelemetryProjectDimension:
      type: object
      additionalProperties: false
      properties:
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        org_id:
          type: string
          format: uuid
        org_name:
          type: string
        active_allocations:
          type: integer
          minimum: 0
        storage_bytes:
          type: integer
          minimum: 0
      required:
      - project_id
      - project_name
      - org_id
      - org_name
      - active_allocations
      - storage_bytes
    AdminFleetTelemetryDimensions:
      type: object
      additionalProperties: false
      properties:
        tenants:
          type: array
          items:
            "$ref": "#/components/schemas/AdminFleetTelemetryTenantDimension"
        projects:
          type: array
          items:
            "$ref": "#/components/schemas/AdminFleetTelemetryProjectDimension"
      required:
      - tenants
      - projects
    AdminFleetTelemetryResponse:
      type: object
      additionalProperties: false
      description: Fleet telemetry rollups over a bounded window for admin incident
        and capacity triage.
      properties:
        generated_at:
          type: string
          format: date-time
        window:
          "$ref": "#/components/schemas/AdminFleetTelemetryWindow"
        overview:
          "$ref": "#/components/schemas/AdminFleetTelemetryOverview"
        rollups:
          "$ref": "#/components/schemas/AdminFleetTelemetryRollups"
        timeseries:
          "$ref": "#/components/schemas/AdminFleetTelemetryTimeseries"
        dimensions:
          "$ref": "#/components/schemas/AdminFleetTelemetryDimensions"
      required:
      - generated_at
      - window
      - overview
      - rollups
      - timeseries
      - dimensions
    AdminOutboxFailedEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        aggregate_type:
          type: string
        aggregate_id:
          type: string
        event_type:
          type: string
        payload:
          type: object
          additionalProperties: true
        correlation_id:
          type: string
        retry_count:
          type: integer
          minimum: 0
        last_attempted_at:
          type: string
          format: date-time
          nullable: true
        occurred_at:
          type: string
          format: date-time
      required:
      - id
      - aggregate_type
      - aggregate_id
      - event_type
      - payload
      - correlation_id
      - retry_count
      - last_attempted_at
      - occurred_at
    AdminOutboxFailedListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AdminOutboxFailedEvent"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AdminOutboxMutationResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
        outbox_event_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending
          - discarded
      required:
      - ok
      - outbox_event_id
      - status
    AdminDLQMessage:
      type: object
      additionalProperties: false
      properties:
        stream_seq:
          type: integer
          format: int64
          minimum: 1
        subject:
          type: string
        original_topic:
          type: string
          nullable: true
        event_type:
          type: string
          nullable: true
        correlation_id:
          type: string
          nullable: true
        occurred_at:
          type: string
          format: date-time
          nullable: true
        payload:
          type: object
          additionalProperties: true
        requeue_enabled:
          type: boolean
      required:
      - stream_seq
      - subject
      - original_topic
      - event_type
      - correlation_id
      - occurred_at
      - payload
      - requeue_enabled
    AdminDLQMessageListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AdminDLQMessage"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AdminDLQMutationResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
        stream_seq:
          type: integer
          format: int64
          minimum: 1
        status:
          type: string
          enum:
          - requeued
          - discarded
        target_subject:
          type: string
          nullable: true
      required:
      - ok
      - stream_seq
      - status
      - target_subject
    AdminRunbook:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        severity_hint:
          type: string
          enum:
          - sev1
          - sev2
          - sev3
        owner_team:
          type: string
          minLength: 1
        last_reviewed_at:
          type: string
          format: date
        url:
          type: string
          minLength: 1
        signals:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
      required:
      - id
      - title
      - severity_hint
      - owner_team
      - last_reviewed_at
      - url
      - signals
    AdminRunbookListResponse:
      type: object
      additionalProperties: false
      properties:
        generated_at:
          type: string
          format: date-time
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AdminRunbook"
      required:
      - generated_at
      - items
    OkResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
      required:
      - ok
    AccountType:
      type: string
      enum:
      - enterprise
      - personal
      description: User account model resolved by the active authentication flow.
    LoginRequest:
      type: object
      additionalProperties: false
      properties:
        username:
          type: string
          minLength: 1
        password:
          type: string
          minLength: 1
      required:
      - username
      - password
    LoginResponse:
      type: object
      additionalProperties: false
      properties:
        access_token:
          type: string
        expires_in_seconds:
          type: integer
          minimum: 1
        refresh_token:
          type: string
          nullable: true
        account_type:
          "$ref": "#/components/schemas/AccountType"
        org_id:
          type: string
          format: uuid
          nullable: true
        user:
          "$ref": "#/components/schemas/UserWithBalance"
      required:
      - access_token
      - expires_in_seconds
      - account_type
      - user
    SignupRequest:
      type: object
      additionalProperties: false
      properties:
        username:
          type: string
          minLength: 1
        password:
          type: string
          minLength: 8
      required:
      - username
      - password
    SignupResponse:
      allOf:
      - "$ref": "#/components/schemas/AuthSessionResponse"
      description: Internal/dev bootstrap signup response.
    RefreshTokenRequest:
      type: object
      additionalProperties: false
      properties:
        refresh_token:
          type: string
          minLength: 1
      required:
      - refresh_token
    RefreshTokenResponse:
      type: object
      additionalProperties: false
      properties:
        access_token:
          type: string
        expires_in_seconds:
          type: integer
          minimum: 1
        refresh_token:
          type: string
          nullable: true
        org_id:
          type: string
          format: uuid
          nullable: true
        user:
          "$ref": "#/components/schemas/UserWithBalance"
      required:
      - access_token
      - expires_in_seconds
      - user
    LogoutRequest:
      type: object
      additionalProperties: false
      description: Optional refresh token for full session revocation at OIDC provider.
      properties:
        refresh_token:
          type: string
          minLength: 1
    TerminalTokenResponse:
      type: object
      additionalProperties: false
      description: |
        Short-lived, single-use terminal session token scoped to a specific allocation.
        Clients must obtain this token via the REST API immediately before opening
        the ws/terminal WebSocket connection.
        Browser clients pass this token via `Sec-WebSocket-Protocol`.
        Non-browser clients may pass it via `Authorization: Bearer <token>`.
      properties:
        token:
          type: string
        expires_in_seconds:
          type: integer
          minimum: 1
          maximum: 300
        allocation_id:
          type: string
          format: uuid
      required:
      - token
      - expires_in_seconds
      - allocation_id
    InternalNodeEnrollmentRequest:
      type: object
      additionalProperties: false
      properties:
        node_id:
          type: string
          minLength: 1
        csr:
          type: string
          minLength: 1
          description: PEM-encoded CSR
      required:
      - node_id
      - csr
    InternalNodeEnrollmentResponse:
      type: object
      additionalProperties: false
      properties:
        certificate:
          type: string
          minLength: 1
          description: PEM-encoded certificate chain
        ca_bundle:
          type: string
          minLength: 1
          description: PEM-encoded CA bundle
      required:
      - certificate
      - ca_bundle
    InternalNodeCertRenewRequest:
      type: object
      additionalProperties: false
      properties:
        csr:
          type: string
          minLength: 1
          description: PEM-encoded CSR
      required:
      - csr
    InternalNodeCertRenewResponse:
      type: object
      additionalProperties: false
      properties:
        certificate:
          type: string
          minLength: 1
          description: PEM-encoded certificate chain
      required:
      - certificate
    InternalNodeTask:
      type: object
      additionalProperties: false
      properties:
        task_id:
          type: string
          format: uuid
        task_type:
          type: string
          minLength: 1
        node_id:
          type: string
          minLength: 1
        correlation_id:
          type: string
        issued_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        params:
          type: object
          additionalProperties: true
        signature:
          type: string
          minLength: 1
      required:
      - task_id
      - task_type
      - node_id
      - correlation_id
      - issued_at
      - expires_at
      - params
      - signature
    InternalNodeTaskResultRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - success
          - failed
          - rejected
        error:
          type: string
          nullable: true
        completed_at:
          type: string
          format: date-time
        output:
          type: object
          additionalProperties: true
      required:
      - status
      - completed_at
      - output
    InternalNodeTaskResultResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          type: boolean
      required:
      - ok
    InternalAppProxyRouteReportRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - pending
          - active
          - failed
        route_url:
          type: string
          nullable: true
          description: Browser-facing URL published by the gateway/controller when
            active.
        target_host:
          type: string
          nullable: true
          description: Gateway-resolved private host, node-local endpoint, or controller-owned
            upstream reference.
        target_port:
          type: integer
          minimum: 1
          maximum: 65535
          nullable: true
        failure_reason:
          type: string
          nullable: true
        target_metadata:
          type: object
          additionalProperties: true
          nullable: true
      required:
      - status
    InternalAppProxyRouteReportResponse:
      type: object
      additionalProperties: false
      properties:
        route:
          "$ref": "#/components/schemas/AppInstanceProxyRoute"
      required:
      - route
    InternalTerminalStreamFrame:
      type: object
      additionalProperties: false
      properties:
        session_id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - data
          - resize
          - close
        direction:
          type: string
          enum:
          - upstream
          - downstream
        payload:
          type: string
          format: byte
          nullable: true
        close_reason:
          type: string
          enum:
          - normal_close
          - allocation_released
          - session_timeout
          - node_stream_dropped
          - admin_terminate
          nullable: true
        cols:
          type: integer
          minimum: 1
          maximum: 512
          nullable: true
        rows:
          type: integer
          minimum: 1
          maximum: 512
          nullable: true
      required:
      - session_id
      - type
      - direction
    AppCatalogItem:
      type: object
      additionalProperties: false
      properties:
        slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        display_name:
          type: string
        category:
          type: string
          enum:
          - model_serving
          - inference
          - training
          - orchestration
          - observability
          - other
        publisher:
          type: string
        latest_version:
          type: string
        status:
          type: string
          enum:
          - active
          - deprecated
          - disabled
        description:
          type: string
          nullable: true
        logo_url:
          type: string
          format: uri
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true
      required:
      - slug
      - display_name
      - category
      - publisher
      - latest_version
      - status
    AppCatalogListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AppCatalogItem"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AppCatalogVersion:
      type: object
      additionalProperties: false
      properties:
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        version:
          type: string
          minLength: 1
        runtime_backend:
          type: string
          enum:
          - k8s
          - rke2
          - slurm
          - ray
          - bare_metal
        manifest:
          type: object
          additionalProperties: true
        status:
          type: string
          enum:
          - active
          - deprecated
          - disabled
      required:
      - app_slug
      - version
      - runtime_backend
      - manifest
      - status
    AppEntitlement:
      type: object
      additionalProperties: false
      properties:
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        project_id:
          type: string
          format: uuid
        enabled:
          type: boolean
        policy_overrides:
          type: object
          additionalProperties: true
      required:
      - app_slug
      - project_id
      - enabled
      - policy_overrides
    AppEntitlementListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AppEntitlement"
      required:
      - items
    UpsertAppEntitlementRequest:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
        policy_overrides:
          type: object
          additionalProperties: true
      required:
      - enabled
    CreateAppInstanceRequest:
      type: object
      additionalProperties: false
      properties:
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
          minLength: 1
        display_name:
          type: string
          minLength: 1
        app_artifact_id:
          type: string
          format: uuid
          nullable: true
        operating_mode:
          type: string
          enum:
          - tenant_dedicated
          - platform_managed
          nullable: true
          description: |
            Optional request hint for the desired app runtime operating mode.
            Server policy and app backend determine the effective mode; clients must not assume the requested mode is always granted.
        control_plane_scope:
          type: string
          enum:
          - project
          - tenant
          - platform
          nullable: true
          description: |
            Optional request hint for the desired runtime control-plane scope.
            Current baseline allows `project` or `tenant` only when the effective operating mode is `tenant_dedicated`;
            `platform` requires `platform_managed`. Server policy and app backend remain authoritative.
        operator_service_account_id:
          type: string
          format: uuid
          nullable: true
        placement_intent:
          "$ref": "#/components/schemas/AppInstancePlacementIntent"
        config:
          type: object
          additionalProperties: true
        resource_overrides:
          type: object
          additionalProperties: true
      required:
      - app_slug
      - app_version
      - display_name
    AppInstance:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        resource_name:
          type: string
        project_id:
          type: string
          format: uuid
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
        display_name:
          type: string
        app_artifact_id:
          type: string
          format: uuid
          nullable: true
        operating_mode:
          type: string
          enum:
          - tenant_dedicated
          - platform_managed
          description: Effective runtime operating mode for the instance.
        control_plane_scope:
          type: string
          enum:
          - project
          - tenant
          - platform
          description: Effective scope of the runtime control plane serving this instance.
        runtime_backend:
          type: string
          enum:
          - k8s
          - rke2
          - slurm
          - ray
          - bare_metal
          description: Effective runtime backend serving this instance.
        tenant_boundary_mode:
          type: string
          enum:
          - tenant_isolated
          - shared_service
          description: Whether the instance runs on tenant-bounded infrastructure
            or a shared managed substrate.
        status:
          type: string
          enum:
          - requested
          - deploying
          - running
          - stopping
          - stopped
          - starting
          - restarting
          - upgrading
          - rolling_back
          - failed
          - decommissioning
          - decommissioned
          - deleting
          - deleted
        failure_reason:
          type: string
          nullable: true
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        requested_by_service_account_id:
          type: string
          format: uuid
          nullable: true
        operator_service_account_id:
          type: string
          format: uuid
          nullable: true
        placement_intent:
          "$ref": "#/components/schemas/AppInstancePlacementIntent"
        runtime_state:
          type: object
          additionalProperties: true
        phase:
          type: string
          nullable: true
        progress:
          type: object
          additionalProperties: true
        health_status:
          type: string
          nullable: true
        health_detail:
          type: object
          additionalProperties: true
        proxy_routes:
          type: array
          items:
            "$ref": "#/components/schemas/AppInstanceProxyRoute"
          description: Platform-proxy route intents and observed route state for app
            endpoints that requested `platform_proxy` exposure.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - resource_name
      - project_id
      - app_slug
      - app_version
      - display_name
      - operating_mode
      - control_plane_scope
      - runtime_backend
      - tenant_boundary_mode
      - status
      - created_at
      - updated_at
    AppInstanceProxyRoute:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        app_instance_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        endpoint_name:
          type: string
          minLength: 1
        protocol:
          type: string
          enum:
          - http
          - https
          - ws
          - wss
        exposure_mode:
          type: string
          enum:
          - platform_proxy
        route_path:
          type: string
          description: Stable platform path reserved for the proxy route. It may be
            active only after the proxy controller reconciles the route.
        route_url:
          type: string
          nullable: true
          description: Browser-facing URL once a gateway/controller has published
            the route.
        target_kind:
          type: string
          enum:
          - app_instance_endpoint
        target_host:
          type: string
          nullable: true
          description: Gateway-resolved private host or node-local target. Null until
            the proxy controller has enough runtime state to resolve it.
        target_port:
          type: integer
          minimum: 1
          maximum: 65535
        target_metadata:
          type: object
          additionalProperties: true
        status:
          type: string
          enum:
          - pending
          - active
          - failed
          - deleting
          - deleted
        failure_reason:
          type: string
          nullable: true
        last_reconciled_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - app_instance_id
      - project_id
      - endpoint_name
      - protocol
      - exposure_mode
      - route_path
      - target_kind
      - target_port
      - target_metadata
      - status
      - created_at
      - updated_at
    AppInstancePlacementIntent:
      type: object
      additionalProperties: false
      properties:
        target_allocation_id:
          type: string
          format: uuid
          nullable: true
          description: Requested allocation that should host an allocation-local workload,
            such as a launchable OCI workload image.
        controller_allocation_id:
          type: string
          format: uuid
          nullable: true
          description: Requested allocation that should host the app control-plane
            member when the app runtime needs one.
        worker_allocation_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Explicit worker allocation targets selected at deploy time.
        server_allocation_id:
          type: string
          format: uuid
          nullable: true
          description: Requested allocation that should host the self-managed Kubernetes
            server member.
        agent_allocation_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Explicit agent allocation targets selected at deploy time for
            self-managed Kubernetes.
        allow_shared_allocation:
          type: boolean
          description: Whether the controller and one or more workers may reuse the
            same active allocation.
    SharedAppRuntimePlacementIntent:
      type: object
      additionalProperties: false
      description: |
        Reserved contract for tenant-owned shared runtime placement. This schema is
        additive contract direction only; tenant-shared runtime endpoints are not
        implemented yet.
      properties:
        controller_allocation_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Explicit controller/control-plane allocation targets for the
            tenant-owned shared runtime.
        allow_project_contributed_workers:
          type: boolean
          description: Whether attached consumer projects may contribute worker allocations
            to the shared runtime.
    CreateSharedAppRuntimeRequest:
      type: object
      additionalProperties: false
      description: Request contract for creating a tenant-owned shared app runtime.
      properties:
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
          minLength: 1
        display_name:
          type: string
          minLength: 1
        operating_mode:
          type: string
          enum:
          - tenant_dedicated
          description: Tenant-owned shared mode is only defined for tenant-dedicated
            runtimes in this baseline.
        control_plane_scope:
          type: string
          enum:
          - tenant
          description: Shared runtime control plane is tenant-scoped in this baseline.
        operator_identity_ref:
          type: string
          nullable: true
          description: Reserved reference to the tenant-bounded machine identity that
            will operate the shared runtime.
        placement_intent:
          "$ref": "#/components/schemas/SharedAppRuntimePlacementIntent"
        config:
          type: object
          additionalProperties: true
        initial_attached_project_ids:
          type: array
          items:
            type: string
            format: uuid
      required:
      - app_slug
      - app_version
      - display_name
    SharedAppRuntime:
      type: object
      additionalProperties: false
      description: Tenant-owned shared runtime control-plane object.
      properties:
        id:
          type: string
          format: uuid
        resource_name:
          type: string
        org_id:
          type: string
          format: uuid
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
        display_name:
          type: string
        operating_mode:
          type: string
          enum:
          - tenant_dedicated
        control_plane_scope:
          type: string
          enum:
          - tenant
        runtime_backend:
          type: string
          enum:
          - k8s
          - rke2
          - slurm
          - ray
          - bare_metal
        status:
          type: string
          enum:
          - requested
          - deploying
          - running
          - upgrading
          - rolling_back
          - failed
          - deleting
          - deleted
        operator_identity_ref:
          type: string
          nullable: true
        placement_intent:
          "$ref": "#/components/schemas/SharedAppRuntimePlacementIntent"
        runtime_state:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - resource_name
      - org_id
      - app_slug
      - app_version
      - display_name
      - operating_mode
      - control_plane_scope
      - runtime_backend
      - status
      - created_at
      - updated_at
    CreateSharedAppRuntimeAttachmentRequest:
      type: object
      additionalProperties: false
      description: Request contract for attaching a consumer project to a tenant-owned
        shared runtime.
      properties:
        project_id:
          type: string
          format: uuid
        allow_worker_contribution:
          type: boolean
        allow_job_submission:
          type: boolean
        policy:
          type: object
          additionalProperties: true
      required:
      - project_id
    SharedAppRuntimeAttachment:
      type: object
      additionalProperties: false
      description: Attachment resource between a tenant-owned shared runtime and a
        consumer project.
      properties:
        id:
          type: string
          format: uuid
        shared_runtime_id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - requested
          - attached
          - detaching
          - detached
          - failed
        allow_worker_contribution:
          type: boolean
        allow_job_submission:
          type: boolean
        policy:
          type: object
          additionalProperties: true
        runtime_state:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - shared_runtime_id
      - org_id
      - project_id
      - status
      - created_at
      - updated_at
    SharedAppRuntimeListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/SharedAppRuntime"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    SharedAppRuntimeAttachmentListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/SharedAppRuntimeAttachment"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    SharedAppRuntimeWorker:
      type: object
      additionalProperties: false
      description: |
        Additive contract direction for one concrete worker contribution inside a
        tenant-owned shared runtime. Reserved for tenant-shared worker topology;
        not fully implemented yet.
      properties:
        id:
          type: string
          format: uuid
        shared_runtime_id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        source_project_id:
          type: string
          format: uuid
          nullable: true
        attachment_id:
          type: string
          format: uuid
          nullable: true
        component_key:
          type: string
        contribution_mode:
          type: string
          enum:
          - tenant_owned
          - project_contributed
        allocation_id:
          type: string
          format: uuid
        bound_node_id:
          type: string
          format: uuid
          nullable: true
        status:
          type: string
          enum:
          - requested
          - provisioning
          - ready
          - draining
          - removed
          - failed
        runtime_state:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - shared_runtime_id
      - org_id
      - contribution_mode
      - allocation_id
      - status
      - created_at
      - updated_at
    ReportSharedAppRuntimeWorkerRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - requested
          - provisioning
          - ready
          - draining
          - removed
          - failed
        bound_node_id:
          type: string
          format: uuid
          nullable: true
        runtime_state:
          type: object
          additionalProperties: true
      required:
      - status
    SharedAppRuntimeWorkerListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/SharedAppRuntimeWorker"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    CreateSharedAppRuntimeWorkerOperationRequest:
      type: object
      additionalProperties: false
      description: |
        Additive contract direction for requesting tenant-shared worker changes.
        Reserved for shared-runtime worker contribution flow; not fully implemented yet.
      properties:
        action:
          type: string
          enum:
          - add
          - drain
          - remove
        attachment_id:
          type: string
          format: uuid
          nullable: true
        source_project_id:
          type: string
          format: uuid
          nullable: true
        requested_allocation_ids:
          type: array
          items:
            type: string
            format: uuid
      required:
      - action
    SharedAppRuntimeWorkerOperation:
      type: object
      additionalProperties: false
      description: |
        One worker lifecycle request against a tenant-owned shared runtime. External
        app workers consume these operations through the polling-compatible runtime
        contract and report progress through the operation report endpoint.
      properties:
        id:
          type: string
          format: uuid
        shared_runtime_id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        action:
          type: string
          enum:
          - add
          - drain
          - remove
        attachment_id:
          type: string
          format: uuid
          nullable: true
        source_project_id:
          type: string
          format: uuid
          nullable: true
        requested_allocation_ids:
          type: array
          items:
            type: string
            format: uuid
        status:
          type: string
          enum:
          - accepted
          - in_progress
          - succeeded
          - failed
          - cancelled
        correlation_id:
          type: string
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        last_error_code:
          type: string
          nullable: true
        last_error_message:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - shared_runtime_id
      - org_id
      - action
      - status
      - correlation_id
      - created_at
      - updated_at
    SharedAppRuntimeWorkerResult:
      type: object
      additionalProperties: false
      properties:
        allocation_id:
          type: string
          format: uuid
        bound_node_id:
          type: string
          format: uuid
          nullable: true
        status:
          type: string
          enum:
          - requested
          - provisioning
          - ready
          - draining
          - removed
          - failed
        runtime_state:
          type: object
          additionalProperties: true
      required:
      - allocation_id
      - status
    ReportSharedAppRuntimeWorkerOperationRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - in_progress
          - succeeded
          - failed
          - cancelled
        last_error_code:
          type: string
          nullable: true
        last_error_message:
          type: string
          nullable: true
        workers:
          type: array
          items:
            "$ref": "#/components/schemas/SharedAppRuntimeWorkerResult"
      required:
      - status
    SharedAppRuntimeWorkerOperationListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    ReportAppInstanceRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - deploying
          - running
          - failed
          - decommissioning
          - decommissioned
          - deleting
          - deleted
        failure_reason:
          type: string
          nullable: true
        runtime_state:
          type: object
          additionalProperties: true
        phase:
          type: string
          nullable: true
        progress:
          type: object
          additionalProperties: true
        health_status:
          type: string
          nullable: true
        health_detail:
          type: object
          additionalProperties: true
      required:
      - status
    ReconcileAppInstanceBootstrapSshTrustRequest:
      type: object
      additionalProperties: false
      properties:
        access_credential_id:
          type: string
          format: uuid
          nullable: true
        allocation_id:
          type: string
          format: uuid
        username_on_node:
          type: string
        public_key:
          type: string
          nullable: true
        desired_state:
          type: string
          enum:
          - present
          - absent
      required:
      - allocation_id
      - username_on_node
      - desired_state
    AppInstanceBootstrapSshTrustState:
      type: object
      additionalProperties: false
      properties:
        app_instance_id:
          type: string
          format: uuid
        allocation_id:
          type: string
          format: uuid
        username_on_node:
          type: string
        access_credential_id:
          type: string
          format: uuid
          nullable: true
        managed_key_id:
          type: string
          description: Stable node-side GPUaaS managed-key marker. App bootstrap SSH
            reconcile uses the bound access credential ID when present, so repeat
            deploys with the same credential update one authorized_keys block; app-instance
            scoped markers are retained only as a legacy fallback.
        desired_state:
          type: string
          enum:
          - present
          - absent
        status:
          type: string
          enum:
          - sync_requested
        public_key_fingerprint:
          type: string
          nullable: true
        node_task_type:
          type: string
        correlation_id:
          type: string
        last_reconciled_at:
          type: string
          format: date-time
      required:
      - app_instance_id
      - allocation_id
      - username_on_node
      - managed_key_id
      - desired_state
      - status
      - node_task_type
      - correlation_id
      - last_reconciled_at
    ReportSharedAppRuntimeRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - deploying
          - running
          - failed
          - deleting
          - deleted
        failure_reason:
          type: string
          nullable: true
        runtime_state:
          type: object
          additionalProperties: true
      required:
      - status
    ReportSharedAppRuntimeAttachmentRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - attached
          - failed
          - detaching
          - detached
        runtime_state:
          type: object
          additionalProperties: true
      required:
      - status
    IssueAppInstanceRuntimeSecretRequest:
      type: object
      additionalProperties: false
      properties:
        purpose:
          type: string
          enum:
          - artifact_pull
      required:
      - purpose
    AppInstanceRuntimeSecretBundle:
      type: object
      additionalProperties: false
      properties:
        app_instance_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        app_artifact_id:
          type: string
          format: uuid
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
        artifact_kind:
          type: string
          enum:
          - oci
          - blob
        source_type:
          type: string
          enum:
          - oci_registry
          - s3
          - gcs
          - azure_blob
          - https
          - huggingface
          - artifact_store
        repository:
          type: string
        source_uri:
          type: string
          nullable: true
        digest:
          type: string
          pattern: "^sha256:[a-f0-9]{64}$"
        digest_algorithm:
          type: string
          enum:
          - sha256
        runtime_backend:
          type: string
        purpose:
          type: string
          enum:
          - artifact_pull
        delivery_mode:
          type: string
          enum:
          - vault_wrapped_token
        wrapped_token:
          type: string
          minLength: 1
        unwrap_url:
          type: string
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
      required:
      - app_instance_id
      - project_id
      - app_artifact_id
      - app_slug
      - app_version
      - artifact_kind
      - source_type
      - repository
      - digest
      - digest_algorithm
      - runtime_backend
      - purpose
      - delivery_mode
      - wrapped_token
    AppInstanceAccessBundle:
      type: object
      additionalProperties: false
      properties:
        app_instance_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        runtime_backend:
          type: string
        access_kind:
          type: string
          enum:
          - kubeconfig
        status:
          type: string
          enum:
          - available
          - pending
          - unavailable
        cluster_name:
          type: string
          nullable: true
        server_endpoint:
          type: string
          nullable: true
        kubeconfig:
          type: string
          nullable: true
        detail:
          type: string
          nullable: true
        generated_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
      required:
      - app_instance_id
      - project_id
      - runtime_backend
      - access_kind
      - status
    UpgradeAppInstanceRequest:
      type: object
      additionalProperties: false
      properties:
        app_version:
          type: string
          minLength: 1
      required:
      - app_version
    RollbackAppInstanceRequest:
      type: object
      additionalProperties: false
      properties:
        app_version:
          type: string
          minLength: 1
      required:
      - app_version
    AppInstanceListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AppInstance"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AppInstanceMember:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        app_instance_id:
          type: string
          format: uuid
        component_key:
          type: string
          minLength: 1
          description: Stable adapter-supplied component identifier. Runtime meaning
            remains adapter-owned.
        member_role:
          type: string
          nullable: true
          description: Normalized runtime role when the adapter exposes one, for example
            controller or worker.
        status:
          type: string
          enum:
          - requested
          - reconciling
          - ready
          - draining
          - deleting
          - failed
          - deleted
          description: Generic platform member status. Runtime-specific interpretation
            remains adapter-owned.
        bound_node_id:
          type: string
          format: uuid
          nullable: true
        bound_node_resource_name:
          type: string
          nullable: true
        bound_allocation_id:
          type: string
          format: uuid
          nullable: true
        runtime_state:
          type: object
          additionalProperties: true
          nullable: true
          description: Normalized member runtime state. Legacy adapter detail is lifted
            into this field when possible.
        health_status:
          type: string
          nullable: true
        health_detail:
          type: object
          additionalProperties: true
          nullable: true
        endpoint:
          type: object
          additionalProperties: true
          nullable: true
          description: Adapter-reported or derived endpoint details for workload member
            connectivity.
        last_operation_id:
          type: string
          format: uuid
          nullable: true
        last_correlation_id:
          type: string
          nullable: true
        adapter_detail:
          type: object
          additionalProperties: true
          nullable: true
          description: Adapter-owned runtime detail surfaced through a generic envelope.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - app_instance_id
      - component_key
      - status
      - created_at
      - updated_at
    AppInstanceMemberListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AppInstanceMember"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    AppInstanceMemberOperationListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AppInstanceMemberOperation"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    CreateAppInstanceMemberOperationRequest:
      type: object
      additionalProperties: false
      properties:
        action:
          type: string
          enum:
          - add
          - drain
          - remove
          - replace
        component_key:
          type: string
          minLength: 1
          nullable: true
          description: Generic adapter-supplied component identifier. Required for
            `add`.
        target_member_id:
          type: string
          format: uuid
          nullable: true
          description: Target member for `drain`, `remove`, or `replace`.
        requested_count:
          type: integer
          minimum: 1
          nullable: true
          description: Requested member count delta for `add`.
        allocation_intent:
          type: object
          additionalProperties: true
          nullable: true
          description: Opaque app-level capacity intent. This is not a raw node-placement
            contract.
      required:
      - action
    AppInstanceMemberOperation:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        app_instance_id:
          type: string
          format: uuid
        action:
          type: string
          enum:
          - add
          - drain
          - remove
          - replace
        component_key:
          type: string
          nullable: true
        target_member_id:
          type: string
          format: uuid
          nullable: true
        requested_count:
          type: integer
          minimum: 1
          nullable: true
        allocation_intent:
          type: object
          additionalProperties: true
          nullable: true
          description: Opaque app-level capacity intent echoed back through the operation
            read model.
        status:
          type: string
          enum:
          - accepted
          - in_progress
          - succeeded
          - failed
          - cancelled
        correlation_id:
          type: string
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        requested_by_service_account_id:
          type: string
          format: uuid
          nullable: true
        last_error_code:
          type: string
          nullable: true
        last_error_message:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - app_instance_id
      - action
      - status
      - correlation_id
      - created_at
      - updated_at
    ReportAppInstanceMemberOperationRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - in_progress
          - succeeded
          - failed
          - cancelled
        target_member_id:
          type: string
          format: uuid
          nullable: true
          description: Optional target member binding when the operation was accepted
            without a concrete target id. For `add` and `replace`, adapters may report
            a new member id here and the platform will materialize the generic member
            row through this report flow.
        member_status:
          type: string
          enum:
          - requested
          - reconciling
          - ready
          - draining
          - deleting
          - failed
          - deleted
          nullable: true
        bound_node_id:
          type: string
          format: uuid
          nullable: true
        bound_allocation_id:
          type: string
          format: uuid
          nullable: true
        member_role:
          type: string
          nullable: true
        runtime_state:
          type: object
          additionalProperties: true
          nullable: true
        health_status:
          type: string
          nullable: true
        health_detail:
          type: object
          additionalProperties: true
          nullable: true
        endpoint:
          type: object
          additionalProperties: true
          nullable: true
        adapter_detail:
          type: object
          additionalProperties: true
          nullable: true
          description: Adapter-owned runtime detail surfaced through the generic platform
            envelope.
        last_error_code:
          type: string
          nullable: true
        last_error_message:
          type: string
          nullable: true
      required:
      - status
    AppInstanceRepairAction:
      type: string
      enum:
      - reconcile
      - repair
      description: Reconcile is drift correction without destructive restart when
        possible. Repair may restart/reinstall runtime services for the targeted scope
        when the runtime contract declares it safe.
    AppInstanceRepairScope:
      type: string
      enum:
      - whole_runtime
      - control_plane
      - member
      description: Target scope for app-runtime repair. RKE2 maps control_plane to
        the server member and member to one server or agent member.
    AppInstanceRepairOperationStatus:
      type: string
      enum:
      - accepted
      - in_progress
      - succeeded
      - failed
      - cancelled
    AppInstanceRepairStep:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        status:
          type: string
          enum:
          - pending
          - running
          - succeeded
          - failed
          - skipped
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        summary:
          type: string
          nullable: true
      required:
      - name
      - status
      - started_at
      - completed_at
      - summary
    CreateAppInstanceRepairRequest:
      type: object
      additionalProperties: false
      properties:
        action:
          "$ref": "#/components/schemas/AppInstanceRepairAction"
        scope:
          "$ref": "#/components/schemas/AppInstanceRepairScope"
        target_member_id:
          type: string
          format: uuid
          nullable: true
          description: Required when scope is member.
        component_key:
          type: string
          nullable: true
          description: Optional adapter component key such as server or agent, useful
            for scoped repair requests before a target member is selected.
        reason:
          type: string
          nullable: true
          maxLength: 500
        dry_run:
          type: boolean
          default: false
          description: When true, validates and returns the planned operation without
            mutating runtime state.
      required:
      - action
      - scope
    AppInstanceRepairOperation:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        app_instance_id:
          type: string
          format: uuid
        action:
          "$ref": "#/components/schemas/AppInstanceRepairAction"
        scope:
          "$ref": "#/components/schemas/AppInstanceRepairScope"
        target_member_id:
          type: string
          format: uuid
          nullable: true
        component_key:
          type: string
          nullable: true
        status:
          "$ref": "#/components/schemas/AppInstanceRepairOperationStatus"
        phase:
          type: string
          nullable: true
          description: Adapter-owned phase label for progress display.
        progress:
          type: object
          additionalProperties: true
          nullable: true
        steps:
          type: array
          items:
            "$ref": "#/components/schemas/AppInstanceRepairStep"
        correlation_id:
          type: string
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        requested_by_service_account_id:
          type: string
          format: uuid
          nullable: true
        last_error_code:
          type: string
          nullable: true
        last_error_message:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - app_instance_id
      - action
      - scope
      - status
      - steps
      - correlation_id
      - created_at
      - updated_at
    AppInstanceRepairOperationListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AppInstanceRepairOperation"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    ReportAppInstanceRepairOperationRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          "$ref": "#/components/schemas/AppInstanceRepairOperationStatus"
        phase:
          type: string
          nullable: true
        progress:
          type: object
          additionalProperties: true
          nullable: true
        steps:
          type: array
          items:
            "$ref": "#/components/schemas/AppInstanceRepairStep"
        runtime_state:
          type: object
          additionalProperties: true
          nullable: true
        health_status:
          type: string
          nullable: true
        health_detail:
          type: object
          additionalProperties: true
          nullable: true
        last_error_code:
          type: string
          nullable: true
        last_error_message:
          type: string
          nullable: true
      required:
      - status
    ReportAppInstanceMemberRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - requested
          - reconciling
          - ready
          - draining
          - deleting
          - failed
          - deleted
        bound_node_id:
          type: string
          format: uuid
          nullable: true
        bound_allocation_id:
          type: string
          format: uuid
          nullable: true
        member_role:
          type: string
          nullable: true
        runtime_state:
          type: object
          additionalProperties: true
          nullable: true
        health_status:
          type: string
          nullable: true
        health_detail:
          type: object
          additionalProperties: true
          nullable: true
        endpoint:
          type: object
          additionalProperties: true
          nullable: true
        adapter_detail:
          type: object
          additionalProperties: true
          nullable: true
          description: Adapter-owned runtime detail surfaced through the generic platform
            envelope.
      required:
      - status
    OciRegistryInfo:
      type: object
      additionalProperties: false
      properties:
        registry_host:
          type: string
        registry_api_base_url:
          type: string
          format: uri
        namespace_mode:
          type: string
          enum:
          - platform
          - tenant
          - project
        digest_required:
          type: boolean
        project_private_repositories_enabled:
          type: boolean
        publish_intent_ttl_seconds:
          type: integer
          minimum: 1
      required:
      - registry_host
      - registry_api_base_url
      - namespace_mode
      - digest_required
      - project_private_repositories_enabled
      - publish_intent_ttl_seconds
    PlatformReleaseArtifact:
      type: object
      additionalProperties: false
      properties:
        artifact_id:
          type: string
          enum:
          - cli-linux-amd64
          - cli-darwin-arm64
          - cli-darwin-amd64
          - go-sdk
          - python-sdk
          - node-agent
          - node-agent-bootstrap
        display_name:
          type: string
          minLength: 1
        description:
          type: string
          minLength: 1
        audience:
          type: string
          enum:
          - developer
          - operator
        platforms:
          type: array
          items:
            type: string
            minLength: 1
        version:
          type: string
          minLength: 1
        file_name:
          type: string
          minLength: 1
        oci_ref:
          type: string
          nullable: true
        digest:
          type: string
          nullable: true
        tag:
          type: string
          nullable: true
        artifact_type:
          type: string
          nullable: true
        download_url:
          type: string
          minLength: 1
      required:
      - artifact_id
      - display_name
      - description
      - audience
      - platforms
      - version
      - file_name
      - download_url
    ArtifactPullIntent:
      type: object
      additionalProperties: false
      description: Short-lived registry pull intent. Credential material is Vault-wrapped
        and must not be cached or persisted by clients.
      properties:
        artifact_scope:
          type: string
          enum:
          - platform_release
          - app_artifact
        artifact_id:
          type: string
          minLength: 1
        project_id:
          type: string
          format: uuid
          nullable: true
        version:
          type: string
          nullable: true
        app_slug:
          type: string
          nullable: true
        app_version:
          type: string
          nullable: true
        artifact_kind:
          type: string
          nullable: true
          enum:
          - oci
          - blob
        source_type:
          type: string
          enum:
          - oci_registry
        registry_host:
          type: string
          minLength: 1
        registry_api_base_url:
          type: string
          minLength: 1
        repository:
          type: string
          minLength: 1
        oci_ref:
          type: string
          minLength: 1
        digest:
          type: string
          minLength: 1
        tag:
          type: string
          nullable: true
        credential_delivery_mode:
          type: string
          enum:
          - vault_wrapped_token
        credential_wrapped_token:
          type: string
          minLength: 1
        credential_unwrap_url:
          type: string
          format: uri
          nullable: true
        credential_expires_at:
          type: string
          format: date-time
      required:
      - artifact_scope
      - artifact_id
      - registry_host
      - registry_api_base_url
      - repository
      - oci_ref
      - digest
      - credential_delivery_mode
      - credential_wrapped_token
      - credential_expires_at
    PlatformRelease:
      type: object
      additionalProperties: false
      properties:
        version:
          type: string
          minLength: 1
        artifacts:
          type: array
          items:
            "$ref": "#/components/schemas/PlatformReleaseArtifact"
      required:
      - version
      - artifacts
    PlatformReleaseListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/PlatformRelease"
      required:
      - items
    PlatformDevCA:
      type: object
      additionalProperties: false
      properties:
        display_name:
          type: string
          minLength: 1
        description:
          type: string
          minLength: 1
        file_name:
          type: string
          minLength: 1
        fingerprint_sha256:
          type: string
          minLength: 1
        format:
          type: string
          enum:
          - pem
        download_url:
          type: string
          minLength: 1
      required:
      - display_name
      - description
      - file_name
      - fingerprint_sha256
      - format
      - download_url
    AppArtifact:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
        artifact_name:
          type: string
          minLength: 1
        artifact_kind:
          type: string
          enum:
          - oci
          - blob
        source_type:
          type: string
          enum:
          - oci_registry
          - s3
          - gcs
          - azure_blob
          - https
          - huggingface
          - artifact_store
        publish_intent_id:
          type: string
          format: uuid
          nullable: true
        repository:
          type: string
          minLength: 1
        source_uri:
          type: string
          minLength: 1
          nullable: true
        digest:
          type: string
          pattern: "^sha256:[a-f0-9]{64}$"
        digest_algorithm:
          type: string
          enum:
          - sha256
        tag:
          type: string
          nullable: true
        media_type:
          type: string
          minLength: 1
        lifecycle_state:
          type: string
          enum:
          - published
          - promoted
          - deprecated
          - retired
        trust_state:
          type: string
          enum:
          - unverified
          - verified
          - failed_verification
          - revoked
        verification_method:
          type: string
          nullable: true
        verification_key_id:
          type: string
          nullable: true
        provenance_digest:
          type: string
          pattern: "^sha256:[a-f0-9]{64}$"
          nullable: true
        verified_at:
          type: string
          format: date-time
          nullable: true
        promoted_channel:
          type: string
          nullable: true
        target_environment:
          type: string
          nullable: true
        requested_by_user_id:
          type: string
          format: uuid
          nullable: true
        registered_by_service_account_id:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - project_id
      - app_slug
      - app_version
      - artifact_name
      - artifact_kind
      - source_type
      - repository
      - digest
      - digest_algorithm
      - media_type
      - lifecycle_state
      - trust_state
      - created_at
      - updated_at
    AppArtifactListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/AppArtifact"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      required:
      - items
      - pagination
    CreateAppArtifactPublishIntentRequest:
      type: object
      additionalProperties: false
      properties:
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
          minLength: 1
        artifact_name:
          type: string
          minLength: 1
        artifact_kind:
          type: string
          enum:
          - oci
          - blob
        source_type:
          type: string
          enum:
          - oci_registry
          - s3
          - gcs
          - azure_blob
          - https
          - huggingface
          - artifact_store
        channel:
          type: string
          minLength: 1
          nullable: true
      required:
      - app_slug
      - app_version
      - artifact_name
      - artifact_kind
      - source_type
    AppArtifactPublishIntent:
      type: object
      additionalProperties: false
      properties:
        intent_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
        artifact_name:
          type: string
        artifact_kind:
          type: string
          enum:
          - oci
          - blob
        source_type:
          type: string
          enum:
          - oci_registry
          - s3
          - gcs
          - azure_blob
          - https
          - huggingface
          - artifact_store
        repository:
          type: string
        source_uri:
          type: string
          nullable: true
        upload_path:
          type: string
          nullable: true
        upload_method:
          type: string
          enum:
          - oci_push
          - blob_upload
          - external_register
        tag:
          type: string
          nullable: true
        digest_required:
          type: boolean
        signature_required:
          type: boolean
        signature_scheme:
          type: string
          nullable: true
        signing_key_id:
          type: string
          nullable: true
        provenance_required:
          type: boolean
        credential_delivery_mode:
          type: string
          nullable: true
          enum:
          - vault_wrapped_token
        credential_wrapped_token:
          type: string
          nullable: true
        credential_unwrap_url:
          type: string
          format: uri
          nullable: true
        credential_expires_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
      required:
      - intent_id
      - project_id
      - app_slug
      - app_version
      - artifact_name
      - artifact_kind
      - source_type
      - repository
      - upload_method
      - digest_required
      - signature_required
      - provenance_required
      - expires_at
    RegisterAppArtifactRequest:
      type: object
      additionalProperties: false
      properties:
        app_slug:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
        app_version:
          type: string
          minLength: 1
        artifact_name:
          type: string
          minLength: 1
        artifact_kind:
          type: string
          enum:
          - oci
          - blob
        source_type:
          type: string
          enum:
          - oci_registry
          - s3
          - gcs
          - azure_blob
          - https
          - huggingface
          - artifact_store
        publish_intent_id:
          type: string
          format: uuid
          nullable: true
        repository:
          type: string
          minLength: 1
        source_uri:
          type: string
          minLength: 1
          nullable: true
        digest:
          type: string
          pattern: "^sha256:[a-f0-9]{64}$"
        digest_algorithm:
          type: string
          enum:
          - sha256
        tag:
          type: string
          nullable: true
        media_type:
          type: string
          minLength: 1
      required:
      - app_slug
      - app_version
      - artifact_name
      - artifact_kind
      - source_type
      - repository
      - digest
      - digest_algorithm
      - media_type
    PromoteAppArtifactRequest:
      type: object
      additionalProperties: false
      properties:
        channel:
          type: string
          minLength: 1
        target_environment:
          type: string
          minLength: 1
          nullable: true
      required:
      - channel
    V3ComputeLaunchSubmitRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          maxLength: 120
          nullable: true
        sku:
          type: string
          minLength: 1
        capacity_shape:
          "$ref": "#/components/schemas/V3ComputeCapacityShape"
        gpu_count:
          type: integer
          minimum: 1
          nullable: true
        os_image_slug:
          type: string
          nullable: true
        region_code:
          type: string
          nullable: true
        scheduler_type:
          type: string
          enum:
          - bare_metal
          - slurm
          - k8s
          - ray
          nullable: true
        ssh_key_ids:
          type: array
          items:
            type: string
            format: uuid
        storage_bucket_ids:
          type: array
          items:
            type: string
        network_policy_id:
          type: string
          nullable: true
        scheduler_request:
          type: object
          additionalProperties: true
      required:
      - sku
    V3AppLaunchSubmitRequest:
      type: object
      additionalProperties: false
      properties:
        app_version:
          type: string
          nullable: true
        display_name:
          type: string
          minLength: 1
          nullable: true
        placement_intent:
          "$ref": "#/components/schemas/AppInstancePlacementIntent"
          nullable: true
        operator_service_account_id:
          type: string
          format: uuid
          nullable: true
        dependencies:
          type: object
          additionalProperties: true
        config:
          type: object
          additionalProperties: true
        resource_overrides:
          type: object
          additionalProperties: true
    V3LaunchSubmitResponse:
      type: object
      additionalProperties: false
      properties:
        task_id:
          type: string
          format: uuid
        task_href:
          type: string
        workload_id:
          type: string
        workload_href:
          type: string
        resource_kind:
          "$ref": "#/components/schemas/V3TaskResourceKind"
        status:
          "$ref": "#/components/schemas/V3TaskStatus"
        message:
          type: string
      required:
      - task_id
      - task_href
      - workload_id
      - workload_href
      - resource_kind
      - status
      - message
    V3PlatformSeverity:
      type: string
      enum:
      - ok
      - info
      - warn
      - error
    V3PlatformKPI:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
        label:
          type: string
        value:
          type: string
        summary:
          type: string
          nullable: true
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
      required:
      - key
      - label
      - value
      - summary
      - severity
    V3PlatformActionItem:
      type: object
      additionalProperties: false
      properties:
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
        code:
          type: string
        title:
          type: string
        summary:
          type: string
        primary_action_label:
          type: string
          nullable: true
        primary_action_href:
          type: string
          nullable: true
        runbook_href:
          type: string
          nullable: true
        signal_key:
          type: string
          description: Backend-owned stable key for acknowledgement/suppression mutations.
        target_type:
          type: string
        target_id:
          type: string
          nullable: true
        ack_fingerprint:
          type: string
          description: Opaque backend fingerprint used to resurface changed failures.
        ack_state:
          "$ref": "#/components/schemas/V3PlatformAckState"
        ack_reason:
          type: string
          nullable: true
        ack_expires_at:
          type: string
          format: date-time
          nullable: true
        ack_actor:
          type: string
          nullable: true
        ack_updated_at:
          type: string
          format: date-time
          nullable: true
      required:
      - severity
      - code
      - title
      - summary
      - primary_action_label
      - primary_action_href
      - runbook_href
      - signal_key
      - target_type
      - target_id
      - ack_fingerprint
      - ack_state
      - ack_reason
      - ack_expires_at
      - ack_actor
      - ack_updated_at
    V3PlatformAckState:
      type: string
      enum:
      - none
      - acknowledged
      - suppressed
      - expired
      - resurfaced
    V3PlatformSignalAcknowledgeRequest:
      type: object
      additionalProperties: false
      properties:
        ack_fingerprint:
          type: string
          minLength: 1
          maxLength: 512
        reason:
          type: string
          nullable: true
          maxLength: 500
        expires_at:
          type: string
          format: date-time
          nullable: true
        scope:
          type: string
          enum:
          - item
          default: item
      required:
      - ack_fingerprint
    V3PlatformSignalSuppressRequest:
      type: object
      additionalProperties: false
      properties:
        ack_fingerprint:
          type: string
          minLength: 1
          maxLength: 512
        reason:
          type: string
          minLength: 1
          maxLength: 500
        expires_at:
          type: string
          format: date-time
        scope:
          type: string
          enum:
          - item
          default: item
      required:
      - ack_fingerprint
      - reason
      - expires_at
    V3PlatformSignalClearRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          nullable: true
          maxLength: 500
    V3PlatformSignalAckResponse:
      type: object
      additionalProperties: false
      properties:
        signal_key:
          type: string
        target_type:
          type: string
        target_id:
          type: string
          nullable: true
        ack_fingerprint:
          type: string
        ack_state:
          "$ref": "#/components/schemas/V3PlatformAckState"
        ack_reason:
          type: string
          nullable: true
        ack_expires_at:
          type: string
          format: date-time
          nullable: true
        ack_actor:
          type: string
          nullable: true
        ack_updated_at:
          type: string
          format: date-time
          nullable: true
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - signal_key
      - target_type
      - target_id
      - ack_fingerprint
      - ack_state
      - ack_reason
      - ack_expires_at
      - ack_actor
      - ack_updated_at
      - meta
    V3PlatformFamilyCard:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          enum:
          - ops
          - lifecycle
          - config
          - evidence
          - finance
          - iam
        title:
          type: string
        summary:
          type: string
        href:
          type: string
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
        metric:
          type: string
          nullable: true
        bullets:
          type: array
          items:
            type: string
      required:
      - key
      - title
      - summary
      - href
      - severity
      - metric
      - bullets
    V3PlatformWorkflowCard:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
        title:
          type: string
        summary:
          type: string
        href:
          type: string
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
        metric:
          type: string
          nullable: true
        bullets:
          type: array
          items:
            type: string
        primary_action_label:
          type: string
          nullable: true
        owner_domain:
          type: string
          nullable: true
        review_required:
          type: boolean
          description: True when this workflow card represents an open operator attention
            item.
        review_state:
          "$ref": "#/components/schemas/V3ProvisioningReviewState"
        reviewed_at:
          type: string
          format: date-time
          nullable: true
        reviewed_by:
          type: string
          nullable: true
        review_note:
          type: string
          nullable: true
        attention_reason:
          type: string
          nullable: true
        next_action:
          type: string
          nullable: true
        superseded_by_workflow_id:
          type: string
          nullable: true
      required:
      - key
      - title
      - summary
      - href
      - severity
      - metric
      - bullets
      - primary_action_label
      - owner_domain
      - review_required
      - review_state
      - reviewed_at
      - reviewed_by
      - review_note
      - attention_reason
      - next_action
      - superseded_by_workflow_id
    V3ProvisioningReviewState:
      type: string
      enum:
      - open
      - taken_care_of
      - ignored
      - superseded
    V3ProvisioningAttentionReviewDecision:
      type: string
      enum:
      - taken_care_of
      - ignored
    V3ProvisioningAttentionReviewRequest:
      type: object
      additionalProperties: false
      properties:
        review_state:
          "$ref": "#/components/schemas/V3ProvisioningAttentionReviewDecision"
        review_note:
          type: string
          minLength: 1
          maxLength: 500
      required:
      - review_state
      - review_note
    V3ProvisioningAttentionReviewResponse:
      type: object
      additionalProperties: false
      properties:
        attention_key:
          type: string
        target_type:
          type: string
        target_id:
          type: string
        workflow_id:
          type: string
          nullable: true
        review_state:
          "$ref": "#/components/schemas/V3ProvisioningReviewState"
        reviewed_at:
          type: string
          format: date-time
        reviewed_by:
          type: string
        review_note:
          type: string
      required:
      - attention_key
      - target_type
      - target_id
      - workflow_id
      - review_state
      - reviewed_at
      - reviewed_by
      - review_note
    V3PlatformHealthItem:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
        label:
          type: string
        status:
          "$ref": "#/components/schemas/V3PlatformSeverity"
        detail:
          type: string
          nullable: true
      required:
      - key
      - label
      - status
      - detail
    V3PlatformNodeRow:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        hostname:
          type: string
          nullable: true
        sku:
          type: string
        status:
          type: string
        occupancy:
          type: string
        placement_impact:
          "$ref": "#/components/schemas/V3PlatformNodePlacementImpact"
        network:
          "$ref": "#/components/schemas/V3PlatformNodeNetworkSummary"
        image:
          "$ref": "#/components/schemas/V3PlatformNodeImageSummary"
        latest_operation:
          "$ref": "#/components/schemas/V3PlatformNodeLatestOperation"
        schedulability:
          "$ref": "#/components/schemas/V3PlatformNodeSchedulability"
        agent_version:
          type: string
          nullable: true
        reported_at:
          type: string
          format: date-time
          nullable: true
        open_href:
          type: string
      required:
      - id
      - hostname
      - sku
      - status
      - occupancy
      - placement_impact
      - network
      - image
      - latest_operation
      - schedulability
      - agent_version
      - reported_at
      - open_href
    V3PlatformNodePlacementImpact:
      type: object
      additionalProperties: false
      properties:
        active_allocations:
          type: integer
        active_slices:
          type: integer
        project_count:
          type: integer
        tenant_count:
          type: integer
        primary_tenant_name:
          type: string
          nullable: true
        primary_project_name:
          type: string
          nullable: true
        primary_owner_username:
          type: string
          nullable: true
        maintenance_summary:
          type: string
        contact_hint:
          type: string
      required:
      - active_allocations
      - active_slices
      - project_count
      - tenant_count
      - primary_tenant_name
      - primary_project_name
      - primary_owner_username
      - maintenance_summary
      - contact_hint
    V3PlatformNodeNetworkSummary:
      type: object
      additionalProperties: false
      properties:
        host:
          type: string
        primary_ip:
          type: string
          nullable: true
        management_ip:
          type: string
          nullable: true
        maas_ip:
          type: string
          nullable: true
        source:
          type: string
          enum:
          - slot
          - maas_management
          - maas
          - host
          - unknown
      required:
      - host
      - primary_ip
      - management_ip
      - maas_ip
      - source
    V3PlatformNodeImageSummary:
      type: object
      additionalProperties: false
      properties:
        os_image_slug:
          type: string
          nullable: true
        os_image_display_name:
          type: string
          nullable: true
        driver_strategy:
          type: string
          nullable: true
        image_status:
          type: string
          nullable: true
        verified_at:
          type: string
          format: date-time
          nullable: true
      required:
      - os_image_slug
      - os_image_display_name
      - driver_strategy
      - image_status
      - verified_at
    V3PlatformNodeLatestOperation:
      type: object
      additionalProperties: false
      properties:
        operation:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        summary:
          type: string
        occurred_at:
          type: string
          format: date-time
          nullable: true
        correlation_id:
          type: string
          nullable: true
        task_href:
          type: string
          nullable: true
        evidence_href:
          type: string
          nullable: true
      required:
      - operation
      - status
      - summary
      - occurred_at
      - correlation_id
      - task_href
      - evidence_href
    V3PlatformNodeSchedulability:
      type: object
      additionalProperties: false
      properties:
        state:
          type: string
          enum:
          - schedulable
          - cordoned
          - draining
          - offline
          - retired
          - blocked
        can_cordon:
          type: boolean
        can_drain:
          type: boolean
        can_resume_scheduling:
          type: boolean
        next_safe_action:
          type: string
        disabled_reason:
          type: string
          nullable: true
      required:
      - state
      - can_cordon
      - can_drain
      - can_resume_scheduling
      - next_safe_action
      - disabled_reason
    V3PlatformNodeFact:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
        label:
          type: string
        value:
          type: string
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
      required:
      - key
      - label
      - value
      - severity
    V3PlatformNodeAgent:
      type: object
      additionalProperties: false
      properties:
        version:
          type: string
          nullable: true
        commit:
          type: string
          nullable: true
        built_at:
          type: string
          nullable: true
        reported_at:
          type: string
          format: date-time
          nullable: true
        lifecycle_status:
          type: string
          nullable: true
        desired_agent_version:
          type: string
          nullable: true
        reported_agent_version:
          type: string
          nullable: true
        error_code:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
      required:
      - version
      - commit
      - built_at
      - reported_at
      - lifecycle_status
      - desired_agent_version
      - reported_agent_version
      - error_code
      - error_message
    V3PlatformNodeMAAS:
      type: object
      additionalProperties: false
      properties:
        site_id:
          type: string
          format: uuid
          nullable: true
        maas_system_id:
          type: string
          nullable: true
        last_maas_status:
          type: string
          nullable: true
        last_maas_power_state:
          type: string
          nullable: true
        last_maas_ips:
          type: array
          items:
            type: string
        drift_detected:
          type: boolean
        last_reconciled_at:
          type: string
          format: date-time
          nullable: true
      required:
      - site_id
      - maas_system_id
      - last_maas_status
      - last_maas_power_state
      - last_maas_ips
      - drift_detected
      - last_reconciled_at
    V3PlatformNodeAllocation:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
        capacity_shape:
          type: string
        sku:
          type: string
        requested_by_user_id:
          type: string
          format: uuid
        requested_by_username:
          type: string
          nullable: true
        tenant_name:
          type: string
          nullable: true
        project_name:
          type: string
          nullable: true
        active_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        open_href:
          type: string
      required:
      - id
      - status
      - capacity_shape
      - sku
      - requested_by_user_id
      - requested_by_username
      - tenant_name
      - project_name
      - active_at
      - created_at
      - open_href
    V3PlatformNodeSlot:
      type: object
      additionalProperties: false
      properties:
        slot_index:
          type: integer
        status:
          type: string
        profile_name:
          type: string
          nullable: true
        accelerator_model:
          type: string
          nullable: true
        gpu_index:
          type: integer
          nullable: true
        gpu_uuid:
          type: string
          nullable: true
        private_ip:
          type: string
          nullable: true
        health_state:
          type: string
      required:
      - slot_index
      - status
      - profile_name
      - accelerator_model
      - gpu_index
      - gpu_uuid
      - private_ip
      - health_state
    V3PlatformNodeTask:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        task_type:
          type: string
        status:
          type: string
        issued_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        error:
          type: string
          nullable: true
        correlation_id:
          type: string
      required:
      - id
      - task_type
      - status
      - issued_at
      - completed_at
      - error
      - correlation_id
    V3PlatformNodeActivityItem:
      type: object
      additionalProperties: false
      description: First-class lifecycle/activity row for a platform node. The UI
        must prefer this over deriving activity from unrelated sections.
      properties:
        id:
          type: string
        occurred_at:
          type: string
          format: date-time
          nullable: true
        source:
          type: string
          enum:
          - allocation
          - node_task
          - agent_lifecycle
          - maas_decommission
          - audit
          - fact
        action:
          type: string
        status:
          type: string
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
        summary:
          type: string
        actor:
          type: string
          nullable: true
        correlation_id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
      required:
      - id
      - occurred_at
      - source
      - action
      - status
      - severity
      - summary
      - actor
      - correlation_id
      - href
    V3PlatformNodeCapability:
      type: object
      additionalProperties: false
      description: Operation capability advertised by the node lifecycle read model.
      properties:
        key:
          type: string
        label:
          type: string
        available:
          type: boolean
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
        summary:
          type: string
        href:
          type: string
          nullable: true
      required:
      - key
      - label
      - available
      - severity
      - summary
      - href
    V3PlatformNodeOperationIntentGroup:
      type: object
      additionalProperties: false
      description: Intent group for node lifecycle operations.
      properties:
        key:
          type: string
          enum:
          - inspect
          - repair
          - scheduling
          - provisioning
          - retirement
          - destructive
        label:
          type: string
        description:
          type: string
      required:
      - key
      - label
      - description
    V3PlatformNodeOperation:
      type: object
      additionalProperties: false
      description: Server-derived operation affordance for node lifecycle recovery
        and maintenance.
      properties:
        key:
          type: string
        group:
          type: string
          enum:
          - inspect
          - repair
          - scheduling
          - provisioning
          - retirement
          - destructive
        label:
          type: string
        description:
          type: string
        preconditions:
          type: array
          items:
            type: string
        result:
          type: string
        progress_location:
          type: string
        failure_path:
          type: string
        evidence_href:
          type: string
          nullable: true
        mutation_method:
          type: string
          enum:
          - POST
          nullable: true
        mutation_href:
          type: string
          nullable: true
        danger:
          type: string
          enum:
          - safe
          - low
          - medium
          - high
          - destructive
        enabled:
          type: boolean
        disabled_reason:
          type: string
          nullable: true
      required:
      - key
      - group
      - label
      - description
      - preconditions
      - result
      - progress_location
      - failure_path
      - evidence_href
      - mutation_method
      - mutation_href
      - danger
      - enabled
      - disabled_reason
    V3PlatformNodeLifecycleMutationResponse:
      type: object
      additionalProperties: false
      description: Result envelope for V3 platform node scheduling lifecycle mutations.
      properties:
        ok:
          type: boolean
        operation:
          type: string
          enum:
          - cordon
          - drain
          - resume_scheduling
          - refresh_inventory
        node_id:
          type: string
          format: uuid
        previous_status:
          type: string
          nullable: true
        status:
          type: string
        task_id:
          type: string
          format: uuid
          nullable: true
        task_type:
          type: string
          nullable: true
        recovery_action:
          "$ref": "#/components/schemas/AdminNodeLifecycleRecoveryAction"
          nullable: true
        correlation_id:
          type: string
        evidence_href:
          type: string
        task_href:
          type: string
          nullable: true
      required:
      - ok
      - operation
      - node_id
      - previous_status
      - status
      - task_id
      - task_type
      - recovery_action
      - correlation_id
      - evidence_href
      - task_href
    V3PlatformSetupChecklistStatus:
      type: string
      enum:
      - configured
      - missing
      - stale
      - unsafe
    V3PlatformSetupChecklistRow:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
        label:
          type: string
        area:
          type: string
          enum:
          - identity_pki
          - registry_artifacts
          - fleet_provisioning
          - runtime_inventory
          - telemetry
          - network_security
          - storage
        status:
          "$ref": "#/components/schemas/V3PlatformSetupChecklistStatus"
        detail:
          type: string
        owner:
          type: string
        next_action:
          type: string
          nullable: true
        evidence_href:
          type: string
          nullable: true
        config_href:
          type: string
      required:
      - key
      - label
      - area
      - status
      - detail
      - owner
      - next_action
      - evidence_href
      - config_href
    V3PlatformSetupChecklistResponse:
      type: object
      additionalProperties: false
      properties:
        kpis:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformKPI"
        rows:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformSetupChecklistRow"
        action_queue:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformActionItem"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - kpis
      - rows
      - action_queue
      - meta
    V3PlatformOnboardingMode:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          enum:
          - automated_maas
          - manual_bootstrap
        label:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        disabled_reason:
          type: string
          nullable: true
      required:
      - key
      - label
      - description
      - enabled
      - disabled_reason
    V3PlatformOnboardingSite:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        region_code:
          type: string
        status:
          type: string
        last_probe_ok:
          type: boolean
          nullable: true
        active_onboardings:
          type: integer
          format: int64
        open_href:
          type: string
      required:
      - id
      - name
      - region_code
      - status
      - last_probe_ok
      - active_onboardings
      - open_href
    V3PlatformOnboardingProfile:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        site_name:
          type: string
        status:
          type: string
        is_default:
          type: boolean
        distro_series:
          type: string
        architecture:
          type: string
        fabric_mode:
          type: string
        site_bootstrap_bundle_ref:
          type: string
          nullable: true
        commissioning_bundle_ref:
          type: string
          nullable: true
        post_deploy_validation_bundle_ref:
          type: string
          nullable: true
        batch_max_parallel:
          type: integer
      required:
      - id
      - name
      - site_name
      - status
      - is_default
      - distro_series
      - architecture
      - fabric_mode
      - site_bootstrap_bundle_ref
      - commissioning_bundle_ref
      - post_deploy_validation_bundle_ref
      - batch_max_parallel
    V3PlatformOnboardingStep:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
        label:
          type: string
        summary:
          type: string
        automated:
          type: boolean
      required:
      - key
      - label
      - summary
      - automated
    V3PlatformOnboardingAutomation:
      type: object
      additionalProperties: false
      properties:
        maas_mutation_ready:
          type: boolean
        manual_bootstrap_ready:
          type: boolean
        bootstrap_token_ttl_seconds:
          type: integer
        progress_poll_interval_seconds:
          type: integer
        disabled_reason:
          type: string
          nullable: true
      required:
      - maas_mutation_ready
      - manual_bootstrap_ready
      - bootstrap_token_ttl_seconds
      - progress_poll_interval_seconds
      - disabled_reason
    V3PlatformOnboardingGuidanceResponse:
      type: object
      additionalProperties: false
      properties:
        modes:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformOnboardingMode"
        sites:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformOnboardingSite"
        profiles:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformOnboardingProfile"
        prerequisites:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformSetupChecklistRow"
        steps:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformOnboardingStep"
        automation:
          "$ref": "#/components/schemas/V3PlatformOnboardingAutomation"
        manual_command_template:
          type: string
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - modes
      - sites
      - profiles
      - prerequisites
      - steps
      - automation
      - manual_command_template
      - meta
    V3PlatformAuditRow:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        occurred_at:
          type: string
          format: date-time
        actor:
          type: string
        action:
          type: string
        target:
          type: string
        result:
          type: string
        correlation_id:
          type: string
          nullable: true
      required:
      - id
      - occurred_at
      - actor
      - action
      - target
      - result
      - correlation_id
    V3PlatformPaymentSessionRow:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        user_id:
          type: string
          nullable: true
        user_label:
          type: string
          nullable: true
        amount_minor:
          type: integer
          format: int64
        credited_amount_minor:
          type: integer
          format: int64
          nullable: true
        currency:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
        initiated_at:
          type: string
          format: date-time
        checkout_completed_at:
          type: string
          format: date-time
          nullable: true
        credited_at:
          type: string
          format: date-time
          nullable: true
        failed_at:
          type: string
          format: date-time
          nullable: true
        reason_hint:
          type: string
          nullable: true
        ledger_entry_id:
          type: string
          nullable: true
        correlation_id:
          type: string
          nullable: true
        attention_reason:
          type: string
          nullable: true
        detail_href:
          type: string
        diagnostics_href:
          type: string
          nullable: true
        signal_key:
          type: string
          description: Backend-owned mutation handle for ack/suppression. Clients
            must pass it opaquely and never derive it.
        target_type:
          type: string
        target_id:
          type: string
        ack_fingerprint:
          type: string
          description: Backend-owned fingerprint for resurface detection. Clients
            must never derive it.
        ack_state:
          "$ref": "#/components/schemas/V3PlatformAckState"
        ack_reason:
          type: string
          nullable: true
        ack_expires_at:
          type: string
          format: date-time
          nullable: true
        ack_actor:
          type: string
          nullable: true
        ack_updated_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - user_id
      - amount_minor
      - currency
      - status
      - created_at
      - reason_hint
      - correlation_id
      - signal_key
      - target_type
      - target_id
      - ack_fingerprint
      - ack_state
      - ack_reason
      - ack_expires_at
      - ack_actor
      - ack_updated_at
    V3PlatformUserRoleRow:
      type: object
      additionalProperties: false
      properties:
        user_id:
          type: string
          format: uuid
        username:
          type: string
        org_id:
          type: string
          format: uuid
          nullable: true
        platform_roles:
          type: array
          items:
            type: string
        balance_minor:
          type: integer
          format: int64
          nullable: true
      required:
      - user_id
      - username
      - org_id
      - platform_roles
      - balance_minor
    V3PlatformOverviewResponse:
      type: object
      additionalProperties: false
      properties:
        kpis:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformKPI"
        families:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformFamilyCard"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - kpis
      - families
      - meta
    V3PlatformOpsResponse:
      type: object
      additionalProperties: false
      properties:
        signals:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformActionItem"
        health:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformHealthItem"
        tools:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformFamilyCard"
        workflows:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - signals
      - health
      - tools
      - workflows
      - meta
    V3PlatformLifecycleResponse:
      type: object
      additionalProperties: false
      properties:
        kpis:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformKPI"
        action_queue:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformActionItem"
        nodes:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeRow"
        intervention_queues:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        onboarding_workflows:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        decommission_workflows:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        agent_workflows:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        maas_profiles:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - kpis
      - action_queue
      - nodes
      - intervention_queues
      - onboarding_workflows
      - decommission_workflows
      - agent_workflows
      - maas_profiles
      - pagination
      - meta
    V3PlatformNodeDetailResponse:
      type: object
      additionalProperties: false
      properties:
        summary:
          "$ref": "#/components/schemas/V3PlatformNodeRow"
        facts:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeFact"
        agent:
          "$ref": "#/components/schemas/V3PlatformNodeAgent"
        maas:
          "$ref": "#/components/schemas/V3PlatformNodeMAAS"
        allocations:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeAllocation"
        slots:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeSlot"
        tasks:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeTask"
        activity:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeActivityItem"
        capabilities:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeCapability"
        operation_groups:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeOperationIntentGroup"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformNodeOperation"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - summary
      - facts
      - agent
      - maas
      - allocations
      - slots
      - tasks
      - activity
      - capabilities
      - operation_groups
      - operations
      - meta
    V3PlatformConfigResponse:
      type: object
      additionalProperties: false
      properties:
        kpis:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformKPI"
        rows:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformFamilyCard"
        publish_workflows:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformConfigOperation"
        activity:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformConfigActivityItem"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - kpis
      - rows
      - publish_workflows
      - operations
      - activity
      - meta
    V3PlatformConfigOperation:
      type: object
      additionalProperties: false
      description: Server-owned operation affordance for platform configuration lifecycle
        actions. Row-scoped operations use templated hrefs and are disabled until
        the UI supplies the selected target.
      properties:
        key:
          type: string
        source:
          type: string
          enum:
          - sku
          - os_image
          - policy
          - quota
          - maas_profile
          - maas_site
        label:
          type: string
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
        href:
          type: string
        target_type:
          type: string
        target_id:
          type: string
          nullable: true
        enabled:
          type: boolean
        disabled_reason:
          type: string
          nullable: true
        danger:
          type: string
          enum:
          - safe
          - low
          - medium
          - high
          - destructive
        audit_action:
          type: string
        result:
          type: string
        latest_actor:
          type: string
          nullable: true
        latest_at:
          type: string
          format: date-time
          nullable: true
        evidence_href:
          type: string
          nullable: true
      required:
      - key
      - source
      - label
      - method
      - href
      - target_type
      - target_id
      - enabled
      - disabled_reason
      - danger
      - audit_action
      - result
      - latest_actor
      - latest_at
      - evidence_href
    V3PlatformConfigActivityItem:
      type: object
      additionalProperties: false
      description: First-class lifecycle/activity row for durable platform configuration
        changes.
      properties:
        id:
          type: string
        occurred_at:
          type: string
          format: date-time
          nullable: true
        source:
          type: string
          enum:
          - sku
          - os_image
          - policy
          - maas_profile
          - maas_site
          - quota
          - audit
        action:
          type: string
        status:
          type: string
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
        summary:
          type: string
        actor:
          type: string
          nullable: true
        correlation_id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
      required:
      - id
      - occurred_at
      - source
      - action
      - status
      - severity
      - summary
      - actor
      - correlation_id
      - href
    V3PlatformEvidenceResponse:
      type: object
      additionalProperties: false
      properties:
        rows:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformAuditRow"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        tools:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformFamilyCard"
        pivots:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - rows
      - pagination
      - tools
      - pivots
      - meta
    V3PlatformFinanceResponse:
      type: object
      additionalProperties: false
      properties:
        kpis:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformKPI"
        sessions:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformPaymentSessionRow"
        action_queue:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformActionItem"
        interventions:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        activity:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformFinanceActivityItem"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - kpis
      - sessions
      - action_queue
      - interventions
      - activity
      - pagination
      - meta
    V3PlatformFinanceSessionsResponse:
      type: object
      additionalProperties: false
      properties:
        sessions:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformPaymentSessionRow"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        filters:
          "$ref": "#/components/schemas/V3PlatformFinanceSessionFilters"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - sessions
      - pagination
      - filters
      - meta
    V3PlatformFinanceSessionFilters:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          nullable: true
        user_id:
          type: string
          nullable: true
        correlation_id:
          type: string
          nullable: true
      required:
      - status
      - user_id
      - correlation_id
    V3PlatformFinanceSessionDetailResponse:
      type: object
      additionalProperties: false
      properties:
        summary:
          "$ref": "#/components/schemas/V3PlatformPaymentSessionRow"
        diagnostics:
          "$ref": "#/components/schemas/V3PlatformFinanceSessionDiagnostics"
        operations:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformFinanceSessionOperation"
        recovery_policy:
          "$ref": "#/components/schemas/V3PlatformFinanceSessionRecoveryPolicy"
        activity:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformFinanceActivityItem"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - summary
      - diagnostics
      - operations
      - recovery_policy
      - activity
      - meta
    V3PlatformFinanceSessionDiagnostics:
      type: object
      additionalProperties: false
      properties:
        payment_session_id:
          type: string
        correlation_id:
          type: string
          nullable: true
        billing_diagnostics_href:
          type: string
          nullable: true
        evidence_href:
          type: string
        payment_session_count:
          type: integer
          format: int64
        ledger_entry_count:
          type: integer
          format: int64
        refund_count:
          type: integer
          format: int64
        audit_log_count:
          type: integer
          format: int64
      required:
      - payment_session_id
      - correlation_id
      - billing_diagnostics_href
      - evidence_href
      - payment_session_count
      - ledger_entry_count
      - refund_count
      - audit_log_count
    V3PlatformFinanceSessionOperation:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          enum:
          - post_credit
          - mark_expired
          - mark_failed
          - create_refund
        label:
          type: string
        method:
          type: string
          enum:
          - POST
        href:
          type: string
        target_type:
          type: string
        target_id:
          type: string
        enabled:
          type: boolean
        disabled_reason:
          type: string
          nullable: true
        danger:
          type: string
          enum:
          - safe
          - low
          - medium
          - high
          - destructive
        audit_action:
          type: string
        result:
          type: string
        recovery_mode:
          type: string
          enum:
          - manual_internal_credit
          - manual_state_update
          - manual_refund_workflow
      required:
      - key
      - label
      - method
      - href
      - target_type
      - target_id
      - enabled
      - disabled_reason
      - danger
      - audit_action
      - result
      - recovery_mode
    V3PlatformFinanceSessionRecoveryPolicy:
      type: object
      additionalProperties: false
      properties:
        provider_replay_supported:
          type: boolean
        provider_replay_reason:
          type: string
        supported_modes:
          type: array
          items:
            type: string
            enum:
            - manual_internal_credit
            - manual_state_update
            - manual_refund_workflow
      required:
      - provider_replay_supported
      - provider_replay_reason
      - supported_modes
    V3PlatformFinanceActivityItem:
      type: object
      additionalProperties: false
      description: First-class lifecycle/activity row for platform finance operations.
        This intentionally excludes provider payment references and raw webhook payloads.
      properties:
        id:
          type: string
        occurred_at:
          type: string
          format: date-time
          nullable: true
        source:
          type: string
          enum:
          - payment_session
          - ledger
          - refund
          - audit
          - outbox
        action:
          type: string
        status:
          type: string
        severity:
          "$ref": "#/components/schemas/V3PlatformSeverity"
        summary:
          type: string
        actor:
          type: string
          nullable: true
        user_id:
          type: string
          nullable: true
        amount_minor:
          type: integer
          format: int64
          nullable: true
        currency:
          type: string
          nullable: true
        correlation_id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
      required:
      - id
      - occurred_at
      - source
      - action
      - status
      - severity
      - summary
      - actor
      - user_id
      - amount_minor
      - currency
      - correlation_id
      - href
    V3PlatformIAMResponse:
      type: object
      additionalProperties: false
      properties:
        kpis:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformKPI"
        users:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformUserRoleRow"
        governance:
          type: array
          items:
            "$ref": "#/components/schemas/V3PlatformWorkflowCard"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - kpis
      - users
      - governance
      - pagination
      - meta
    V3WorkloadLifecycleItem:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
        status:
          type: string
          enum:
          - completed
          - current
          - pending
          - failed
        occurred_at:
          type: string
          format: date-time
          nullable: true
        summary:
          type: string
      required:
      - label
      - status
      - occurred_at
      - summary
    V3WorkloadEventItem:
      type: object
      additionalProperties: false
      properties:
        occurred_at:
          type: string
          format: date-time
        actor:
          type: string
          nullable: true
        action:
          type: string
        status:
          type: string
        source:
          type: string
        summary:
          type: string
      required:
      - occurred_at
      - actor
      - action
      - status
      - source
      - summary
    V3WorkloadConnectTab:
      type: object
      additionalProperties: false
      properties:
        primary_action:
          type: string
          enum:
          - open
          - connect
          - open_notebook
          - try_endpoint
          - open_training_ui
          - retry_release
          - review
          - none
        terminal_href:
          type: string
          nullable: true
        ssh_command:
          type: string
          nullable: true
        app_url:
          type: string
          nullable: true
        app_proxy_launch:
          "$ref": "#/components/schemas/V3WorkloadAppProxyLaunch"
          nullable: true
        notes:
          type: array
          items:
            type: string
      required:
      - primary_action
      - terminal_href
      - ssh_command
      - app_url
      - app_proxy_launch
      - notes
    V3WorkloadAppProxyLaunch:
      type: object
      additionalProperties: false
      description: |
        Browser-session launch context for a workload UI endpoint published through
        the platform proxy. The web client must mint a browser session before
        navigating; do not place auth material in URLs.
      properties:
        project_id:
          type: string
          format: uuid
        app_instance_id:
          type: string
          format: uuid
        endpoint_name:
          type: string
          minLength: 1
        open_path_suffix:
          type: string
          nullable: true
          description: Optional suffix appended after the session mint response when
            the app has a preferred landing path such as `/lab`.
        verify_strategy:
          type: string
          enum:
          - none
          - html_only
          - html_plus_asset
      required:
      - project_id
      - app_instance_id
      - endpoint_name
      - open_path_suffix
      - verify_strategy
    V3WorkloadMetricsTab:
      type: object
      additionalProperties: false
      properties:
        source:
          type: string
          enum:
          - allocation_metrics
          - guest_metrics
          - node_metrics
          - unavailable
        snapshot_href:
          type: string
          nullable: true
        timeseries_href:
          type: string
          nullable: true
        sampled_at:
          type: string
          format: date-time
          nullable: true
        capabilities:
          type: array
          items:
            type: string
      required:
      - source
      - snapshot_href
      - timeseries_href
      - sampled_at
      - capabilities
    V3WorkloadStorageMount:
      type: object
      additionalProperties: false
      properties:
        bucket_id:
          type: string
          nullable: true
        bucket_name:
          type: string
          nullable: true
        mount_path:
          type: string
        access_mode:
          type: string
          enum:
          - read_only
          - read_write
        state:
          type: string
          enum:
          - mounted
          - pending
          - failed
          - detached
        source:
          type: string
      required:
      - bucket_id
      - bucket_name
      - mount_path
      - access_mode
      - state
      - source
    V3WorkloadOverviewTab:
      type: object
      additionalProperties: false
      properties:
        lifecycle:
          type: array
          items:
            "$ref": "#/components/schemas/V3WorkloadLifecycleItem"
        recent_activity:
          type: array
          items:
            "$ref": "#/components/schemas/V3WorkloadEventItem"
        summary:
          type: string
      required:
      - lifecycle
      - recent_activity
      - summary
    V3WorkloadEventsTab:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3WorkloadEventItem"
        timeline_href:
          type: string
      required:
      - items
      - timeline_href
    V3WorkloadStorageTab:
      type: object
      additionalProperties: false
      properties:
        mounts:
          type: array
          items:
            "$ref": "#/components/schemas/V3WorkloadStorageMount"
        storage_href:
          type: string
          nullable: true
      required:
      - mounts
      - storage_href
    V3WorkloadCredentialPosture:
      type: object
      additionalProperties: false
      description: App-runtime credential posture metadata only. Never include private
        keys, tokens, passwords, wrapped tokens, or provider secrets.
      properties:
        credential_id:
          type: string
          format: uuid
        binding_id:
          type: string
          format: uuid
        label:
          type: string
        purpose:
          type: string
        kind:
          type: string
        status:
          type: string
        scope_type:
          type: string
        severity:
          type: string
          enum:
          - ok
          - info
          - warn
          - error
        summary:
          type: string
        last_validated_at:
          type: string
          format: date-time
          nullable: true
        last_used_at:
          type: string
          format: date-time
          nullable: true
        rotation_due_at:
          type: string
          format: date-time
          nullable: true
      required:
      - credential_id
      - binding_id
      - label
      - purpose
      - kind
      - status
      - scope_type
      - severity
      - summary
      - last_validated_at
      - last_used_at
      - rotation_due_at
    V3WorkloadConfigTab:
      type: object
      additionalProperties: false
      properties:
        scheduler_type:
          type: string
        capacity_shape:
          type: string
        placement_status:
          type: string
        sku:
          type: string
        gpus_total:
          type: integer
          minimum: 0
        effective_config:
          type: object
          additionalProperties: true
        credential_posture:
          type: array
          items:
            "$ref": "#/components/schemas/V3WorkloadCredentialPosture"
      required:
      - scheduler_type
      - capacity_shape
      - placement_status
      - sku
      - gpus_total
      - effective_config
      - credential_posture
    V3WorkloadDetailTabs:
      type: object
      additionalProperties: false
      description: V3Workload detail tabs are typed so production pages can match
        the mock without ad-hoc payloads.
      properties:
        overview:
          "$ref": "#/components/schemas/V3WorkloadOverviewTab"
        connect:
          "$ref": "#/components/schemas/V3WorkloadConnectTab"
        metrics:
          "$ref": "#/components/schemas/V3WorkloadMetricsTab"
        events:
          "$ref": "#/components/schemas/V3WorkloadEventsTab"
        storage:
          "$ref": "#/components/schemas/V3WorkloadStorageTab"
        config:
          "$ref": "#/components/schemas/V3WorkloadConfigTab"
      required:
      - overview
      - connect
      - metrics
      - events
      - storage
      - config
    V3StoragePrincipalKind:
      type: string
      enum:
      - project
      - user
      - service_account
      - workload
      - tenant_group
    V3StoragePermission:
      type: string
      enum:
      - list
      - read
      - write
      - delete
      - mount
      - admin
    V3StorageGrantSubject:
      type: object
      additionalProperties: false
      properties:
        kind:
          "$ref": "#/components/schemas/V3StoragePrincipalKind"
        id:
          type: string
          minLength: 1
          maxLength: 128
        project_id:
          type: string
          format: uuid
          nullable: true
      required:
      - kind
      - id
      - project_id
    V3StorageGrantScope:
      type: object
      additionalProperties: false
      properties:
        bucket_id:
          type: string
          minLength: 1
          maxLength: 128
        prefixes:
          type: array
          items:
            type: string
            maxLength: 1024
          description: Empty means the whole bucket. Prefixes are normalized by the
            storage service before provider policy compilation.
      required:
      - bucket_id
      - prefixes
    V3StorageGrant:
      type: object
      additionalProperties: false
      description: GPUaaS-owned storage grant. Provider policy is compiled from this
        record; WEKA/VAST/provider raw policy is not exposed.
      properties:
        id:
          type: string
          format: uuid
        owner_project_id:
          type: string
          format: uuid
        subject:
          "$ref": "#/components/schemas/V3StorageGrantSubject"
        scope:
          "$ref": "#/components/schemas/V3StorageGrantScope"
        permissions:
          type: array
          minItems: 1
          items:
            "$ref": "#/components/schemas/V3StoragePermission"
        provider_backend:
          "$ref": "#/components/schemas/V3StorageBackendType"
        provider_policy_ref:
          type: string
          nullable: true
          description: Opaque GPUaaS/provider binding reference; never raw policy
            JSON.
        expires_at:
          type: string
          format: date-time
          nullable: true
        reason:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - owner_project_id
      - subject
      - scope
      - permissions
      - provider_backend
      - provider_policy_ref
      - expires_at
      - reason
      - created_at
      - revoked_at
    V3StorageGrantCreateRequest:
      type: object
      additionalProperties: false
      properties:
        subject:
          "$ref": "#/components/schemas/V3StorageGrantSubject"
        prefixes:
          type: array
          items:
            type: string
            maxLength: 1024
        permissions:
          type: array
          minItems: 1
          items:
            "$ref": "#/components/schemas/V3StoragePermission"
        expires_at:
          type: string
          format: date-time
          nullable: true
        reason:
          type: string
          maxLength: 256
      required:
      - subject
      - prefixes
      - permissions
      - expires_at
      - reason
    V3StorageGrantResponse:
      type: object
      additionalProperties: false
      properties:
        grant:
          "$ref": "#/components/schemas/V3StorageGrant"
        evidence:
          "$ref": "#/components/schemas/V3MutationEvidence"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - grant
      - evidence
      - meta
    V3StorageGrantRevokeResponse:
      type: object
      additionalProperties: false
      properties:
        grant_id:
          type: string
          format: uuid
        bucket_id:
          type: string
        revoked:
          type: boolean
        evidence:
          "$ref": "#/components/schemas/V3MutationEvidence"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - grant_id
      - bucket_id
      - revoked
      - evidence
      - meta
    V3StorageGrantListResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/V3StorageGrant"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - items
      - pagination
      - meta
    V3StorageCredentialClientKind:
      type: string
      enum:
      - s3_cli
      - sdk
      - workload_mount
    V3StorageCredentialType:
      type: string
      enum:
      - s3_session
      - provider_session
      - vault_wrapped_secret
    V3StorageCredentialSessionState:
      type: string
      enum:
      - active
      - expired
      - revocation_pending
      - revoked
      - failed
    V3StorageCredentialIssueRequest:
      type: object
      additionalProperties: false
      properties:
        subject:
          "$ref": "#/components/schemas/V3StorageGrantSubject"
        prefixes:
          type: array
          items:
            type: string
            maxLength: 1024
        permissions:
          type: array
          minItems: 1
          items:
            "$ref": "#/components/schemas/V3StoragePermission"
        ttl_seconds:
          type: integer
          minimum: 60
          maximum: 43200
        client_kind:
          "$ref": "#/components/schemas/V3StorageCredentialClientKind"
        reason:
          type: string
          maxLength: 256
      required:
      - subject
      - prefixes
      - permissions
      - ttl_seconds
      - client_kind
      - reason
    V3StorageCredentialScopeSummary:
      type: object
      additionalProperties: false
      properties:
        bucket_id:
          type: string
        prefixes:
          type: array
          items:
            type: string
        permissions:
          type: array
          items:
            "$ref": "#/components/schemas/V3StoragePermission"
        provider_backend:
          "$ref": "#/components/schemas/V3StorageBackendType"
      required:
      - bucket_id
      - prefixes
      - permissions
      - provider_backend
    V3StorageCredentialSessionEvidence:
      type: object
      additionalProperties: false
      description: User-safe durable evidence for a one-time provider credential issuance.
        This object may appear in read models and audit pivots; it must never contain
        provider access keys, secret keys, session tokens, wrapped-token bytes, or
        raw provider policy JSON.
      properties:
        credential_session_id:
          type: string
          format: uuid
        credential_type:
          "$ref": "#/components/schemas/V3StorageCredentialType"
        client_kind:
          "$ref": "#/components/schemas/V3StorageCredentialClientKind"
        subject:
          "$ref": "#/components/schemas/V3StorageGrantSubject"
        scope:
          "$ref": "#/components/schemas/V3StorageCredentialScopeSummary"
        issued_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        revocation_state:
          "$ref": "#/components/schemas/V3StorageCredentialSessionState"
        revoke_supported:
          type: boolean
          description: Whether the selected provider supports active session revocation
            before expiry.
        source_workflow_id:
          type: string
          nullable: true
        audit_action:
          type: string
          enum:
          - auth.provider_credential.issue
          - storage.credential.issue
      required:
      - credential_session_id
      - credential_type
      - client_kind
      - subject
      - scope
      - issued_at
      - expires_at
      - revocation_state
      - revoke_supported
      - source_workflow_id
      - audit_action
    V3StorageCredentialIssueResponse:
      type: object
      additionalProperties: false
      description: One-time credential issuance response. Credential material is returned
        only here; read models may keep only the nested session evidence.
      properties:
        credential_session_id:
          type: string
          format: uuid
        credential_type:
          "$ref": "#/components/schemas/V3StorageCredentialType"
        provider_backend:
          "$ref": "#/components/schemas/V3StorageBackendType"
        endpoint:
          type: string
          format: uri
        access_key_id:
          type: string
        secret_access_key:
          type: string
        session_token:
          type: string
          nullable: true
        expires_at:
          type: string
          format: date-time
        scope:
          "$ref": "#/components/schemas/V3StorageCredentialScopeSummary"
        session:
          "$ref": "#/components/schemas/V3StorageCredentialSessionEvidence"
      required:
      - credential_session_id
      - credential_type
      - provider_backend
      - endpoint
      - access_key_id
      - secret_access_key
      - session_token
      - expires_at
      - scope
      - session
    V3AccessQuotaPosture:
      type: string
      enum:
      - ok
      - near_limit
      - blocked
    V3AccessQuotaSignal:
      type: object
      additionalProperties: false
      properties:
        severity:
          "$ref": "#/components/schemas/V3AccessSeverity"
        title:
          type: string
        summary:
          type: string
        action_label:
          type: string
          nullable: true
        action_href:
          type: string
          nullable: true
      required:
      - severity
      - title
      - summary
      - action_label
      - action_href
    V3AccessQuotaResponse:
      type: object
      additionalProperties: false
      properties:
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        user_id:
          type: string
          format: uuid
        limits:
          "$ref": "#/components/schemas/AllocationLimits"
        posture:
          "$ref": "#/components/schemas/V3AccessQuotaPosture"
        signals:
          type: array
          items:
            "$ref": "#/components/schemas/V3AccessQuotaSignal"
        meta:
          "$ref": "#/components/schemas/V3ReadModelMeta"
      required:
      - project_id
      - project_name
      - user_id
      - limits
      - posture
      - signals
      - meta
    V3StorageObjectPathRequest:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 1024
      required:
      - path
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ErrorResponse"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ErrorResponse"
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ErrorResponse"
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ErrorResponse"
    ServiceUnavailable:
      description: Service unavailable
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ErrorResponse"
    TooManyRequests:
      description: Too many requests — rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Request limit per window.
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining in current window.
        Retry-After:
          schema:
            type: integer
          description: Seconds until the rate limit window resets.
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ErrorResponse"
paths:
  "/api/v1/bootstrap/nodes/{bootstrap_token}/script":
    get:
      tags:
      - InternalNodes
      operationId: nodeBootstrapScript
      security: []
      summary: Fetch brokered node bootstrap script using a node-bound bootstrap token
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: bootstrap_token
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: mode
        in: query
        schema:
          type: string
          enum:
          - manual
          - cloud_init
          default: manual
      responses:
        '200':
          description: Shell script
          content:
            text/plain:
              schema:
                type: string
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/bootstrap/nodes/{bootstrap_token}/package":
    get:
      tags:
      - InternalNodes
      operationId: nodeBootstrapPackage
      security: []
      summary: Download brokered node bootstrap package using a node-bound bootstrap
        token
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: bootstrap_token
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Bootstrap package archive
          content:
            application/gzip:
              schema:
                type: string
                format: binary
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/bootstrap/nodes/{bootstrap_token}/registry-credential":
    get:
      tags:
      - InternalNodes
      operationId: nodeBootstrapRegistryCredential
      security: []
      summary: Fetch brokered registry pull credential using a node-bound bootstrap
        token
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: bootstrap_token
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Registry pull credential for node bootstrap runtime configuration
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeBootstrapRegistryCredential"
        '204':
          description: No registry pull credential is configured for this environment
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/bootstrap/nodes/{bootstrap_token}/progress":
    post:
      tags:
      - InternalNodes
      operationId: nodeBootstrapProgress
      security: []
      summary: Report first-boot MAAS bootstrap progress using a node-bound bootstrap
        token
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: bootstrap_token
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NodeBootstrapProgressRequest"
      responses:
        '202':
          description: Progress marker accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeBootstrapProgressResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/internal/v1/nodes/enroll":
    post:
      tags:
      - InternalNodes
      operationId: internalNodeEnroll
      security: []
      summary: Internal node enrollment endpoint (token-authenticated bootstrap)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/InternalNodeEnrollmentRequest"
      responses:
        '200':
          description: Enrollment certificate bundle
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/InternalNodeEnrollmentResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/internal/v1/nodes/{node_id}/cert/renew":
    post:
      tags:
      - InternalNodes
      operationId: internalNodeCertRenew
      security: []
      summary: Internal node certificate renewal endpoint (mTLS-authenticated)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/InternalNodeIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/InternalNodeCertRenewRequest"
      responses:
        '200':
          description: Renewed certificate
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/InternalNodeCertRenewResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/internal/v1/nodes/{node_id}/tasks/wait":
    get:
      tags:
      - InternalNodes
      operationId: internalNodeWaitTask
      security: []
      summary: Internal long-poll endpoint for node task dispatch
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/InternalNodeIdPath"
      responses:
        '200':
          description: Task available
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/InternalNodeTask"
        '204':
          description: No task currently available
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/internal/v1/nodes/{node_id}/tasks/{task_id}/result":
    post:
      tags:
      - InternalNodes
      operationId: internalNodeTaskResult
      security: []
      summary: Internal endpoint for node task completion reporting
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/InternalNodeIdPath"
      - "$ref": "#/components/parameters/InternalTaskIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/InternalNodeTaskResultRequest"
      responses:
        '200':
          description: Task result accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/InternalNodeTaskResultResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/internal/v1/nodes/{node_id}/terminal/stream":
    post:
      tags:
      - InternalNodes
      operationId: internalNodeTerminalStream
      security: []
      summary: Internal bidirectional relay stream for terminal frames
      description: |
        Internal-only stream channel used by terminal relay mode (`TERMINAL_MODE=node_agent_stream`).
        Node identity must be mTLS-authenticated and path node_id must match certificate identity.
      parameters:
      - "$ref": "#/components/parameters/InternalNodeIdPath"
      requestBody:
        required: true
        content:
          application/x-ndjson:
            schema:
              type: array
              items:
                "$ref": "#/components/schemas/InternalTerminalStreamFrame"
      responses:
        '200':
          description: Stream accepted
          content:
            application/x-ndjson:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/InternalTerminalStreamFrame"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/internal/v1/node-logs/loki/api/v1/push":
    post:
      tags:
      - InternalNodes
      operationId: internalNodeLogLokiPush
      summary: Internal node log gateway Loki push endpoint
      description: |
        Node-local collectors push Loki-compatible batches to `gpuaas-node-log-gateway`.
        The gateway validates node internal auth, caps request size, and forwards to the
        in-cluster Loki backend. Worker nodes must not write directly to raw Loki in production.
      security:
      - nodeBearerAuth: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
          application/x-protobuf:
            schema:
              type: string
              format: binary
      responses:
        '204':
          description: Batch accepted and forwarded to the log backend
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '413':
          description: Log batch exceeded the gateway request-size limit
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '502':
          description: Log backend unavailable or rejected the batch
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/internal/v1/app-proxy/routes/{route_id}/report":
    post:
      tags:
      - InternalAppProxy
      operationId: internalAppProxyRouteReport
      security: []
      summary: Internal endpoint for app proxy route reconciliation reporting
      description: |
        Internal-only control-plane endpoint used by a platform proxy controller or gateway reconciler.
        It records observed route state without making the public API a data-plane proxy.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: route_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/InternalAppProxyRouteReportRequest"
      responses:
        '200':
          description: Route report accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/InternalAppProxyRouteReportResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/workloads/{app_instance_id}/ui/{endpoint_name}/browser-session":
    post:
      tags:
      - Apps
      operationId: createAppProxyBrowserSession
      summary: Mint a short-lived browser session for a platform-proxied workload
        UI
      description: |
        Creates a scoped, short-lived HttpOnly browser cookie that allows a same-site
        browser navigation to an authenticated `platform_proxy` workload UI route
        without placing bearer tokens or app-local tokens in the URL. The session is
        scoped to the exact project, workload, and endpoint.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - name: app_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: endpoint_name
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Browser proxy session created
          headers:
            Set-Cookie:
              description: Scoped HttpOnly browser proxy session cookie.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - open_url
                - expires_at
                properties:
                  open_url:
                    type: string
                    description: Same-origin URL the browser can open after receiving
                      the session cookie.
                  expires_at:
                    type: string
                    format: date-time
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/platform-proxy/browser-session":
    post:
      tags:
      - Allocations
      operationId: createPlatformProxyBrowserSession
      summary: Mint a short-lived browser session for a platform proxy route
      description: |
        Creates a scoped, short-lived HttpOnly browser cookie that allows a
        same-site browser navigation to an authenticated platform proxy route
        such as allocation Netdata without placing bearer tokens in the URL.
        The request path is validated against supported platform proxy targets.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - path
              properties:
                path:
                  type: string
                  description: Browser-visible platform proxy path, for example `/backend/p/netdata/allocations/{allocation_id}`
                    or a deeper Netdata subpath.
      responses:
        '200':
          description: Browser proxy session created
          headers:
            Set-Cookie:
              description: Scoped HttpOnly browser proxy session cookie.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - open_url
                - expires_at
                properties:
                  open_url:
                    type: string
                    description: Same-origin URL the browser can open after receiving
                      the session cookie.
                  expires_at:
                    type: string
                    format: date-time
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/projects/{project_id}/workloads/{app_instance_id}/ui/{endpoint_name}/{proxy_path}":
    get:
      tags:
      - Apps
      operationId: proxyAppInstanceUi
      summary: Legacy authenticated platform proxy route for workload UI traffic
      description: |
        Legacy browser-facing HTTP/WebSocket-aware gateway path for app instance
        endpoints published through `platform_proxy`. New routes should use the
        app data-plane `/w/{app_instance_id}/{endpoint_name}/...` namespace.
        The API performs platform auth and project authorization, then proxies to
        the controller-reported active upstream. The backend response body is
        workload-defined.
      parameters:
      - "$ref": "#/components/parameters/ProjectIdPath"
      - name: app_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: endpoint_name
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: proxy_path
        in: path
        required: true
        schema:
          type: string
        description: Remaining workload UI path. Runtime routing also accepts the
          endpoint root without this suffix.
      responses:
        '200':
          description: Proxied workload response
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '502':
          description: Proxy upstream unavailable
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/w/{app_instance_id}/{endpoint_name}":
    get:
      tags:
      - Apps
      operationId: proxyAppInstanceUiDataPlaneRoot
      summary: Authenticated app data-plane proxy route root for workload UI traffic
      description: |
        Browser-facing app data-plane route root for app instance endpoints
        published through `platform_proxy`. The route root is intentionally
        outside the control-plane API namespace and may redirect to the
        app-configured default path such as `/lab`.
      parameters:
      - name: app_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: endpoint_name
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Proxied workload response
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '502':
          description: Proxy upstream unavailable
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/w/{app_instance_id}/{endpoint_name}/{proxy_path}":
    get:
      tags:
      - Apps
      operationId: proxyAppInstanceUiDataPlane
      summary: Authenticated app data-plane proxy route for workload UI traffic
      description: |
        Browser-facing app data-plane route for app instance endpoints published
        through `platform_proxy`. This path is intentionally outside the
        control-plane API namespace so interactive apps can safely use paths such
        as `/api`, `/lab`, `/static`, and WebSocket endpoints under their
        reserved prefix. Runtime routing also accepts the endpoint root without
        this suffix.
      parameters:
      - name: app_instance_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: endpoint_name
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: proxy_path
        in: path
        required: true
        schema:
          type: string
        description: Remaining workload UI path.
      responses:
        '200':
          description: Proxied workload response
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '502':
          description: Proxy upstream unavailable
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/p/netdata/allocations/{allocation_id}/{proxy_path}":
    get:
      tags:
      - Allocations
      operationId: proxyAllocationNetdata
      summary: Authenticated platform proxy route for allocation Netdata
      description: |
        Browser-facing Netdata proxy route for non-slice allocations. The
        response preserves allocation/project authorization and avoids exposing
        node private IPs directly in the UI.
      parameters:
      - name: allocation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: proxy_path
        in: path
        required: true
        schema:
          type: string
        description: Remaining Netdata path, for example `dashboard.html` or `api/v2/data`.
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: Proxied Netdata response
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '502':
          description: Proxy upstream unavailable
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/healthz":
    get:
      tags:
      - Health
      operationId: getHealth
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Health status
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HealthResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/auth/oidc/authorize":
    get:
      tags:
      - Auth
      operationId: getOidcAuthorizeUrl
      description: |
        OIDC authorize bootstrap.
        In tenant federation mode, server resolves tenant/provider mapping (OIDC) using
        verified domain bindings and/or advisory hints.
        `tenant_hint` and `identity_hint` are advisory only; server decides effective tenant context.
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          format: uri
      - name: code_challenge
        in: query
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 128
      - name: code_challenge_method
        in: query
        required: true
        schema:
          type: string
          enum:
          - S256
      - name: tenant_hint
        in: query
        required: false
        description: Advisory tenant hint for federation discovery. Format is tenant
          slug; never trusted without server-side resolution.
        schema:
          type: string
          minLength: 2
          maxLength: 63
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
      - name: identity_hint
        in: query
        required: false
        description: Advisory enterprise identity hint (work email). Personal identities
          should use personal sign-in flow.
        schema:
          type: string
          format: email
      - name: provider_hint
        in: query
        required: false
        description: Advisory social provider shortcut for the platform IdP broker.
          The server validates supported values and remains authoritative.
        schema:
          type: string
          enum:
          - github
          - google
          - huggingface
      responses:
        '200':
          description: OIDC authorization URL and state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OidcAuthorizeResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
  "/api/v1/auth/oidc/exchange":
    post:
      tags:
      - Auth
      operationId: exchangeOidcCode
      description: |
        Exchange callback code for GPUaaS session token.
        In federation-aware flows, callback state must be single-use and issuer/provider bound
        to the resolved tenant org_id.
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OidcExchangeRequest"
      responses:
        '200':
          description: Token exchange success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuthSessionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
  "/api/v1/auth/saml/authorize":
    get:
      tags:
      - Auth
      operationId: getSamlAuthorizeUrl
      description: |
        SAML authorize bootstrap.
        Resolves tenant/provider mapping (SAML) using verified domain bindings and/or
        an advisory tenant hint, then returns IdP redirect URL and opaque state.
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: redirect_uri
        in: query
        required: true
        description: Post-authentication redirect destination after successful ACS
          processing. Stored server-side in state; not sent to IdP. ACS URL remains
          fixed at `/api/v1/auth/saml/callback`.
        schema:
          type: string
          format: uri
      - name: tenant_hint
        in: query
        required: false
        description: Advisory tenant hint for federation discovery. Format is tenant
          slug; never trusted without server-side resolution.
        schema:
          type: string
          minLength: 2
          maxLength: 63
          pattern: "^[a-z0-9][a-z0-9-]{1,62}$"
      responses:
        '200':
          description: SAML redirect URL and state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SamlAuthorizeResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
  "/api/v1/auth/saml/callback":
    post:
      tags:
      - Auth
      operationId: exchangeSamlAssertion
      description: |
        Assertion Consumer Service (ACS) callback for SAML response handling.
        Callback state must be single-use and bound to resolved tenant/provider.
        This endpoint consumes standard SAML POST binding fields (`SAMLResponse`, `RelayState`).
        `Idempotency-Key` remains optional here; browser/IdP-driven callbacks primarily
        rely on single-use RelayState for replay protection.
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              "$ref": "#/components/schemas/SamlCallbackRequest"
      responses:
        '200':
          description: SAML exchange success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuthSessionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
  "/api/v1/auth/personal/login":
    post:
      tags:
      - Auth
      operationId: loginPersonal
      summary: Personal account password login
      description: |
        Direct login flow for personal accounts.
        Enterprise sign-in should use tenant federation endpoints.
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/LoginRequest"
      responses:
        '200':
          description: Login success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/LoginResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
  "/api/v1/auth/personal/signup":
    post:
      tags:
      - Auth
      operationId: signupPersonal
      summary: Personal account signup
      description: 'Creates a user and atomically bootstraps personal tenant + default
        project membership.

'
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SignupRequest"
      responses:
        '201':
          description: Signup success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SignupResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '409':
          "$ref": "#/components/responses/Conflict"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
  "/api/v1/auth/token/refresh":
    post:
      tags:
      - Auth
      operationId: refreshToken
      summary: Exchange a refresh token for a new access token
      description: |
        Public endpoint for session renewal.
        Supports refresh tokens issued for OIDC-backed sessions; OIDC remains the
        primary authentication model for production sign-in.
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RefreshTokenRequest"
      responses:
        '200':
          description: New access token issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RefreshTokenResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
  "/api/v1/auth/logout":
    post:
      tags:
      - Auth
      operationId: logout
      summary: Invalidate the current session and revoke tokens
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/LogoutRequest"
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      responses:
        '200':
          description: Session invalidated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/account/identity-links":
    get:
      tags:
      - Auth
      operationId: listMyIdentityLinks
      summary: List linked identity providers for the current user
      description: |
        Returns explicit identity-provider links for the authenticated account.
        Raw OAuth tokens, refresh tokens, and provider credential material are never returned.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Identity links for the current user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/UserIdentityLinkListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
    post:
      tags:
      - Auth
      operationId: createMyIdentityLink
      summary: Create an explicit identity-provider link for the current user
      description: |
        Creates a linked identity only after explicit proof such as a verified current-session
        provider callback, admin approval, or invite redemption. Duplicate email alone is not proof.
        The mutation is audited and idempotent.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateIdentityLinkRequest"
      responses:
        '201':
          description: Identity link created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateIdentityLinkResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/users/me":
    get:
      tags:
      - Users
      operationId: getMe
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Current user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/UserWithBalance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/projects":
    get:
      tags:
      - Projects
      operationId: listProjects
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Projects visible to current user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Projects
      operationId: createProject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateProjectRequest"
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateProjectResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}":
    patch:
      tags:
      - Projects
      operationId: updateProject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateProjectRequest"
      responses:
        '200':
          description: Project updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateProjectResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - Projects
      operationId: deleteProject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      responses:
        '200':
          description: Project deleted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/DeleteProjectResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/projects/{project_id}/set-default":
    post:
      tags:
      - Projects
      operationId: setDefaultProject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      responses:
        '200':
          description: Default project updated for current user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateProjectResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/apps/catalog":
    get:
      tags:
      - Apps
      operationId: listAppCatalog
      summary: List platform app catalog entries available to the caller
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: category
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - deprecated
          - disabled
      responses:
        '200':
          description: App catalog entries
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppCatalogListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/apps/catalog/{app_slug}/versions":
    get:
      tags:
      - Apps
      operationId: listAppCatalogVersions
      summary: List published versions for an app catalog entry
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/AppSlugPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: App catalog versions
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      "$ref": "#/components/schemas/AppCatalogVersion"
                  pagination:
                    "$ref": "#/components/schemas/Pagination"
                required:
                - items
                - pagination
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/apps/registry":
    get:
      tags:
      - AppArtifacts
      operationId: getAppRegistryInfo
      summary: Get platform OCI registry baseline information for the current environment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Platform OCI registry information
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OciRegistryInfo"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/platform/releases":
    get:
      tags:
      - PlatformReleases
      operationId: listPlatformReleases
      summary: List published platform releases and developer-downloadable artifacts
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Platform release catalog
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatformReleaseListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/platform/releases/{version}":
    get:
      tags:
      - PlatformReleases
      operationId: getPlatformRelease
      summary: Get a single published platform release manifest
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: version
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Platform release manifest
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatformRelease"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/platform/releases/{version}/artifacts/{artifact_id}/download":
    get:
      tags:
      - PlatformReleases
      operationId: downloadPlatformReleaseArtifact
      summary: Download a platform release artifact tarball
      description: Developer-facing artifacts are available to any authenticated user.
        Operator-only artifacts require the admin role.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: version
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: artifact_id
        in: path
        required: true
        schema:
          type: string
          enum:
          - cli
          - go-sdk
          - python-sdk
          - node-agent
          - node-agent-bootstrap
      responses:
        '200':
          description: Artifact archive
          content:
            application/gzip:
              schema:
                type: string
                format: binary
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/platform/releases/{version}/artifacts/{artifact_id}/pull-intent":
    post:
      tags:
      - PlatformReleases
      operationId: createPlatformReleaseArtifactPullIntent
      summary: Issue a wrapped short-lived pull intent for a platform release artifact
      description: Returns registry metadata and Vault-wrapped pull credentials. Developer-facing
        artifacts are available to any authenticated user. Operator-only artifacts
        require the admin role.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: version
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: artifact_id
        in: path
        required: true
        schema:
          type: string
          enum:
          - cli
          - go-sdk
          - python-sdk
          - node-agent
          - node-agent-bootstrap
      responses:
        '201':
          description: Platform release artifact pull intent issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ArtifactPullIntent"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/platform/dev-ca":
    get:
      tags:
      - PlatformReleases
      operationId: getPlatformDevCA
      summary: Get the current platform-control dev CA download metadata
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Platform-control dev CA metadata
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatformDevCA"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/platform/dev-ca/download":
    get:
      tags:
      - PlatformReleases
      operationId: downloadPlatformDevCA
      summary: Download the current platform-control dev CA certificate
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: PEM-encoded CA certificate
          content:
            application/x-x509-ca-cert:
              schema:
                type: string
                format: binary
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/apps/catalog/{app_slug}/versions/{version}/publish":
    post:
      tags:
      - AdminApps
      operationId: adminPublishAppCatalogVersion
      summary: Publish an app catalog version
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppSlugPath"
      - "$ref": "#/components/parameters/AppVersionPath"
      responses:
        '200':
          description: App catalog version published
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppCatalogVersion"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/apps/catalog/{app_slug}/versions/{version}/deprecate":
    post:
      tags:
      - AdminApps
      operationId: adminDeprecateAppCatalogVersion
      summary: Deprecate an app catalog version
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppSlugPath"
      - "$ref": "#/components/parameters/AppVersionPath"
      responses:
        '200':
          description: App catalog version deprecated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppCatalogVersion"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/apps/entitlements":
    get:
      tags:
      - Apps
      operationId: listProjectAppEntitlements
      summary: List app entitlements for a project
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      responses:
        '200':
          description: Project app entitlements
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppEntitlementListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/apps/entitlements/{app_slug}":
    put:
      tags:
      - Apps
      operationId: upsertProjectAppEntitlement
      summary: Enable/disable app entitlement and policy overrides for a project
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppSlugPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpsertAppEntitlementRequest"
      responses:
        '200':
          description: Updated project entitlement
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppEntitlement"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-artifacts":
    get:
      tags:
      - AppArtifacts
      operationId: listProjectAppArtifacts
      summary: List registered app artifacts for a project
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: app_slug
        in: query
        required: false
        schema:
          type: string
      - name: lifecycle_state
        in: query
        required: false
        schema:
          type: string
          enum:
          - published
          - promoted
          - deprecated
          - retired
      responses:
        '200':
          description: Project app artifacts
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifactListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - AppArtifacts
      operationId: registerProjectAppArtifact
      summary: Register a previously published app artifact digest with the control
        plane
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RegisterAppArtifactRequest"
      responses:
        '201':
          description: App artifact registered
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-artifacts/publish-intents":
    post:
      tags:
      - AppArtifacts
      operationId: createProjectAppArtifactPublishIntent
      summary: Issue a short-lived publish intent for direct artifact publication
        to the platform registry
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAppArtifactPublishIntentRequest"
      responses:
        '201':
          description: Publish intent issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifactPublishIntent"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/pull-intent":
    post:
      tags:
      - AppArtifacts
      operationId: createProjectAppArtifactPullIntent
      summary: Issue a wrapped short-lived pull intent for a project app artifact
      description: Returns registry metadata and Vault-wrapped pull credentials. Artifact
        bytes remain on the registry path; clients must not cache or persist the wrapped
        credential.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '201':
          description: App artifact pull intent issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ArtifactPullIntent"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/projects/{project_id}/app-instances":
    get:
      tags:
      - Apps
      operationId: listAppInstances
      summary: List app instances in a project
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - requested
          - deploying
          - running
          - stopping
          - stopped
          - starting
          - restarting
          - upgrading
          - rolling_back
          - failed
          - decommissioning
          - decommissioned
          - deleting
          - deleted
      responses:
        '200':
          description: App instances
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Apps
      operationId: createAppInstance
      summary: Request app instance deployment in a project
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAppInstanceRequest"
      responses:
        '202':
          description: App instance deployment accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/promote":
    post:
      tags:
      - AppArtifacts
      operationId: promoteProjectAppArtifact
      summary: Promote a registered app artifact to a named channel
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PromoteAppArtifactRequest"
      responses:
        '200':
          description: App artifact promoted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/verify":
    post:
      tags:
      - AppArtifacts
      operationId: verifyProjectAppArtifact
      summary: Mark a registered app artifact as verified
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '200':
          description: App artifact verified
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/revoke":
    post:
      tags:
      - AppArtifacts
      operationId: revokeProjectAppArtifact
      summary: Revoke trust for a registered app artifact
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '200':
          description: App artifact trust revoked
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/deprecate":
    post:
      tags:
      - AppArtifacts
      operationId: deprecateProjectAppArtifact
      summary: Deprecate a registered app artifact
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '200':
          description: App artifact deprecated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/retire":
    post:
      tags:
      - AppArtifacts
      operationId: retireProjectAppArtifact
      summary: Retire a registered app artifact from new use
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '200':
          description: App artifact retired
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}":
    get:
      tags:
      - Apps
      operationId: getAppInstance
      summary: Get app instance status and metadata
      description: |
        External app workers use this polling-compatible read surface to load the project-owned
        runtime object they are authorized to reconcile. Platform internals may use events, but
        app workers must treat this API as the stable runtime query contract.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '200':
          description: App instance
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/report":
    post:
      tags:
      - Apps
      operationId: reportAppInstance
      summary: Report adapter-owned status for an app instance without requiring a
        platform-internal worker transition
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReportAppInstanceRequest"
      responses:
        '200':
          description: App instance report accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - Apps
      operationId: deleteAppInstance
      summary: Request app instance decommission (legacy alias)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: App instance decommission accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/bootstrap-ssh/reconcile":
    post:
      tags:
      - Apps
      operationId: reconcileAppInstanceBootstrapSshTrust
      summary: Reconcile app-managed bootstrap SSH trust for an app instance onto
        a target allocation user
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReconcileAppInstanceBootstrapSshTrustRequest"
      responses:
        '202':
          description: Bootstrap SSH trust sync requested
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceBootstrapSshTrustState"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/members":
    get:
      tags:
      - Apps
      operationId: listAppInstanceMembers
      summary: List realized members for an app instance
      description: |
        List generic runtime members for an app-owned worker. Runtime-specific member semantics
        stay adapter-owned and are reported through the generic member envelope.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: component_key
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - requested
          - reconciling
          - ready
          - draining
          - deleting
          - failed
          - deleted
      responses:
        '200':
          description: App instance members
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMemberListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/members/{member_id}":
    get:
      tags:
      - Apps
      operationId: getAppInstanceMember
      summary: Get status and detail for an app-instance member
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/AppInstanceMemberIdPath"
      responses:
        '200':
          description: App instance member
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMember"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/members/{member_id}/report":
    post:
      tags:
      - Apps
      operationId: reportAppInstanceMember
      summary: Report adapter-owned status or detail for an app-instance member without
        requiring a member operation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/AppInstanceMemberIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReportAppInstanceMemberRequest"
      responses:
        '200':
          description: App instance member report accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMember"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/member-operations":
    get:
      tags:
      - Apps
      operationId: listAppInstanceMemberOperations
      summary: List generic member lifecycle operations for an app instance
      description: |
        Polling-compatible work queue for external app workers. App workers read accepted or
        in-progress operations here and report progress through the corresponding report route.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - accepted
          - in_progress
          - succeeded
          - failed
          - cancelled
      - name: component_key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: App instance member operations
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMemberOperationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Apps
      operationId: createAppInstanceMemberOperation
      summary: Request a generic member lifecycle operation for an app instance
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAppInstanceMemberOperationRequest"
      responses:
        '202':
          description: App instance member operation accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMemberOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/member-operations/{operation_id}":
    get:
      tags:
      - Apps
      operationId: getAppInstanceMemberOperation
      summary: Get status for an app-instance member operation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/AppInstanceMemberOperationIdPath"
      responses:
        '200':
          description: App instance member operation
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMemberOperation"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/member-operations/{operation_id}/report":
    post:
      tags:
      - Apps
      operationId: reportAppInstanceMemberOperation
      summary: Report adapter-owned progress or result for an app-instance member
        operation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/AppInstanceMemberOperationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReportAppInstanceMemberOperationRequest"
      responses:
        '200':
          description: App instance member operation report accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMemberOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/upgrade":
    post:
      tags:
      - Apps
      operationId: upgradeAppInstance
      summary: Request app instance upgrade
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpgradeAppInstanceRequest"
      responses:
        '202':
          description: App instance upgrade accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/runtime-secrets":
    post:
      tags:
      - Apps
      operationId: issueAppInstanceRuntimeSecret
      summary: Issue a wrapped runtime secret bundle for an app instance
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/IssueAppInstanceRuntimeSecretRequest"
      responses:
        '200':
          description: Wrapped runtime secret bundle
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceRuntimeSecretBundle"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/access":
    get:
      tags:
      - Apps
      operationId: getAppInstanceAccess
      summary: Get app instance access bundle
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '200':
          description: App instance access bundle
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceAccessBundle"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/rollback":
    post:
      tags:
      - Apps
      operationId: rollbackAppInstance
      summary: Request app instance rollback
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RollbackAppInstanceRequest"
      responses:
        '202':
          description: App instance rollback accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/stop":
    post:
      tags:
      - Apps
      operationId: stopAppInstance
      summary: Request app instance stop
      description: 'Requests a non-destructive stop of the app runtime. The app instance
        remains visible and can be started again later.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: App instance stop accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/start":
    post:
      tags:
      - Apps
      operationId: startAppInstance
      summary: Request app instance start
      description: Requests start for a previously stopped app instance.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: App instance start accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/restart":
    post:
      tags:
      - Apps
      operationId: restartAppInstance
      summary: Request app instance restart
      description: |
        Requests restart for a running or failed app instance without decommissioning it.
        Runtime backends that cannot define safe deterministic restart semantics, such as
        self-managed multi-member Kubernetes/RKE2, should reject this action and expose
        repair/reconcile operations instead.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: App instance restart accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/repair":
    post:
      tags:
      - Apps
      operationId: createAppInstanceRepairOperation
      summary: Request app runtime reconcile or repair
      description: |
        Creates an app-runtime repair operation for drift correction or safe runtime repair.
        This is the preferred action for Kubernetes/RKE2 instead of a generic restart because
        server, agent, and whole-runtime repair have different safety semantics.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAppInstanceRepairRequest"
      responses:
        '202':
          description: App repair operation accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceRepairOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/repair-operations":
    get:
      tags:
      - Apps
      operationId: listAppInstanceRepairOperations
      summary: List app runtime repair operations
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          "$ref": "#/components/schemas/AppInstanceRepairOperationStatus"
      responses:
        '200':
          description: App repair operations
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceRepairOperationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/repair-operations/{repair_operation_id}":
    get:
      tags:
      - Apps
      operationId: getAppInstanceRepairOperation
      summary: Get app runtime repair operation detail
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/AppInstanceRepairOperationIdPath"
      responses:
        '200':
          description: App repair operation
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceRepairOperation"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/repair-operations/{repair_operation_id}/report":
    post:
      tags:
      - Apps
      operationId: reportAppInstanceRepairOperation
      summary: Report app-owned progress for a repair operation
      description: |
        Polling-compatible report surface for app-owned workers. Workers report step-level
        progress so long-running Kubernetes/RKE2 repair operations do not appear stuck.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/AppInstanceRepairOperationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReportAppInstanceRepairOperationRequest"
      responses:
        '200':
          description: App repair operation report accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceRepairOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/decommission":
    post:
      tags:
      - Apps
      operationId: decommissionAppInstance
      summary: Request app instance decommission
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: App instance decommission accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/shared-runtime-attachments/{attachment_id}/worker-operations":
    post:
      tags:
      - Apps
      operationId: createProjectSharedRuntimeWorkerOperation
      summary: Request worker contribution for an attached tenant-shared app runtime
      description: |
        Allows an attached consumer project to request shared worker contribution through
        its own project-scoped attachment path. The platform resolves the backing
        tenant-owned shared runtime from the attachment and enforces attachment policy.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/SharedRuntimeAttachmentIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest"
      responses:
        '202':
          description: Shared runtime worker operation accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/shared-app-runtimes":
    get:
      tags:
      - Apps
      operationId: listSharedAppRuntimes
      summary: List tenant-owned shared app runtimes
      description: |
        List tenant-owned shared runtimes within one tenant. Delegated
        `shared_runtime_operator` tokens are intended for runtime-scoped reads;
        broader listing is primarily a user/operator surface.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - requested
          - deploying
          - running
          - upgrading
          - rolling_back
          - failed
          - deleting
          - deleted
      responses:
        '200':
          description: Tenant-owned shared app runtimes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Apps
      operationId: createSharedAppRuntime
      summary: Request tenant-owned shared app runtime deployment
      description: Create a tenant-owned shared runtime in requested state.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OrgIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSharedAppRuntimeRequest"
      responses:
        '202':
          description: Shared app runtime deployment accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntime"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}":
    get:
      tags:
      - Apps
      operationId: getSharedAppRuntime
      summary: Get tenant-owned shared app runtime status and metadata
      description: |
        Read one tenant-owned shared runtime. Intended machine actor is a delegated `shared_runtime_operator`
        token bound to the same `org_id` and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Shared app runtime
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntime"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    delete:
      tags:
      - Apps
      operationId: deleteSharedAppRuntime
      summary: Request deletion of a tenant-owned shared app runtime
      description: Request tenant-owned shared runtime deletion by transitioning it
        to deleting state.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Shared app runtime deletion accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntime"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/report":
    post:
      tags:
      - Apps
      operationId: reportSharedAppRuntime
      summary: Report tenant-owned shared app runtime lifecycle state
      description: |
        Report lifecycle progress for one tenant-owned shared runtime. Intended machine actor
        is a delegated `shared_runtime_operator` token bound to the same `org_id` and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReportSharedAppRuntimeRequest"
      responses:
        '200':
          description: Shared app runtime updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntime"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments":
    get:
      tags:
      - Apps
      operationId: listSharedAppRuntimeAttachments
      summary: List attached consumer projects for a tenant-owned shared app runtime
      description: |
        List consumer-project attachments for one tenant-owned shared runtime.
        Intended machine actor is a delegated `shared_runtime_operator`
        token bound to the same `org_id` and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Shared runtime attachments
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeAttachmentListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Apps
      operationId: createSharedAppRuntimeAttachment
      summary: Attach a consumer project to a tenant-owned shared app runtime
      description: Attach or update one consumer project relationship for a tenant-owned
        shared runtime.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSharedAppRuntimeAttachmentRequest"
      responses:
        '202':
          description: Shared runtime attachment accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeAttachment"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments/{attachment_id}":
    get:
      tags:
      - Apps
      operationId: getSharedAppRuntimeAttachment
      summary: Get one attached consumer project relationship
      description: |
        Read one shared runtime attachment. Intended machine actor is a delegated `shared_runtime_operator`
        token bound to the same `org_id` and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: attachment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Shared runtime attachment
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeAttachment"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Apps
      operationId: reportSharedAppRuntimeAttachment
      summary: Report attached project contribution state for a tenant-owned shared
        app runtime
      description: |
        Report attachment-scoped progress or contribution state for one shared runtime attachment.
        Intended machine actor is a delegated `shared_runtime_operator`
        token bound to the same `org_id` and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: attachment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReportSharedAppRuntimeAttachmentRequest"
      responses:
        '200':
          description: Shared runtime attachment updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeAttachment"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - Apps
      operationId: deleteSharedAppRuntimeAttachment
      summary: Detach a consumer project from a tenant-owned shared app runtime
      description: Detach a consumer project from one tenant-owned shared runtime.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OrgIdPath"
      - "$ref": "#/components/parameters/SharedRuntimeIdPath"
      - "$ref": "#/components/parameters/SharedRuntimeAttachmentIdPath"
      responses:
        '202':
          description: Shared runtime attachment deletion accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeAttachment"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/workers":
    get:
      tags:
      - Apps
      operationId: listSharedAppRuntimeWorkers
      summary: List workers for a tenant-owned shared app runtime
      description: |
        Runtime-query surface for tenant-shared external app workers. A delegated
        `shared_runtime_operator` token may read workers only for its bound `org_id`
        and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Shared runtime workers
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/workers/{worker_id}":
    get:
      tags:
      - Apps
      operationId: getSharedAppRuntimeWorker
      summary: Get one worker contribution for a tenant-owned shared app runtime
      description: |
        Runtime-query surface for one tenant-shared worker contribution. A delegated
        `shared_runtime_operator` token may read this resource only for its bound
        `org_id` and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: worker_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Shared runtime worker
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorker"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Apps
      operationId: reportSharedAppRuntimeWorker
      summary: Report one worker contribution for a tenant-owned shared app runtime
      description: |
        Report worker-scoped lifecycle progress for one shared runtime worker.
        Intended machine actor is a delegated `shared_runtime_operator`
        token bound to the same `org_id` and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: worker_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReportSharedAppRuntimeWorkerRequest"
      responses:
        '200':
          description: Shared runtime worker updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorker"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/worker-operations":
    get:
      tags:
      - Apps
      operationId: listSharedAppRuntimeWorkerOperations
      summary: List worker operations for a tenant-owned shared app runtime
      description: |
        Polling-compatible work queue for tenant-shared external app workers. A delegated
        `shared_runtime_operator` token reads pending operations here and reports progress
        through the corresponding operation report route.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Shared runtime worker operations
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Apps
      operationId: createSharedAppRuntimeWorkerOperation
      summary: Request a worker lifecycle change for a tenant-owned shared app runtime
      description: |
        Create an operator-visible worker lifecycle request for a tenant-owned shared runtime.
        Human tenant/project actors request operations; delegated app workers consume and
        report them through the runtime worker contract.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OrgIdPath"
      - name: shared_runtime_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest"
      responses:
        '202':
          description: Shared runtime worker operation accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/worker-operations/{operation_id}":
    get:
      tags:
      - Apps
      operationId: getSharedAppRuntimeWorkerOperation
      summary: Get one worker operation for a tenant-owned shared app runtime
      description: |
        Runtime-query surface for one tenant-shared worker lifecycle operation.
        Delegated app workers use this endpoint to recover operation state safely after
        restarts or polling gaps.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - "$ref": "#/components/parameters/SharedRuntimeIdPath"
      - "$ref": "#/components/parameters/SharedRuntimeWorkerOperationIdPath"
      responses:
        '200':
          description: Shared runtime worker operation
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Apps
      operationId: reportSharedAppRuntimeWorkerOperation
      summary: Report one worker operation for a tenant-owned shared app runtime
      description: |
        Report worker-operation progress for one shared runtime worker operation.
        Intended machine actor is a delegated `shared_runtime_operator`
        token bound to the same `org_id` and `shared_runtime_id`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - "$ref": "#/components/parameters/SharedRuntimeIdPath"
      - "$ref": "#/components/parameters/SharedRuntimeWorkerOperationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReportSharedAppRuntimeWorkerOperationRequest"
      responses:
        '200':
          description: Shared runtime worker operation updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/ssh-keys":
    get:
      tags:
      - SshKeys
      operationId: listSshKeys
      description: 'Lists registered SSH public keys in the caller''s active scope.
        Without `X-Project-ID`, this returns the caller''s personal keys. With `X-Project-ID`,
        this returns project-scoped keys for that project. Service-account callers
        must provide `X-Project-ID`.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Registered SSH public keys for the current personal or project
            scope
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SshPublicKeyListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - SshKeys
      operationId: createSshKey
      description: 'Registers an SSH public key in the caller''s active scope. Without
        `X-Project-ID`, this creates a personal key for the caller. With `X-Project-ID`,
        this creates a project-scoped key that can later be referenced by project-scoped
        automation such as service accounts. Project-scoped keys cannot be marked
        as default.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSshPublicKeyRequest"
      responses:
        '201':
          description: SSH public key created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateSshPublicKeyResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/ssh-keys/{key_id}":
    delete:
      tags:
      - SshKeys
      operationId: deleteSshKey
      description: 'Revokes a registered SSH public key in the caller''s active scope.
        Without `X-Project-ID`, this operates on the caller''s personal keys. With
        `X-Project-ID`, this operates on project-scoped keys for that project. Service-account
        callers must provide `X-Project-ID`.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SshKeyIdPath"
      responses:
        '200':
          description: SSH public key removed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/ssh-keys/{key_id}/default":
    put:
      tags:
      - SshKeys
      operationId: setDefaultSshKey
      description: Sets the caller's personal default SSH key for future allocations.
        Project-scoped keys are not eligible for default selection.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SshKeyIdPath"
      responses:
        '200':
          description: Default SSH key updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateSshPublicKeyResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/billing/balance":
    get:
      tags:
      - Billing
      operationId: getBillingBalance
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Balance
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  balance:
                    "$ref": "#/components/schemas/Money"
                required:
                - balance
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/billing/usage":
    get:
      tags:
      - Billing
      operationId: listBillingUsage
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: allocation_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: app_instance_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: usage_source
        in: query
        required: false
        schema:
          type: string
          enum:
          - allocation
          - app_runtime
      - "$ref": "#/components/parameters/BillingFrom"
      - "$ref": "#/components/parameters/BillingTo"
      - "$ref": "#/components/parameters/BillingUsageSort"
      responses:
        '200':
          description: Usage list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/UsageListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/billing/usage/csv":
    get:
      tags:
      - Billing
      operationId: exportBillingUsageCsv
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: allocation_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: app_instance_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: usage_source
        in: query
        required: false
        schema:
          type: string
          enum:
          - allocation
          - app_runtime
      - "$ref": "#/components/parameters/BillingFrom"
      - "$ref": "#/components/parameters/BillingTo"
      - "$ref": "#/components/parameters/BillingUsageSort"
      responses:
        '200':
          description: CSV export
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/billing/refunds":
    get:
      tags:
      - Billing
      operationId: listBillingRefunds
      summary: List caller refund requests and outcomes
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - accepted
          - completed
          - failed
      responses:
        '200':
          description: Refund requests
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RefundListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/payments/checkout-session":
    post:
      tags:
      - Payments
      operationId: createChargeSession
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateChargeSessionRequest"
      responses:
        '200':
          description: Checkout session URL
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SessionUrlResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/payments/customer-portal-session":
    post:
      tags:
      - Payments
      operationId: createCustomerPortalSession
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      responses:
        '200':
          description: Customer portal URL
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SessionUrlResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/payments/webhook":
    post:
      tags:
      - Payments
      operationId: stripeWebhook
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Webhook accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/skus":
    get:
      tags:
      - Catalog
      operationId: listSkus
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: SKU list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SkuListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/nodes":
    get:
      tags:
      - Nodes
      operationId: listNodeSummaries
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - online
          - offline
          - maintenance
      - name: region_code
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: User-facing node list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeSummaryListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/v3/shell/context":
    get:
      tags:
      - V3ReadModels
      operationId: getV3ShellContext
      summary: Get v3 shell context read model
      description: 'Returns the scoped shell context needed by the v3 product shell:
        available modes, tenant/project selectors, region selector, balance summary,
        and attention counts. The response is scoped to the authenticated user and
        may be Redis cached using user, tenant, project, role, and mode scope in the
        cache key.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - in: query
        name: mode
        required: false
        schema:
          "$ref": "#/components/schemas/V3ShellMode"
      responses:
        '200':
          description: V3 shell context
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3ShellContextResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/regions":
    get:
      tags:
      - V3ReadModels
      operationId: listV3Regions
      summary: List v3 shell regions
      description: 'Temporary v3 migration read model for the product shell region
        selector. This endpoint lets UI remove hardcoded region labels while the scheduler
        and capacity layers evolve toward explicit multi-region support.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: V3 region list
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3RegionListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/workloads":
    get:
      tags:
      - V3ReadModels
      operationId: listV3Workloads
      summary: List unified v3 workload workbench rows
      description: 'Returns one runtime workbench across raw compute allocations and
        app-backed workloads. This read model is the v3 replacement target for list
        pages that currently split allocations and app instances. It must enforce
        project scope before reading or caching rows.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - in: query
        name: status
        required: false
        schema:
          "$ref": "#/components/schemas/V3WorkloadStatus"
      - in: query
        name: kind
        required: false
        schema:
          "$ref": "#/components/schemas/V3WorkloadKind"
      - in: query
        name: search
        required: false
        schema:
          type: string
          maxLength: 120
      - in: query
        name: include_history
        required: false
        description: Include archived terminal workload rows such as released runtimes
          and expired recovery items. Default runtime lists omit history; explicit
          status filters are also treated as history queries.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Unified v3 workload list
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3WorkloadListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/workloads/{workload_id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3WorkloadDetail
      summary: Get unified v3 workload detail read model
      description: 'Returns the v3 workload detail shell data for a compute or app-backed
        runtime. Kind-specific connect, metrics, storage, and config data are returned
        as sanitized tab payloads owned by their source domains. Raw secrets and private
        keys must never be present in this read model.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/WorkloadIdPath"
      responses:
        '200':
          description: Unified v3 workload detail
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3WorkloadDetailResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/tasks":
    get:
      tags:
      - V3ReadModels
      operationId: listV3Tasks
      summary: List v3 task read-model rows
      description: 'Returns the project-scoped long-running operation workbench used
        after launch, release, restart, and app lifecycle submissions. The first production
        implementation is allocation-backed and normalizes allocation lifecycle state
        into a task shape; future domains can add task sources without changing the
        shell contract.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - in: query
        name: status
        required: false
        schema:
          "$ref": "#/components/schemas/V3TaskStatus"
      responses:
        '200':
          description: V3 task list
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3TaskListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/tasks/{task_id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3TaskDetail
      summary: Get v3 task detail read model
      description: 'Returns task header context plus a normalized timeline. For allocation
        tasks, the response enriches the synthetic lifecycle steps with the existing
        allocation timeline when available.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3TaskIdPath"
      responses:
        '200':
          description: V3 task detail
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3TaskDetailResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/compute":
    get:
      tags:
      - V3ReadModels
      operationId: getV3ComputeCatalog
      summary: Get v3 compute catalog read model
      description: 'Temporary v3 migration read model for the Compute shell group.
        Returns project-scoped launchable SKU summaries and compatible OS image hints
        for the compute catalog and launch wizard. Capacity values are user-safe posture
        hints and must not expose raw node inventory secrets.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - in: query
        name: shape
        required: false
        schema:
          "$ref": "#/components/schemas/V3ComputeCapacityShape"
      - in: query
        name: search
        required: false
        schema:
          type: string
          maxLength: 120
      - in: query
        name: region_code
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 compute catalog
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3ComputeCatalogResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/launch/compute/precheck":
    post:
      tags:
      - V3ReadModels
      operationId: precheckV3ComputeLaunch
      summary: Precheck v3 compute launch readiness
      description: 'Read-only launch readiness contract for the v3 compute wizard.
        It evaluates project scope, catalog selection, dependency presence, and safe
        capacity posture before the user submits a mutating allocation request. This
        endpoint is safe to retry and must not create allocations, credentials, buckets,
        or network policy objects.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3ComputeLaunchPrecheckRequest"
      responses:
        '200':
          description: V3 compute launch readiness
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3LaunchPrecheckResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/apps":
    get:
      tags:
      - V3ReadModels
      operationId: listV3Apps
      summary: List v3 managed app catalog rows
      description: 'Temporary v3 migration read model for the Apps shell group. Returns
        the catalog, featured rows, entitlement state, dependency hints, and launch
        links used by the v3 app catalog. It is page-shaped and may later graduate
        into domain-owned app catalog resources.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - in: query
        name: category
        required: false
        schema:
          type: string
          maxLength: 80
      - in: query
        name: search
        required: false
        schema:
          type: string
          maxLength: 120
      responses:
        '200':
          description: V3 managed app catalog
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AppCatalogResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/apps/{app_slug}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3AppDetail
      summary: Get v3 managed app detail read model
      description: 'Returns the app detail read model used by the v3 catalog detail
        and app launch entry. Secrets, signed pull credentials, service-account tokens,
        and provider credentials must never be present in this response.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AppSlugPath"
      responses:
        '200':
          description: V3 managed app detail
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AppDetailResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/launch/apps/{app_slug}/precheck":
    post:
      tags:
      - V3ReadModels
      operationId: precheckV3AppLaunch
      summary: Precheck v3 app launch readiness
      description: 'Read-only launch readiness contract for the v3 app wizard. It
        evaluates project entitlement, version availability, dependency presence,
        and basic runtime intent before the user submits a mutating app-instance request.
        This endpoint is safe to retry and must not create app instances, service
        accounts, credentials, buckets, or network policy objects.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppSlugPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3AppLaunchPrecheckRequest"
      responses:
        '200':
          description: V3 app launch readiness
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3LaunchPrecheckResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/storage":
    get:
      tags:
      - V3ReadModels
      operationId: listV3StorageBuckets
      summary: List v3 storage workbench bucket rows
      description: 'Temporary v3 migration read model for the Storage shell group.
        Returns project-scoped bucket rows with usage, mount, access, lifecycle, and
        attention flags. Responses must not include raw object-store credentials,
        signed URLs, provider secrets, or private key material.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - in: query
        name: purpose
        required: false
        schema:
          "$ref": "#/components/schemas/V3StorageBucketPurpose"
      - in: query
        name: search
        required: false
        schema:
          type: string
          maxLength: 120
      responses:
        '200':
          description: V3 storage bucket workbench list
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageBucketListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - V3Storage
      operationId: createV3StorageBucket
      summary: Create a v3 storage bucket
      description: Creates a project-scoped bucket through the currently configured
        storage provider. The response is provider-neutral and never returns provider
        credentials, mount secrets, signed URLs, or raw backend identifiers. Requires
        an idempotency key.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3StorageBucketCreateRequest"
      responses:
        '201':
          description: V3 storage bucket created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageBucketCreateResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/storage/{bucket_id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3StorageBucketDetail
      summary: Get v3 storage bucket detail read model
      description: 'Temporary v3 migration read model for a bucket detail page. The
        payload is presentation-shaped and sanitized: it may include object key previews,
        mount summaries, lifecycle posture, and access audiences, but never credential
        material, signed download/upload URLs, or raw provider config.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      responses:
        '200':
          description: V3 storage bucket detail
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageBucketDetailResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      tags:
      - V3Storage
      operationId: updateV3StorageBucket
      summary: Update provider-neutral bucket lifecycle metadata
      description: Updates bucket policy metadata such as purpose, quota, retention,
        access protocol, and access audience. Provider credentials and backend-specific
        identifiers are never returned. Audited as `storage.bucket.update`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3StorageBucketUpdateRequest"
      responses:
        '200':
          description: V3 storage bucket updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageBucketMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    delete:
      tags:
      - V3Storage
      operationId: deleteV3StorageBucket
      summary: Delete a storage bucket when no active grants or attachments remain
      description: Deletes provider-local data and marks the bucket deleted only after
        active grants and attachments have been removed. Audited as `storage.bucket.delete`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      responses:
        '204':
          description: V3 storage bucket deleted
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/storage/{bucket_id}/archive":
    post:
      tags:
      - V3Storage
      operationId: archiveV3StorageBucket
      summary: Archive a storage bucket without deleting provider data
      description: Moves the bucket lifecycle state to deleting for operator follow-up
        while preserving provider data. Requires no active grants or attachments.
        Audited as `storage.bucket.archive`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3StorageBucketArchiveRequest"
      responses:
        '200':
          description: V3 storage bucket archived
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageBucketMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/storage/{bucket_id}/attachments":
    get:
      tags:
      - V3Storage
      operationId: listV3StorageAttachments
      summary: List runtime storage attachments for a bucket
      description: 'Lists provider-neutral storage attachment state for one project
        storage namespace. This is a read model over Temporal/node-agent/provider
        state and never returns provider credentials, raw mount commands, or backend
        cluster identifiers.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      responses:
        '200':
          description: Storage attachments
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageAttachmentListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3Storage
      operationId: createV3StorageAttachment
      summary: Request storage attachment to a workload or allocation
      description: 'Persists an idempotent storage attachment intent and starts the
        Temporal attach workflow. The response returns the attachment state; it does
        not wait for the node-agent mount to complete. Audited as `storage.attachment.request`.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3StorageAttachmentCreateRequest"
      responses:
        '202':
          description: Storage attachment workflow accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageAttachmentResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/storage/{bucket_id}/attachments/{attachment_id}":
    get:
      tags:
      - V3Storage
      operationId: getV3StorageAttachment
      summary: Get one storage attachment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      - "$ref": "#/components/parameters/V3StorageAttachmentIdPath"
      responses:
        '200':
          description: Storage attachment
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageAttachmentResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    delete:
      tags:
      - V3Storage
      operationId: detachV3StorageAttachment
      summary: Request storage attachment detach
      description: 'Starts or signals the Temporal detach workflow. Persistent storage
        is never deleted by this endpoint. Audited as `storage.attachment.detach`.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      - "$ref": "#/components/parameters/V3StorageAttachmentIdPath"
      responses:
        '202':
          description: Storage detach workflow accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageAttachmentResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/access":
    get:
      tags:
      - V3ReadModels
      operationId: getV3AccessOverview
      summary: Get v3 access posture overview read model
      description: 'Temporary v3 migration read model for the Access shell group.
        Returns project-scoped counts and drift signals across memberships, service
        accounts, credentials, and entitlements. Raw secrets, private keys, access
        tokens, refresh tokens, and provider credentials must never be returned.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: V3 access overview
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccessOverviewResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/access/memberships":
    get:
      tags:
      - V3ReadModels
      operationId: listV3AccessMemberships
      summary: List v3 access membership rows
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 access memberships
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccessMembershipListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/access/memberships/users/{user_id}/bind":
    post:
      tags:
      - V3ReadModels
      operationId: bindV3AccessUserMembership
      summary: Bind a user to the caller tenant and project from the v3 access workbench
      description: Uses the existing tenant-admin membership authority and audit path.
        The request body supplies the project role, tenant role, and project_id to
        bind.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/UserIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TenantBindUserMembershipRequest"
      responses:
        '200':
          description: Membership bound
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminBindUserMembershipResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/access/memberships/users/{user_id}/remove":
    post:
      tags:
      - V3ReadModels
      operationId: removeV3AccessUserMembership
      summary: Remove a user's V3 access membership
      description: |
        Soft-deletes the target user's project membership or tenant-scoped memberships
        using the tenant-admin authority. Audited as `tenant.user.membership.remove`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/UserIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3RemoveAccessMembershipRequest"
      responses:
        '200':
          description: Membership removal result
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3RemoveAccessMembershipResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/access/service-accounts":
    get:
      tags:
      - V3ReadModels
      operationId: listV3AccessServiceAccounts
      summary: List v3 access service-account rows
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 access service accounts
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccessServiceAccountListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - V3ReadModels
      operationId: createV3AccessServiceAccount
      summary: Create a project-scoped service account from the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateServiceAccountRequest"
      responses:
        '201':
          description: Service account created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateServiceAccountResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/access/service-accounts/{service_account_id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3AccessServiceAccount
      summary: Get project-scoped service account detail from the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/ServiceAccountIdPath"
      responses:
        '200':
          description: Service account detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServiceAccount"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    delete:
      tags:
      - V3ReadModels
      operationId: deleteV3AccessServiceAccount
      summary: Soft-delete a project-scoped service account from the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ServiceAccountIdPath"
      responses:
        '200':
          description: Service account soft-deleted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServiceAccount"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/access/service-accounts/{service_account_id}/disable":
    post:
      tags:
      - V3ReadModels
      operationId: disableV3AccessServiceAccount
      summary: Disable a project-scoped service account from the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ServiceAccountIdPath"
      responses:
        '200':
          description: Service account disabled
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServiceAccount"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/access/service-accounts/{service_account_id}/rotate-key":
    post:
      tags:
      - V3ReadModels
      operationId: rotateV3AccessServiceAccountKey
      summary: Rotate a project-scoped service-account credential from the v3 access
        workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ServiceAccountIdPath"
      responses:
        '200':
          description: Service account credential rotated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RotateServiceAccountCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/access/credentials":
    get:
      tags:
      - V3ReadModels
      operationId: listV3AccessCredentials
      summary: List v3 access credential map rows
      description: 'Returns credential posture metadata only. The response may include
        labels, fingerprints, status, ownership, and expiry metadata, but never raw
        public key payloads, private keys, token material, or provider secrets.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 access credentials
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccessCredentialListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - V3ReadModels
      operationId: createV3AccessCredential
      summary: Create a project-scoped access credential from the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectCreateAccessCredentialRequest"
      responses:
        '201':
          description: Project access credential created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/access/credentials/{credential_id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3AccessCredential
      summary: Get project-scoped access credential metadata from the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      responses:
        '200':
          description: Project access credential metadata
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      tags:
      - V3ReadModels
      operationId: updateV3AccessCredential
      summary: Update project-scoped access credential metadata from the v3 access
        workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectUpdateAccessCredentialRequest"
      responses:
        '200':
          description: Project access credential updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    delete:
      tags:
      - V3ReadModels
      operationId: deleteV3AccessCredential
      summary: Delete a project-scoped access credential from the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      responses:
        '204':
          description: Project access credential deleted
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/access/credentials/{credential_id}/rotate":
    post:
      tags:
      - V3ReadModels
      operationId: rotateV3AccessCredential
      summary: Rotate a project-scoped access credential from the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectRotateAccessCredentialRequest"
      responses:
        '200':
          description: Project access credential rotated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/access/credentials/{credential_id}/deliver":
    post:
      tags:
      - V3ReadModels
      operationId: deliverV3AccessCredential
      summary: Retrieve secure delivery for a project-scoped access credential from
        the v3 access workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectDeliverAccessCredentialRequest"
      responses:
        '200':
          description: Access credential delivery prepared
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectDeliverAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/access/entitlements":
    get:
      tags:
      - V3ReadModels
      operationId: listV3AccessEntitlements
      summary: List v3 access entitlement rows
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - in: query
        name: kind
        required: false
        schema:
          type: string
          enum:
          - app
          - sku
          - region
      responses:
        '200':
          description: V3 access entitlements
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccessEntitlementListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/access/entitlements/{app_slug}":
    put:
      tags:
      - V3ReadModels
      operationId: upsertV3AccessAppEntitlement
      summary: Enable or disable an app entitlement for the active v3 project
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppSlugPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpsertAppEntitlementRequest"
      responses:
        '200':
          description: Project app entitlement updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppEntitlement"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/access/audit":
    get:
      tags:
      - V3ReadModels
      operationId: listV3AccessAuditEvents
      summary: List v3 access audit events
      description: 'Returns access-family audit events for membership, service-account,
        credential, entitlement, identity, and connectivity mutations. This is a scoped
        read model over audit_logs and must not return credential material, token
        payloads, private keys, provider secrets, or raw request bodies.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 access audit events
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccessAuditEventListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/account":
    get:
      tags:
      - V3ReadModels
      operationId: getV3AccountOverview
      summary: Get v3 account overview read model
      description: 'Temporary v3 migration read model for the Account shell group.
        Returns personal profile, linked identity counts, personal credential counts,
        active session count, and personal attention items. Raw tokens, refresh tokens,
        private keys, password hashes, and provider secrets must never be returned.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: V3 account overview
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccountOverviewResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/account/profile":
    get:
      tags:
      - V3ReadModels
      operationId: getV3AccountProfile
      summary: Get v3 account profile and linked identities
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: V3 account profile
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccountProfileResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/account/security":
    get:
      tags:
      - V3ReadModels
      operationId: getV3AccountSecurity
      summary: Get v3 account personal security posture
      description: 'Returns metadata for personal SSH/API credentials and MFA posture.
        This endpoint owns personal records; Access endpoints may reference the same
        records only as a permission map. No private keys or API tokens are returned.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: V3 account security posture
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccountSecurityResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/account/security/ssh-keys":
    post:
      tags:
      - V3ReadModels
      operationId: createV3AccountSshKey
      summary: Register a personal SSH key from the v3 account security workbench
      description: Without `X-Project-ID`, this creates a personal SSH key for the
        caller.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSshPublicKeyRequest"
      responses:
        '201':
          description: SSH public key created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateSshPublicKeyResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
    get:
      tags:
      - V3ReadModels
      operationId: listV3AccountSshKeys
      summary: List personal SSH keys for launch and account security workflows
      description: Returns caller-owned SSH public keys through the V3 account namespace.
        No private key material is accepted or returned.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: SSH public keys
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SshPublicKeyListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/account/security/ssh-keys/{key_id}":
    delete:
      tags:
      - V3ReadModels
      operationId: deleteV3AccountSshKey
      summary: Revoke a personal SSH key from the v3 account security workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SshKeyIdPath"
      responses:
        '200':
          description: SSH public key removed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/account/security/ssh-keys/{key_id}/default":
    put:
      tags:
      - V3ReadModels
      operationId: setDefaultV3AccountSshKey
      summary: Set the caller's personal default SSH key from the v3 account security
        workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SshKeyIdPath"
      responses:
        '200':
          description: Default SSH key updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateSshPublicKeyResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/account/sessions":
    get:
      tags:
      - V3ReadModels
      operationId: listV3AccountSessions
      summary: List v3 account sessions
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: V3 account sessions
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccountSessionListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/account/sessions/{session_id}/revoke":
    post:
      tags:
      - V3ReadModels
      operationId: revokeV3AccountSession
      summary: Revoke a tracked v3 account session
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3AccountSessionRevokeRequest"
      responses:
        '200':
          description: Account session revoked
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccountSessionRevokeResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/account/sessions/revoke-others":
    post:
      tags:
      - V3ReadModels
      operationId: revokeOtherV3AccountSessions
      summary: Revoke every tracked v3 account session except the current session
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3AccountSessionRevokeRequest"
      responses:
        '200':
          description: Other account sessions revoked
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccountSessionRevokeResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/allocations":
    get:
      tags:
      - Allocations
      operationId: listAllocations
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
      responses:
        '200':
          description: Allocation list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
    post:
      tags:
      - Allocations
      operationId: createAllocation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAllocationRequest"
      responses:
        '201':
          description: Allocation created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateAllocationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/allocations/limits":
    get:
      tags:
      - Allocations
      operationId: getAllocationLimits
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: Effective per-user allocation concurrency limits for the current
            scope
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationLimits"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/runtime-bundles":
    get:
      tags:
      - Allocations
      operationId: listManagedRuntimeBundles
      summary: List platform-managed runtime bundles
      description: |
        Lists platform-owned runtime bundles that can be layered on top of a raw
        allocation. Runtime bundles describe supported install paths and activation
        hints; arbitrary packages installed by SSH users remain outside platform
        ownership.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - deprecated
          - disabled
      responses:
        '200':
          description: Managed runtime bundles
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ManagedRuntimeBundleListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/allocations/{allocation_id}/runtime-bundles":
    get:
      tags:
      - Allocations
      operationId: listAllocationRuntimeBundles
      summary: List managed runtime bundle state for an allocation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '200':
          description: Allocation runtime bundle state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationRuntimeBundleListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Allocations
      operationId: applyAllocationRuntimeBundle
      summary: Apply or change a managed runtime bundle on an allocation
      description: |
        Records the desired managed runtime bundle for an allocation. Active
        allocations receive a bounded node-agent task that writes a platform-owned
        runtime environment descriptor under /etc/gpuaas/runtime. This endpoint
        does not manage arbitrary user-installed packages.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ApplyAllocationRuntimeBundleRequest"
      responses:
        '202':
          description: Runtime bundle apply recorded
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ApplyAllocationRuntimeBundleResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/allocations/{allocation_id}":
    get:
      tags:
      - Allocations
      operationId: getAllocationById
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '200':
          description: Allocation detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Allocation"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/allocations/{allocation_id}/timeline":
    get:
      tags:
      - Allocations
      operationId: getAllocationTimeline
      summary: Get sanitized provisioning and release timeline for an allocation
      description: 'Returns allocation state milestones, durable placement claims,
        and node-agent task progress for the allocation. Raw task params and output
        are intentionally omitted because they can contain infrastructure-only or
        credential-like material.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AllocationIdPath"
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: Maximum number of recent timeline items to return.
      - in: query
        name: cursor
        schema:
          type: string
        description: Opaque cursor returned by the previous page.
      responses:
        '200':
          description: Allocation task timeline
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationTimelineResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/allocations":
    get:
      tags:
      - Allocations
      operationId: listProjectAllocations
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
      responses:
        '200':
          description: Project allocation list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/projects/{project_id}/allocations/{allocation_id}":
    get:
      tags:
      - Allocations
      operationId: getProjectAllocationById
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '200':
          description: Project allocation detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Allocation"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/allocation-groups":
    get:
      tags:
      - AllocationGroups
      operationId: listProjectAllocationGroups
      summary: List allocation groups in a project
      description: |
        Lists project-scoped parent resources that group normal single-node allocations.
        Member allocations remain the source of placement, connection, billing, and release truth.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          "$ref": "#/components/schemas/AllocationGroupStatus"
      - name: group_kind
        in: query
        required: false
        schema:
          "$ref": "#/components/schemas/AllocationGroupKind"
      responses:
        '200':
          description: Project allocation groups
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationGroupListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - AllocationGroups
      operationId: createProjectAllocationGroup
      summary: Request a grouped set of normal allocations
      description: |
        Creates a project-scoped allocation-group parent and requests member allocations.
        Each member is a normal allocation with its own lifecycle, billing window, and connection target.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAllocationGroupRequest"
      responses:
        '202':
          description: Allocation group request accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateAllocationGroupResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/projects/{project_id}/allocation-groups/{allocation_group_id}":
    get:
      tags:
      - AllocationGroups
      operationId: getProjectAllocationGroup
      summary: Get allocation group detail
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AllocationGroupIdPath"
      responses:
        '200':
          description: Allocation group detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationGroup"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/allocation-groups/{allocation_group_id}/release":
    post:
      tags:
      - AllocationGroups
      operationId: releaseProjectAllocationGroup
      summary: Request release for member allocations in a group
      description: |
        Records idempotent group release intent and fans out normal allocation release requests.
        Member allocations keep their own release state and release_failed handling.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AllocationGroupIdPath"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReleaseAllocationGroupRequest"
      responses:
        '202':
          description: Allocation group release accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ReleaseAllocationGroupResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/orgs/{org_id}/allocations":
    get:
      tags:
      - Allocations
      operationId: listOrgAllocations
      description: |
        List tenant-scoped allocations within one tenant. Delegated `shared_runtime_operator`
        tokens are allowed only for runtime-bounded control-plane allocation reads; handlers
        further narrow results to the requesting shared runtime placement.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
      responses:
        '200':
          description: Org allocation list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/orgs/{org_id}/allocations/{allocation_id}":
    get:
      tags:
      - Allocations
      operationId: getOrgAllocationById
      description: |
        Read one tenant-scoped allocation. Delegated `shared_runtime_operator` tokens are
        allowed only when the requested allocation is referenced by the bound shared runtime placement.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '200':
          description: Org allocation detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Allocation"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/allocations/{allocation_id}/release":
    post:
      tags:
      - Allocations
      operationId: releaseAllocation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '202':
          description: Release accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ReleaseAllocationResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/allocations/{allocation_id}/restart":
    post:
      tags:
      - Allocations
      operationId: restartAllocation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '202':
          description: Restart accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RestartAllocationResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/allocations/{allocation_id}/metrics":
    get:
      tags:
      - Allocations
      operationId: getAllocationMetrics
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '200':
          description: Live node metrics for this allocation
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationMetricsResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/allocations/{allocation_id}/metrics/timeseries":
    get:
      tags:
      - Allocations
      operationId: getAllocationMetricsTimeseries
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AllocationIdPath"
      - name: window_seconds
        in: query
        required: false
        schema:
          type: integer
          minimum: 60
          maximum: 86400
          default: 900
      - name: points
        in: query
        required: false
        schema:
          type: integer
          minimum: 10
          maximum: 240
          default: 60
      responses:
        '200':
          description: Time-series node metrics for this allocation
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationMetricsTimeseriesResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/allocations/{allocation_id}/terminal-token":
    post:
      tags:
      - Allocations
      operationId: createTerminalToken
      summary: Mint a short-lived single-use terminal session token for a WebSocket
        connection
      description: 'Non-idempotent by design. Each successful call issues a new single-use
        terminal token.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AllocationIdPath"
      - "$ref": "#/components/parameters/IdempotencyKey"
      responses:
        '200':
          description: Terminal token issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TerminalTokenResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          description: Allocation is not in active state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
  "/api/v1/allocations/{allocation_id}/ssh-keys":
    put:
      tags:
      - Allocations
      operationId: setAllocationSshKeys
      summary: Replace the registered SSH key set for an allocation
      description: 'Replaces the allocation''s attached registered SSH key IDs. The
        referenced keys must already be registered for the allocation owner. When
        the allocation is active, the control plane also queues a bounded node-agent
        task to rewrite the existing allocation runtime user''s `~/.ssh/authorized_keys`
        file with the resolved public keys. This endpoint never creates a new runtime
        user and never accepts raw public key material directly.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SetAllocationSshKeysRequest"
      responses:
        '200':
          description: Allocation SSH keys updated; active allocations will also synchronize
            the runtime user's authorized_keys set asynchronously
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Allocation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/allocations/{allocation_id}/access-grants":
    get:
      tags:
      - Allocations
      operationId: listAllocationAccessGrants
      summary: List project-member SSH access grants for an allocation
      description: 'Lists explicit project-member SSH grants for the allocation in
        the active project context. Grants are separate from the allocation owner''s
        registered SSH key set and are used for live handoff without sharing private
        keys.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '200':
          description: Allocation access grants
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationAccessGrantListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - Allocations
      operationId: createAllocationAccessGrant
      summary: Grant a project member SSH access to an allocation
      description: 'Creates or updates an active allocation SSH access grant for a
        project member. The grantee must already be a member of the allocation''s
        project and the SSH key must be the grantee''s personal registered key. Allocation
        owners and project/tenant admins can grant access. Active allocations queue
        a bounded node-agent task that rewrites the existing allocation runtime user''s
        authorized_keys set with owner keys plus active grants.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAllocationAccessGrantRequest"
      responses:
        '201':
          description: Allocation access grant created or updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateAllocationAccessGrantResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/allocations/{allocation_id}/access-grants/{grant_id}":
    delete:
      tags:
      - Allocations
      operationId: revokeAllocationAccessGrant
      summary: Revoke a project-member SSH access grant
      description: Revokes an active allocation SSH access grant. The allocation owner,
        project/tenant admins, or the grantee can revoke. Active allocations queue
        a bounded node-agent task to remove the grantee key from the runtime user's
        authorized_keys set.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      - name: grant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Allocation access grant revoked
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RevokeAllocationAccessGrantResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/storage/list":
    get:
      tags:
      - Storage
      operationId: listStorage
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - name: path
        in: query
        required: false
        schema:
          type: string
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Storage list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/StorageListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/storage/download":
    get:
      tags:
      - Storage
      operationId: downloadStorageObject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - name: path
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: File download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/storage/upload":
    put:
      tags:
      - Storage
      operationId: uploadStorageObject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: path
        in: query
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Upload result
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/storage/mkdir":
    post:
      tags:
      - Storage
      operationId: createStorageDirectory
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StorageMkdirRequest"
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/storage/rename":
    post:
      tags:
      - Storage
      operationId: renameStorageObject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StorageRenameRequest"
      responses:
        '200':
          description: Renamed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/storage/delete":
    delete:
      tags:
      - Storage
      operationId: deleteStorageObject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: path
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/service-accounts":
    get:
      tags:
      - ServiceAccounts
      operationId: listServiceAccounts
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Service account list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServiceAccountListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - ServiceAccounts
      operationId: createServiceAccount
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateServiceAccountRequest"
      responses:
        '201':
          description: Service account created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateServiceAccountResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/projects/{project_id}/service-accounts/{service_account_id}/disable":
    post:
      tags:
      - ServiceAccounts
      operationId: disableServiceAccount
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/ServiceAccountIdPath"
      responses:
        '200':
          description: Service account disabled
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServiceAccount"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/service-accounts/{service_account_id}/rotate-key":
    post:
      tags:
      - ServiceAccounts
      operationId: rotateServiceAccountCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/ServiceAccountIdPath"
      responses:
        '200':
          description: Service account key rotated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RotateServiceAccountCredentialResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/service-accounts/{service_account_id}":
    get:
      tags:
      - ServiceAccounts
      operationId: getServiceAccount
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/ServiceAccountIdPath"
      responses:
        '200':
          description: Service account detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServiceAccount"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    delete:
      tags:
      - ServiceAccounts
      operationId: deleteServiceAccount
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/ServiceAccountIdPath"
      responses:
        '200':
          description: Service account soft-deleted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServiceAccount"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/access-credentials":
    get:
      tags:
      - ProjectAccessCredentials
      operationId: listProjectAccessCredentials
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Project-scoped access credentials
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectAccessCredentialListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - ProjectAccessCredentials
      operationId: createProjectAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectCreateAccessCredentialRequest"
      responses:
        '201':
          description: Project access credential created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/projects/{project_id}/access-credentials/{credential_id}":
    get:
      tags:
      - ProjectAccessCredentials
      operationId: getProjectAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      responses:
        '200':
          description: Project access credential metadata
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      tags:
      - ProjectAccessCredentials
      operationId: updateProjectAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectUpdateAccessCredentialRequest"
      responses:
        '200':
          description: Project access credential updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    delete:
      tags:
      - ProjectAccessCredentials
      operationId: deleteProjectAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      responses:
        '204':
          description: Project access credential deleted
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/projects/{project_id}/access-credentials/{credential_id}/rotate":
    post:
      tags:
      - ProjectAccessCredentials
      operationId: rotateProjectAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectRotateAccessCredentialRequest"
      responses:
        '200':
          description: Project access credential rotated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/projects/{project_id}/access-credentials/{credential_id}/deliver":
    post:
      tags:
      - ProjectAccessCredentials
      operationId: deliverProjectAccessCredential
      summary: Retrieve secure delivery for a project-scoped access credential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProjectDeliverAccessCredentialRequest"
      responses:
        '200':
          description: Access credential delivery prepared
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProjectDeliverAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/auth/service-account/token":
    post:
      tags:
      - Auth
      operationId: createServiceAccountToken
      summary: Mint short-lived access token for a project-scoped service account
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ServiceAccountTokenRequest"
      responses:
        '200':
          description: Service account token issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServiceAccountTokenResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/auth/shared-runtime-operator/token":
    post:
      tags:
      - Auth
      operationId: createSharedRuntimeOperatorToken
      summary: Mint short-lived access token for a delegated tenant-shared runtime
        operator identity
      description: |
        Issue a delegated machine token bound to a single tenant-owned shared
        runtime. Intended claim shape is `SharedRuntimeOperatorTokenClaims`.
      security: []
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SharedRuntimeOperatorTokenRequest"
      responses:
        '200':
          description: Shared runtime operator token issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedRuntimeOperatorTokenResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/overview":
    get:
      tags:
      - AdminUsers
      operationId: adminGetOverview
      summary: Aggregated admin dashboard counters
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Admin overview counters
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminOverviewResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/ops/overview":
    get:
      tags:
      - AdminOps
      operationId: adminGetOpsOverview
      summary: Aggregated operational telemetry summary for admin operations dashboard
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Ops overview snapshot
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminOpsOverviewResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/runtime/metadata":
    get:
      tags:
      - AdminOps
      operationId: adminGetRuntimeMetadata
      summary: Live runtime metadata for platform-control services
      description: |
        Returns the runtime image/build/deployment metadata visible from the
        running API process. The first slice reports gpuaas-api itself; broader
        multi-service discovery can be added without changing the item shape.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Runtime metadata snapshot
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminRuntimeMetadataResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/telemetry/fleet":
    get:
      tags:
      - AdminOps
      operationId: adminGetFleetTelemetry
      summary: Admin telemetry fleet rollups for CPU/GPU/memory/storage with tenant/project
        drill-down
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: range
        in: query
        required: false
        schema:
          type: string
          enum:
          - 15m
          - 1h
          - 6h
          - 24h
          default: 1h
        description: Telemetry window range.
      - name: points
        in: query
        required: false
        schema:
          type: integer
          minimum: 10
          maximum: 240
          default: 60
        description: Number of samples requested in each returned time series.
      responses:
        '200':
          description: Fleet telemetry snapshot
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminFleetTelemetryResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/outbox/failed":
    get:
      tags:
      - AdminOps
      operationId: adminListFailedOutboxEvents
      summary: List failed outbox events (historical DLQ backlog)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Failed outbox events
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminOutboxFailedListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/outbox/{event_id}/requeue":
    post:
      tags:
      - AdminOps
      operationId: adminRequeueOutboxEvent
      summary: Requeue a failed outbox event back to pending
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Outbox event requeued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminOutboxMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/outbox/{event_id}/discard":
    post:
      tags:
      - AdminOps
      operationId: adminDiscardOutboxEvent
      summary: Discard a failed outbox event from backlog (audited)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Outbox event discarded
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminOutboxMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/dlq/messages":
    get:
      tags:
      - AdminOps
      operationId: adminListDLQMessages
      summary: List DLQ stream messages for operator triage
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: subject_prefix
        in: query
        required: false
        schema:
          type: string
        description: Optional DLQ subject prefix filter (for example dlq.provisioning.).
      responses:
        '200':
          description: DLQ messages page
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminDLQMessageListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/dlq/messages/{stream_seq}/requeue":
    post:
      tags:
      - AdminOps
      operationId: adminRequeueDLQMessage
      summary: Requeue a DLQ message to its original subject
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: stream_seq
        in: path
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
      responses:
        '200':
          description: DLQ message requeued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminDLQMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/dlq/messages/{stream_seq}/discard":
    post:
      tags:
      - AdminOps
      operationId: adminDiscardDLQMessage
      summary: Discard a DLQ message by stream sequence (audited)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: stream_seq
        in: path
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
      responses:
        '200':
          description: DLQ message discarded
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminDLQMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/runbooks":
    get:
      tags:
      - AdminOps
      operationId: adminListRunbooks
      summary: List operational runbooks metadata for admin ops dashboards
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Runbook metadata list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminRunbookListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/runbooks/{runbook_id}":
    get:
      tags:
      - AdminOps
      operationId: adminGetRunbook
      summary: Get single operational runbook metadata by stable runbook ID
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: runbook_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Runbook metadata
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminRunbook"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/users":
    get:
      tags:
      - AdminUsers
      operationId: adminListUsers
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Users
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      "$ref": "#/components/schemas/UserWithBalance"
                  pagination:
                    "$ref": "#/components/schemas/Pagination"
                required:
                - items
                - pagination
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - AdminUsers
      operationId: adminCreateUser
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateUserRequest"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminCreateUserResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/users/{user_id}/balance":
    post:
      tags:
      - AdminUsers
      operationId: adminAdjustBalance
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/UserIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminAdjustBalanceRequest"
      responses:
        '200':
          description: Adjusted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/users/{user_id}/platform-roles":
    get:
      tags:
      - AdminRoles
      operationId: adminListUserPlatformRoles
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/UserIdPath"
      responses:
        '200':
          description: Active platform role bindings for a user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminUserPlatformRoleListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - AdminRoles
      operationId: adminBindUserPlatformRole
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/UserIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminBindUserPlatformRoleRequest"
      responses:
        '200':
          description: Role bound (idempotent)
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminUserPlatformRoleMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/users/{user_id}/platform-roles/{role}":
    delete:
      tags:
      - AdminRoles
      operationId: adminRevokeUserPlatformRole
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/UserIdPath"
      - "$ref": "#/components/parameters/PlatformRolePath"
      responses:
        '200':
          description: Role revoked (idempotent)
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminUserPlatformRoleMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/access-credentials":
    get:
      tags:
      - AdminAccessCredentials
      operationId: adminListAccessCredentials
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Access credentials
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminAccessCredentialListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
    post:
      tags:
      - AdminAccessCredentials
      operationId: adminCreateAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateAccessCredentialRequest"
      responses:
        '201':
          description: Access credential created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/access-credentials/{credential_id}":
    get:
      tags:
      - AdminAccessCredentials
      operationId: adminGetAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      responses:
        '200':
          description: Access credential
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      tags:
      - AdminAccessCredentials
      operationId: adminUpdateAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateAccessCredentialRequest"
      responses:
        '200':
          description: Access credential updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - AdminAccessCredentials
      operationId: adminDeleteAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      responses:
        '204':
          description: Access credential deleted
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/access-credentials/{credential_id}/rotate":
    post:
      tags:
      - AdminAccessCredentials
      operationId: adminRotateAccessCredential
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AccessCredentialIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminRotateAccessCredentialRequest"
      responses:
        '200':
          description: Access credential rotated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminCreateAccessCredentialResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/tenants/{tenant_id}/memberships":
    post:
      tags:
      - AdminUsers
      operationId: adminBindUserMembership
      summary: Assign user tenant/project membership (platform-admin)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/TenantIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminBindUserMembershipRequest"
      responses:
        '200':
          description: Membership bound (idempotent)
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminBindUserMembershipResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/tenants":
    get:
      tags:
      - AdminUsers
      operationId: adminListTenants
      summary: List tenants for platform-admin onboarding operations
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Tenant list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminTenantListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/tenants/{tenant_id}/projects":
    get:
      tags:
      - AdminUsers
      operationId: adminListTenantProjects
      summary: List projects within a tenant for platform-admin onboarding operations
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/TenantIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Tenant project list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminTenantProjectListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/tenant/users":
    get:
      tags:
      - Users
      operationId: tenantListUsers
      summary: List users in caller tenant (tenant-admin scope)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Tenant users
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TenantMemberListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
    post:
      tags:
      - Users
      operationId: tenantCreateUser
      summary: Create tenant user and bind tenant/project roles (tenant-admin scope)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TenantCreateUserRequest"
      responses:
        '201':
          description: User created and bound
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminCreateUserResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/tenant/users/{user_id}/memberships":
    post:
      tags:
      - Users
      operationId: tenantBindUserMembership
      summary: Bind or update user tenant/project membership in caller tenant (tenant-admin
        scope)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/UserIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TenantBindUserMembershipRequest"
      responses:
        '200':
          description: Membership bound
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminBindUserMembershipResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/users/{user_id}/refunds":
    get:
      tags:
      - AdminUsers
      operationId: adminListUserRefunds
      summary: List refund requests for a user
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/UserIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - accepted
          - completed
          - failed
      responses:
        '200':
          description: Refund requests
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RefundListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - AdminUsers
      operationId: adminCreateRefund
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/UserIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateRefundRequest"
      responses:
        '201':
          description: Refund request created and accepted under policy
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminCreateRefundResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/maas-sites":
    get:
      tags:
      - AdminMaasSites
      operationId: adminListMaasSites
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: MAAS sites
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - AdminMaasSites
      operationId: adminCreateMaasSite
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateMaasSiteRequest"
      responses:
        '201':
          description: Created MAAS site
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSite"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/maas-sites/{id}":
    get:
      tags:
      - AdminMaasSites
      operationId: adminGetMaasSite
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS site
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSite"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      tags:
      - AdminMaasSites
      operationId: adminUpdateMaasSite
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateMaasSiteRequest"
      responses:
        '200':
          description: Updated MAAS site
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSite"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - AdminMaasSites
      operationId: adminDisableMaasSite
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '204':
          description: MAAS site disabled
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/maas-sites/{id}/discovery-candidates":
    get:
      tags:
      - AdminMaasSites
      operationId: adminListMaasDiscoveryCandidates
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS discovery candidates for onboarding
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDiscoveryCandidateListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/maas-sites/{id}/discovery-candidates/{maas_system_id}/enrichment":
    get:
      tags:
      - AdminMaasSites
      operationId: adminGetMaasDiscoveryCandidateEnrichment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: maas_system_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: On-demand enrichment for a MAAS discovery candidate
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDiscoveryCandidateEnrichment"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/maas-sites/{id}/discovery-candidates/{maas_system_id}/decision":
    put:
      tags:
      - AdminMaasSites
      operationId: adminUpdateMaasDiscoveryCandidateDecision
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: maas_system_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateMaasDiscoveryCandidateDecisionRequest"
      responses:
        '200':
          description: Updated MAAS discovery candidate decision
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDiscoveryCandidateDecision"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/maas-sites/{id}/profiles":
    get:
      tags:
      - AdminMaasSites
      operationId: adminListMaasSiteProfiles
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS site profiles
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProfileListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - AdminMaasSites
      operationId: adminCreateMaasSiteProfile
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateMaasSiteProfileRequest"
      responses:
        '201':
          description: Created MAAS site profile
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProfile"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/maas-sites/{id}/profiles/{profile_id}":
    get:
      tags:
      - AdminMaasSites
      operationId: adminGetMaasSiteProfile
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - "$ref": "#/components/parameters/MaasSiteProfileIdPath"
      responses:
        '200':
          description: MAAS site profile
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProfile"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      tags:
      - AdminMaasSites
      operationId: adminUpdateMaasSiteProfile
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - "$ref": "#/components/parameters/MaasSiteProfileIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateMaasSiteProfileRequest"
      responses:
        '200':
          description: Updated MAAS site profile
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProfile"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - AdminMaasSites
      operationId: adminDisableMaasSiteProfile
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - "$ref": "#/components/parameters/MaasSiteProfileIdPath"
      responses:
        '204':
          description: MAAS site profile disabled
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/maas-sites/{id}/credentials":
    post:
      tags:
      - AdminMaasSites
      operationId: adminWriteMaasSiteCredentials
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsRequest"
      responses:
        '200':
          description: MAAS site credentials written and validated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/maas-sites/{id}/probe":
    post:
      tags:
      - AdminMaasSites
      operationId: adminProbeMaasSite
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS site probed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProbeResult"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/maas-sites/{id}/roce-assignments":
    get:
      tags:
      - AdminMaasSites
      operationId: adminListMaasRoceAssignments
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS site RoCE assignments
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasRoceAssignmentListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - AdminMaasSites
      operationId: adminBulkUpsertMaasRoceAssignments
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminBulkUpsertMaasRoceAssignmentsRequest"
      responses:
        '200':
          description: MAAS site RoCE assignments upserted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasRoceAssignmentListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/maas-sites/{id}/roce-assignments/{assignment_id}":
    delete:
      tags:
      - AdminMaasSites
      operationId: adminDeleteMaasRoceAssignment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: assignment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: MAAS site RoCE assignment deleted
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/maas-sites/{id}/roce-assignments/{assignment_id}/enable":
    post:
      tags:
      - AdminMaasSites
      operationId: adminEnableMaasRoceAssignment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: assignment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: MAAS site RoCE assignment enabled
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasRoceAssignment"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/maas-sites/{id}/roce-assignments/{assignment_id}/disable":
    post:
      tags:
      - AdminMaasSites
      operationId: adminDisableMaasRoceAssignmentExplicit
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: assignment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminSetMaasRoceAssignmentStatusRequest"
      responses:
        '200':
          description: MAAS site RoCE assignment disabled
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasRoceAssignment"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/onboardings":
    post:
      tags:
      - AdminMaasLifecycle
      operationId: adminStartMaasOnboarding
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminStartMaasOnboardingRequest"
      responses:
        '202':
          description: MAAS onboarding accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminListMaasOnboardings
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: batch_id
        in: query
        schema:
          type: string
          format: uuid
      - name: site_id
        in: query
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        schema:
          "$ref": "#/components/schemas/MaasWorkflowStatus"
      responses:
        '200':
          description: MAAS onboarding workflows
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasOnboardingListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/onboardings/batch":
    post:
      tags:
      - AdminMaasLifecycle
      operationId: adminStartMaasBatchOnboarding
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingRequest"
      responses:
        '202':
          description: MAAS batch onboarding accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/onboardings/{onboarding_id}":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminGetMaasOnboarding
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      responses:
        '200':
          description: MAAS onboarding workflow detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasOnboardingDetail"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/onboardings/{onboarding_id}/install-output":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminGetMaasOnboardingInstallOutput
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      responses:
        '200':
          description: Current MAAS installation output for the onboarding machine
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasOnboardingInstallOutput"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/onboardings/{onboarding_id}/maas-events":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminGetMaasOnboardingMaasEvents
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      - name: level
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Recent MAAS events for the onboarding machine
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasOnboardingEvents"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/onboardings/{onboarding_id}/resume":
    post:
      tags:
      - AdminMaasLifecycle
      operationId: adminResumeMaasOnboarding
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      responses:
        '202':
          description: MAAS onboarding resume accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/onboardings/{onboarding_id}/rerun":
    post:
      tags:
      - AdminMaasLifecycle
      operationId: adminRerunMaasOnboarding
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      responses:
        '202':
          description: MAAS onboarding rerun accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/decommissions":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminListMaasDecommissions
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: node_id
        in: query
        schema:
          type: string
          format: uuid
      - name: site_id
        in: query
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        schema:
          "$ref": "#/components/schemas/MaasWorkflowStatus"
      responses:
        '200':
          description: MAAS decommission workflows
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDecommissionListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/decommissions/{decommission_id}":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminGetMaasDecommission
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '200':
          description: MAAS decommission workflow detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDecommissionDetail"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/decommissions/{decommission_id}/install-output":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminGetMaasDecommissionInstallOutput
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '200':
          description: Current MAAS installation output for the decommission machine
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDecommissionInstallOutput"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/decommissions/{decommission_id}/maas-events":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminGetMaasDecommissionMaasEvents
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      - name: level
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Recent MAAS events for the decommission machine
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDecommissionEvents"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/reconciliation/status":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminGetMaasReconciliationStatus
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: MAAS reconciliation summary
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasReconciliationStatus"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/reconciliation/drift":
    get:
      tags:
      - AdminMaasLifecycle
      operationId: adminListMaasDrift
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: site_id
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: MAAS reconciliation drift records
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDriftListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/nodes":
    get:
      tags:
      - AdminNodes
      operationId: adminListNodes
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - retired
          - removing
          - maintenance
      - name: region_code
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Nodes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeAdminListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
    post:
      tags:
      - AdminNodes
      operationId: adminCreateNode
      summary: Register a new host as a node after any prior node identity on that
        host has been fully removed
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateNodeRequest"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeAdmin"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/nodes/{node_id}/resource-slots":
    get:
      tags:
      - AdminNodes
      operationId: adminListNodeResourceSlots
      summary: List approved GPU slice slot inventory for a node
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Node resource slots
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeResourceSlotListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    put:
      tags:
      - AdminNodes
      operationId: adminUpsertNodeResourceSlots
      summary: Upsert admin-approved GPU slice slot inventory for a node
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpsertNodeResourceSlotsRequest"
      responses:
        '200':
          description: Upserted node resource slots
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeResourceSlotListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/nodes/{node_id}/slice-topology/discovery":
    get:
      tags:
      - AdminNodes
      operationId: adminGetLatestNodeSliceTopologyDiscovery
      summary: Get latest node-agent GPU slice topology discovery report
      description: Returns the latest advisory `slice.topology_discover` node task
        output. The returned candidate map is not schedulable until approved through
        `/resource-slots`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Latest topology discovery task, or null when none has run
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - AdminNodes
      operationId: adminStartNodeSliceTopologyDiscovery
      summary: Queue node-agent GPU slice topology discovery
      description: Queues or reuses a non-expired `slice.topology_discover` task for
        a node. Discovery output is advisory only and must be approved into `node_resource_slots`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '202':
          description: Discovery task queued or already in progress
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/os-images":
    get:
      tags:
      - AdminOSImages
      operationId: adminListOSImages
      summary: List admin-managed OS images for baremetal and GPU slice runtimes
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: target
        in: query
        schema:
          "$ref": "#/components/schemas/OSImageTarget"
      - name: status
        in: query
        schema:
          "$ref": "#/components/schemas/OSImageStatus"
      - name: sku
        in: query
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: OS image catalog entries
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OSImageListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - AdminOSImages
      operationId: adminCreateOSImage
      summary: Register an OS image catalog entry
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateOSImageRequest"
      responses:
        '201':
          description: Created OS image
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OSImage"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/os-images/{image_id}":
    delete:
      tags:
      - AdminOSImages
      operationId: adminRemoveOSImage
      summary: Disable an OS image catalog entry so it cannot be selected for new
        hosts or slices
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OSImageIdPath"
      responses:
        '204':
          description: Disabled
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/skus":
    get:
      tags:
      - AdminSkus
      operationId: adminListSkus
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Admin SKU list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSkuListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '429':
          "$ref": "#/components/responses/TooManyRequests"
    post:
      tags:
      - AdminSkus
      operationId: adminCreateSku
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateSkuRequest"
      responses:
        '201':
          description: Created SKU
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSku"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/skus/{sku}":
    patch:
      tags:
      - AdminSkus
      operationId: adminUpdateSku
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SkuPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateSkuRequest"
      responses:
        '200':
          description: Updated SKU
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSku"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/skus/{sku}/activate":
    post:
      tags:
      - AdminSkus
      operationId: adminActivateSku
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SkuPath"
      responses:
        '200':
          description: Activated SKU
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSku"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/skus/{sku}/deactivate":
    post:
      tags:
      - AdminSkus
      operationId: adminDeactivateSku
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SkuPath"
      responses:
        '200':
          description: Deactivated SKU
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSku"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/nodes/{node_id}/probe":
    post:
      tags:
      - AdminNodes
      operationId: adminProbeNode
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Probed
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                    enum:
                    - active
                    - offline
                required:
                - ok
                - status
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/nodes/{node_id}/enrollment-token":
    post:
      tags:
      - AdminNodes
      operationId: adminCreateNodeEnrollmentToken
      summary: Create a single-use node enrollment token (manual onboarding)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '201':
          description: Enrollment token created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminNodeEnrollmentTokenResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/nodes/{node_id}/reissue-enrollment":
    post:
      tags:
      - AdminNodes
      operationId: adminReissueNodeEnrollment
      summary: Reissue recovery enrollment material for an installed node agent
      description: Creates a short-lived enrollment token and returns operator-ready
        recovery instructions without requiring node bootstrap package generation.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '201':
          description: Re-enrollment material created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminNodeReenrollmentResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/nodes/{node_id}/bootstrap-script":
    post:
      tags:
      - AdminNodes
      operationId: adminCreateNodeBootstrapScript
      summary: Create a brokered node bootstrap script and short-lived bootstrap token
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      - name: mode
        in: query
        schema:
          type: string
          enum:
          - manual
          - cloud_init
          default: manual
        description: Render mode for operator shell or cloud-init consumption.
      responses:
        '201':
          description: Bootstrap script created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminNodeBootstrapScriptResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/nodes/{node_id}/agent-lifecycle":
    get:
      tags:
      - AdminNodes
      operationId: adminGetNodeAgentLifecycle
      summary: Get the latest node-agent lifecycle state and most recent lifecycle
        run for a node
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Current node-agent lifecycle state
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  node_id:
                    type: string
                    format: uuid
                  state:
                    "$ref": "#/components/schemas/NodeAgentLifecycleState"
                  latest_run:
                    allOf:
                    - "$ref": "#/components/schemas/NodeAgentLifecycleRun"
                    nullable: true
                required:
                - node_id
                - state
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - AdminNodes
      operationId: adminStartNodeAgentLifecycle
      summary: Start a node-agent lifecycle run for upgrade or repair
      description: |
        The control plane must support explicit execution modes for secure operator flows:
        `reimage` and `manual_install`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleRequest"
      responses:
        '202':
          description: Node-agent lifecycle accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/nodes/{node_id}":
    delete:
      tags:
      - AdminNodes
      operationId: adminDeleteNode
      summary: Retire a node (reversible)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '204':
          description: Node retired
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/nodes/{node_id}/reactivate":
    post:
      tags:
      - AdminNodes
      operationId: adminReactivateNode
      summary: Reactivate a retired node with the same node identity
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Node reactivated
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                    enum:
                    - offline
                required:
                - ok
                - status
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/nodes/{node_id}/resume-lifecycle":
    post:
      tags:
      - AdminNodes
      operationId: adminResumeNodeLifecycle
      summary: Resume an in-progress node lifecycle transition
      description: |
        Recovers coarse in-progress inventory lifecycle states whose owning node task may
        have been lost, expired, or left in a stale dispatched lease. Supported states:
        `draining` -> `node.drain`, `removing` -> `node.uninstall`.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Node lifecycle resume accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminResumeNodeLifecycleResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/nodes/{node_id}/remove":
    delete:
      tags:
      - AdminNodes
      operationId: adminRemoveNode
      summary: Permanently remove a retired node and start host cleanup for later
        host reuse
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '204':
          description: Node removal started
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/nodes/{node_id}/detach":
    delete:
      tags:
      - AdminNodes
      operationId: adminDetachNode
      summary: Permanently remove a retired node from GPUaaS without touching the
        underlying host
      description: |
        Performs GPUaaS-only control-plane cleanup for a retired node. This operation does not
        call MAAS, does not uninstall host software, and does not power cycle or release the
        underlying machine. Use this when the host has already been repurposed or must remain
        untouched outside GPUaaS.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '204':
          description: Node detached from GPUaaS
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/nodes/{node_id}/force-detach":
    delete:
      tags:
      - AdminNodes
      operationId: adminForceDetachNode
      summary: Forcefully remove a stuck node from GPUaaS without waiting for host
        lifecycle completion
      description: |
        Performs GPUaaS-only control-plane cleanup for a node stuck in `draining`,
        `removing`, or `retired` when the owning node-agent lifecycle cannot complete.
        This operation does not call MAAS, does not uninstall host software, and does not
        power cycle or release the underlying machine. Use this only for unreachable,
        repurposed, or disposable hosts where host-side cleanup is no longer possible.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '204':
          description: Node force-detached from GPUaaS
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/nodes/{node_id}/decommission":
    post:
      tags:
      - AdminMaasLifecycle
      operationId: adminStartMaasDecommission
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminStartMaasDecommissionRequest"
      responses:
        '202':
          description: MAAS decommission accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/decommissions/{decommission_id}/resume":
    post:
      tags:
      - AdminMaasLifecycle
      operationId: adminResumeMaasDecommission
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '202':
          description: MAAS decommission resume accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/decommissions/{decommission_id}/cancel":
    post:
      tags:
      - AdminMaasLifecycle
      operationId: adminCancelMaasDecommission
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '202':
          description: MAAS decommission cancel accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/decommissions/{decommission_id}/rerun":
    post:
      tags:
      - AdminMaasLifecycle
      operationId: adminRerunMaasDecommission
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '202':
          description: MAAS decommission rerun accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/users/{user_id}":
    get:
      tags:
      - AdminUsers
      operationId: adminGetUser
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/UserIdPath"
      responses:
        '200':
          description: User detail with balance
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/UserWithBalance"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/allocations":
    get:
      tags:
      - AdminAllocations
      operationId: adminListAllocations
      summary: List all allocations across all users (admin)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: user_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: node_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - requested
          - provisioning
          - active
          - restarting
          - restart_failed
          - releasing
          - released
          - failed
          - release_failed
      responses:
        '200':
          description: Allocation list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/allocations/limits/policy":
    get:
      tags:
      - AdminAllocations
      operationId: adminGetAllocationConcurrencyPolicy
      summary: Get the global concurrent-allocation policy
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Global allocation concurrency policy details
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminAllocationConcurrencyPolicy"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    put:
      tags:
      - AdminAllocations
      operationId: adminSetAllocationConcurrencyPolicy
      summary: Set the global concurrent-allocation policy
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminSetAllocationConcurrencyPolicyRequest"
      responses:
        '200':
          description: Updated global allocation concurrency policy details
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminAllocationConcurrencyPolicy"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/allocations/placement-claims/backfill":
    post:
      tags:
      - AdminAllocations
      operationId: adminBackfillAllocationPlacementClaims
      summary: Backfill missing baremetal node-exclusive placement claims
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      responses:
        '200':
          description: Backfill result
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminBackfillAllocationPlacementClaimsResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/admin/allocations/{allocation_id}/timeline":
    get:
      tags:
      - AdminAllocations
      operationId: adminGetAllocationTimeline
      summary: Get sanitized provisioning and release timeline for any allocation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/AllocationIdPath"
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: Maximum number of recent timeline items to return.
      - in: query
        name: cursor
        schema:
          type: string
        description: Opaque cursor returned by the previous page.
      responses:
        '200':
          description: Allocation task timeline
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationTimelineResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/allocations/{allocation_id}/force-release":
    post:
      tags:
      - AdminAllocations
      operationId: adminForceReleaseAllocation
      summary: Force-release any active allocation regardless of owner (admin)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  minLength: 3
              required:
              - reason
      responses:
        '202':
          description: Force release accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ReleaseAllocationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/allocations/{allocation_id}/force-cleanup":
    post:
      tags:
      - AdminAllocations
      operationId: adminForceCleanupAllocation
      summary: Force-clean a stuck requested/provisioning GPU slice allocation (admin)
      description: 'Fails a stuck GPU-slice allocation before it becomes active. By
        default claimed slots are moved to cleanup_blocked so an operator must inspect
        the host. If runtime_verified_absent is true, the operator has verified no
        VM or runtime remains and claimed slots are returned to available.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  minLength: 3
                runtime_verified_absent:
                  type: boolean
                  default: false
                  description: Set true only after verifying no VM/process/runtime
                    remains on the slice host.
              required:
              - reason
      responses:
        '200':
          description: Force cleanup applied
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ReleaseAllocationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/audit-logs":
    get:
      tags:
      - AdminAudit
      operationId: adminListAuditLogs
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: actor_user_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: actor_role
        in: query
        required: false
        schema:
          type: string
          enum:
          - user
          - admin
          - service_account
          - system
      - name: action
        in: query
        required: false
        schema:
          type: string
      - name: target_type
        in: query
        required: false
        schema:
          type: string
      - name: correlation_id
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Paginated audit logs
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuditLogListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/audit-logs":
    get:
      tags:
      - Audit
      operationId: listMyAuditLogs
      summary: List audit logs visible to the authenticated user
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: action
        in: query
        required: false
        schema:
          type: string
      - name: target_type
        in: query
        required: false
        schema:
          type: string
      - name: correlation_id
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Paginated user-scoped audit logs
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuditLogListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/projects/{project_id}/audit-logs":
    get:
      tags:
      - Audit
      operationId: listProjectAuditLogs
      summary: List audit logs visible to project administrators
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: action
        in: query
        required: false
        schema:
          type: string
      - name: target_type
        in: query
        required: false
        schema:
          type: string
      - name: correlation_id
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Paginated project-scoped audit logs
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuditLogListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/orgs/{org_id}/audit-logs":
    get:
      tags:
      - Audit
      operationId: listOrgAuditLogs
      summary: List audit logs visible to tenant administrators
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OrgIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: action
        in: query
        required: false
        schema:
          type: string
      - name: target_type
        in: query
        required: false
        schema:
          type: string
      - name: correlation_id
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Paginated tenant-scoped audit logs
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuditLogListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/audit-logs/export":
    get:
      tags:
      - AdminAudit
      operationId: adminExportAuditLogsCsv
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: actor_user_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: action
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Audit log export CSV
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/payments/sessions":
    get:
      tags:
      - AdminPayments
      operationId: adminListPaymentSessions
      summary: List payment sessions for reconciliation and support (admin)
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: user_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - initiated
          - checkout_completed
          - credited
          - failed_reconcile
          - expired
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Payment session list
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      "$ref": "#/components/schemas/PaymentSession"
                  pagination:
                    "$ref": "#/components/schemas/Pagination"
                required:
                - items
                - pagination
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/payments/sessions/{payment_session_id}":
    get:
      tags:
      - AdminPayments
      operationId: adminGetPaymentSession
      summary: Get payment session detail for reconciliation and support
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: payment_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Payment session
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PaymentSession"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/payments/sessions/{payment_session_id}/reconcile":
    post:
      tags:
      - AdminPayments
      operationId: adminReconcilePaymentSession
      summary: Reconcile a stuck or failed payment session with an audited operator
        action
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: payment_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminReconcilePaymentSessionRequest"
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Reconciled payment session
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PaymentSession"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/admin/billing/reconciliation":
    get:
      tags:
      - AdminPayments
      operationId: adminListBillingReconciliation
      summary: List billing reconciliation runs and current usage-ledger posture
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Billing reconciliation posture
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BillingReconciliationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - AdminPayments
      operationId: adminRunBillingReconciliation
      summary: Run an immediate usage-ledger reconciliation check
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      security:
      - bearerAuth: []
      responses:
        '202':
          description: Billing reconciliation completed and recorded
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BillingReconciliationRun"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/admin/billing/reconciliation/{job_id}":
    get:
      tags:
      - AdminPayments
      operationId: adminGetBillingReconciliation
      summary: Get a billing reconciliation run
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Billing reconciliation run
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BillingReconciliationRun"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/admin/billing/diagnostics":
    get:
      tags:
      - AdminPayments
      operationId: adminGetBillingDiagnostics
      summary: Fetch billing evidence by correlation id for support and dispute triage
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: correlation_id
        in: query
        required: true
        schema:
          type: string
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Billing diagnostic evidence
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BillingDiagnosticsResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/launch/compute":
    post:
      tags:
      - V3ReadModels
      operationId: submitV3ComputeLaunch
      summary: Submit v3 compute launch
      description: 'Mutating submit endpoint for the v3 compute wizard. The endpoint
        reuses the allocation creation domain path and returns a normalized task handoff
        so the browser can route immediately to the v3 task progress page. Clients
        must send an idempotency key; replaying the same body with the same key must
        not create a duplicate workload.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3ComputeLaunchSubmitRequest"
      responses:
        '202':
          description: V3 compute launch accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3LaunchSubmitResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/launch/apps/{app_slug}":
    post:
      tags:
      - V3ReadModels
      operationId: submitV3AppLaunch
      summary: Submit v3 app launch
      description: 'Mutating submit endpoint for the v3 app wizard. The endpoint reuses
        the app-instance domain path and returns a normalized task handoff so app-backed
        runtimes remain workload subtypes in the v3 shell. Clients must send an idempotency
        key; replaying the same body with the same key must not create a duplicate
        app instance.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppSlugPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3AppLaunchSubmitRequest"
      responses:
        '202':
          description: V3 app launch accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3LaunchSubmitResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/overview":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformOverview
      summary: Get v3 platform overview read model
      description: 'Temporary v3 migration read model for the Platform landing page.
        It summarizes operator families, fleet posture, active allocations, API health,
        worker posture, and DLQ state. Requires platform ops read permission.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: V3 platform overview
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformOverviewResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/ops":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformOps
      summary: Get v3 platform live ops read model
      description: Temporary v3 migration read model for live triage, active signals,
        service health, and investigation pivots. Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: V3 platform ops
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformOpsResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/ops/signals/{signal_key}/acknowledge":
    post:
      tags:
      - V3ReadModels
      operationId: acknowledgeV3PlatformSignal
      summary: Acknowledge a v3 platform operator signal
      description: Backend-owned acknowledgement mutation for an active admin workbench
        signal. Requires platform ops write permission and an idempotency key for
        safe retries. The backend validates the supplied fingerprint against the current
        read-model signal before persisting acknowledgement state.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3PlatformSignalKeyPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3PlatformSignalAcknowledgeRequest"
      responses:
        '200':
          description: Signal acknowledgement state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformSignalAckResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/ops/signals/{signal_key}/suppress":
    post:
      tags:
      - V3ReadModels
      operationId: suppressV3PlatformSignal
      summary: Suppress a v3 platform operator signal
      description: Backend-owned suppression mutation for admin workbench queue noise.
        Suppression requires a future expires_at timestamp and resurfaces automatically
        when the backend fingerprint changes. Requires platform ops write permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3PlatformSignalKeyPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3PlatformSignalSuppressRequest"
      responses:
        '200':
          description: Signal suppression state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformSignalAckResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/ops/signals/{signal_key}/acknowledgement":
    delete:
      tags:
      - V3ReadModels
      operationId: clearV3PlatformSignalAcknowledgement
      summary: Clear acknowledgement or suppression for a v3 platform signal
      description: Clears current acknowledgement/suppression state for an admin workbench
        signal without deleting the audit trail. Requires platform ops write permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3PlatformSignalKeyPath"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3PlatformSignalClearRequest"
      responses:
        '200':
          description: Signal acknowledgement cleared
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformSignalAckResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformLifecycle
      summary: Get v3 platform lifecycle read model
      description: Temporary v3 migration read model for node lifecycle posture, action
        queue, and inventory rows. Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 platform lifecycle
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformLifecycleResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/lifecycle/attention/{attention_key}/review":
    post:
      tags:
      - V3ReadModels
      operationId: reviewV3ProvisioningAttention
      summary: Review a v3 provisioning attention item
      description: Marks a backend-owned provisioning attention item as taken care
        of or intentionally ignored. Requires platform ops write permission, persists
        an audit row, and keeps reviewed items available through history/evidence
        while removing them from default live attention queues.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3ProvisioningAttentionKeyPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3ProvisioningAttentionReviewRequest"
      responses:
        '200':
          description: Provisioning attention review state
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3ProvisioningAttentionReviewResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/onboarding":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformOnboardingGuidance
      summary: Get v3 platform node onboarding guidance read model
      description: Guidance-first node onboarding contract for site/profile selection,
        bootstrap readiness, manual fallback command shape, progress steps, and future
        automated MAAS mutation readiness. Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: V3 platform node onboarding guidance
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformOnboardingGuidanceResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - V3PlatformLifecycle
      operationId: startV3PlatformOnboarding
      summary: Start a v3 platform MAAS node onboarding workflow
      description: V3 lifecycle wrapper for the MAAS onboarding mutation. Requires
        platform ops mutation permission and an Idempotency-Key.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminStartMaasOnboardingRequest"
      responses:
        '202':
          description: V3 platform MAAS onboarding accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/onboarding/batch":
    post:
      tags:
      - V3PlatformLifecycle
      operationId: startV3PlatformBatchOnboarding
      summary: Start a v3 platform MAAS batch onboarding workflow
      description: V3 lifecycle wrapper for batch MAAS onboarding.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingRequest"
      responses:
        '202':
          description: V3 platform MAAS batch onboarding accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}":
    get:
      tags:
      - V3PlatformLifecycle
      operationId: getV3PlatformOnboarding
      summary: Get v3 platform onboarding workflow detail
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      responses:
        '200':
          description: V3 platform MAAS onboarding workflow detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasOnboardingDetail"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}/install-output":
    get:
      tags:
      - V3PlatformLifecycle
      operationId: getV3PlatformOnboardingInstallOutput
      summary: Get v3 platform onboarding install output
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      responses:
        '200':
          description: Current MAAS installation output for the onboarding machine
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasOnboardingInstallOutput"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}/maas-events":
    get:
      tags:
      - V3PlatformLifecycle
      operationId: getV3PlatformOnboardingMaasEvents
      summary: Get v3 platform onboarding MAAS events
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      - name: level
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Recent MAAS events for the onboarding machine
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasOnboardingEvents"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}/resume":
    post:
      tags:
      - V3PlatformLifecycle
      operationId: resumeV3PlatformOnboarding
      summary: Resume a v3 platform onboarding workflow
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      responses:
        '202':
          description: V3 platform onboarding resume accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}/rerun":
    post:
      tags:
      - V3PlatformLifecycle
      operationId: rerunV3PlatformOnboarding
      summary: Rerun a v3 platform onboarding workflow
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OnboardingIdPath"
      responses:
        '202':
          description: V3 platform onboarding rerun accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/decommission":
    post:
      tags:
      - V3PlatformLifecycle
      operationId: startV3PlatformNodeDecommission
      summary: Start a v3 platform node decommission or reimage workflow
      description: V3 lifecycle wrapper for MAAS node decommission/reimage.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminStartMaasDecommissionRequest"
      responses:
        '202':
          description: V3 platform MAAS decommission accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}":
    get:
      tags:
      - V3PlatformLifecycle
      operationId: getV3PlatformDecommission
      summary: Get v3 platform decommission workflow detail
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '200':
          description: V3 platform MAAS decommission workflow detail
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDecommissionDetail"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/install-output":
    get:
      tags:
      - V3PlatformLifecycle
      operationId: getV3PlatformDecommissionInstallOutput
      summary: Get v3 platform decommission install output
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '200':
          description: Current MAAS installation output for the decommission machine
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDecommissionInstallOutput"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/maas-events":
    get:
      tags:
      - V3PlatformLifecycle
      operationId: getV3PlatformDecommissionMaasEvents
      summary: Get v3 platform decommission MAAS events
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      - name: level
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Recent MAAS events for the decommission machine
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDecommissionEvents"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/resume":
    post:
      tags:
      - V3PlatformLifecycle
      operationId: resumeV3PlatformDecommission
      summary: Resume a v3 platform decommission workflow
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '202':
          description: V3 platform decommission resume accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/cancel":
    post:
      tags:
      - V3PlatformLifecycle
      operationId: cancelV3PlatformDecommission
      summary: Cancel a v3 platform decommission workflow
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '202':
          description: V3 platform decommission cancel accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/rerun":
    post:
      tags:
      - V3PlatformLifecycle
      operationId: rerunV3PlatformDecommission
      summary: Rerun a v3 platform decommission workflow
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/DecommissionIdPath"
      responses:
        '202':
          description: V3 platform decommission rerun accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformNodeDetail
      summary: Get v3 platform node detail read model
      description: Temporary v3 migration read model for one node's lifecycle, MAAS,
        agent, slot, allocation, and task posture. Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: V3 platform node detail
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformNodeDetailResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    delete:
      tags:
      - V3ReadModels
      operationId: retireV3PlatformNode
      summary: Retire a v3 platform node
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '204':
          description: Node retired
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/cordon":
    post:
      tags:
      - V3ReadModels
      operationId: cordonV3PlatformNode
      summary: Cordon a platform node
      description: Stops new scheduling onto an active node while preserving running
        workloads. Requires platform admin permission and Idempotency-Key.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Node cordoned
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/drain":
    post:
      tags:
      - V3ReadModels
      operationId: drainV3PlatformNode
      summary: Drain a platform node
      description: Cordons an active or cordoned node and queues the node.drain lifecycle
        task. Requires platform admin permission and Idempotency-Key.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '202':
          description: Node drain queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/resume-scheduling":
    post:
      tags:
      - V3ReadModels
      operationId: resumeSchedulingV3PlatformNode
      summary: Resume scheduling for a cordoned platform node
      description: Returns a cordoned node to the active scheduler pool. Requires
        platform admin permission and Idempotency-Key.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Node scheduling resumed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/refresh-inventory":
    post:
      tags:
      - V3ReadModels
      operationId: refreshInventoryV3PlatformNode
      summary: Refresh node inventory
      description: Queues slice topology discovery for GPU, slot, and hardware inventory
        refresh. Requires platform admin permission and Idempotency-Key.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '202':
          description: Inventory refresh queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/config/setup":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformSetupChecklist
      summary: Get v3 platform setup checklist read model
      description: Operator first-run readiness checklist covering identity/PKI, registry,
        MAAS provisioning, node-agent posture, runtime inventory, telemetry, network/security
        placeholders, and storage provider posture. Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: V3 platform setup checklist
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformSetupChecklistResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/config":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformConfig
      summary: Get v3 platform configuration read model
      description: Temporary v3 migration read model for SKU, OS image, quota, MAAS
        profile, and policy posture. Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: V3 platform config
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformConfigResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/config/skus":
    post:
      tags:
      - V3ReadModels
      operationId: createV3PlatformConfigSku
      summary: Create a GPU SKU from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateSkuRequest"
      responses:
        '201':
          description: SKU created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSku"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/config/skus/{sku}":
    patch:
      tags:
      - V3ReadModels
      operationId: updateV3PlatformConfigSku
      summary: Update a GPU SKU from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SkuPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateSkuRequest"
      responses:
        '200':
          description: SKU updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSku"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/config/skus/{sku}/activate":
    post:
      tags:
      - V3ReadModels
      operationId: activateV3PlatformConfigSku
      summary: Activate a GPU SKU from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SkuPath"
      responses:
        '200':
          description: SKU activated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSku"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/config/skus/{sku}/deactivate":
    post:
      tags:
      - V3ReadModels
      operationId: deactivateV3PlatformConfigSku
      summary: Deactivate a GPU SKU from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SkuPath"
      responses:
        '200':
          description: SKU deactivated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminSku"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/config/os-images":
    post:
      tags:
      - V3ReadModels
      operationId: createV3PlatformConfigOSImage
      summary: Create an OS image from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateOSImageRequest"
      responses:
        '201':
          description: OS image created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OSImage"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/config/os-images/{image_id}":
    patch:
      tags:
      - V3ReadModels
      operationId: updateV3PlatformConfigOSImage
      summary: Update an OS image from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OSImageIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateOSImageRequest"
      responses:
        '200':
          description: OS image updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OSImage"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - V3ReadModels
      operationId: deleteV3PlatformConfigOSImage
      summary: Remove an OS image from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OSImageIdPath"
      responses:
        '204':
          description: OS image removed
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/config/os-images/{image_id}/deprecate":
    post:
      tags:
      - V3ReadModels
      operationId: deprecateV3PlatformConfigOSImage
      summary: Deprecate an OS image from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OSImageIdPath"
      responses:
        '200':
          description: OS image deprecated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OSImage"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/config/os-images/{image_id}/reactivate":
    post:
      tags:
      - V3ReadModels
      operationId: reactivateV3PlatformConfigOSImage
      summary: Reactivate an OS image from the v3 platform config workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/OSImageIdPath"
      responses:
        '200':
          description: OS image reactivated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OSImage"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/config/quotas/allocation-concurrency":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformConfigAllocationConcurrencyPolicy
      summary: Get the global concurrent-allocation policy from the v3 platform config
        workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Global allocation concurrency policy details
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminAllocationConcurrencyPolicy"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    put:
      tags:
      - V3ReadModels
      operationId: setV3PlatformConfigAllocationConcurrencyPolicy
      summary: Set the global concurrent-allocation policy from the v3 platform config
        workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminSetAllocationConcurrencyPolicyRequest"
      responses:
        '200':
          description: Updated global allocation concurrency policy details
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminAllocationConcurrencyPolicy"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/evidence":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformEvidence
      summary: Get v3 platform evidence read model
      description: Temporary v3 migration read model for audit and investigation pivots.
        Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 platform evidence
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformEvidenceResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/finance":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformFinance
      summary: Get v3 platform finance operations read model
      description: Temporary v3 migration read model for payment-session operations
        and financial intervention posture. Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 platform finance
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformFinanceResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/finance/sessions":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformFinanceSessions
      summary: List v3 platform finance payment sessions
      description: Workbench read model for payment-session triage. Returns backend-owned
        signal keys and ack fields so clients never derive acknowledgement identity.
        Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: user_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: correlation_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 platform finance sessions
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformFinanceSessionsResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/finance/sessions/{payment_session_id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformFinanceSessionDetail
      summary: Get v3 platform finance payment-session detail
      description: Focused payment-session detail read model with diagnostics, evidence
        links, and manual recovery operation targets. Provider replay is intentionally
        not exposed by this slice.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: payment_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: V3 platform finance session detail
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformFinanceSessionDetailResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/iam":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformIAM
      summary: Get v3 platform IAM read model
      description: Temporary v3 migration read model for users and platform role posture.
        Requires platform ops read permission.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 platform IAM
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3PlatformIAMResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/storage/{bucket_id}/grants":
    get:
      tags:
      - V3Storage
      operationId: listV3StorageGrants
      summary: List storage grants for a bucket
      description: 'Contract baseline for provider-neutral storage sharing. Returns
        GPUaaS grant records and compiled-policy posture only; provider credentials,
        raw WEKA policy JSON, and provider admin identifiers are never returned.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: Storage grants
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageGrantListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3Storage
      operationId: createV3StorageGrant
      summary: Create a bucket or prefix storage grant
      description: 'Creates a GPUaaS-owned storage grant. Provider adapters compile
        this grant into provider policy, for example WEKA IAM or bucket policy, but
        GPUaaS remains the source of truth. This mutation is idempotent and audited
        as `storage.grant.create`.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3StorageGrantCreateRequest"
      responses:
        '201':
          description: Storage grant created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageGrantResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/storage/{bucket_id}/grants/{grant_id}":
    delete:
      tags:
      - V3Storage
      operationId: revokeV3StorageGrant
      summary: Revoke a storage grant
      description: 'Revokes future provider credential issuance for a grant and asks
        the provider adapter to remove or narrow compiled policy where supported.
        Active STS credentials may remain valid until expiry if the provider cannot
        revoke individual sessions. Audited as `storage.grant.revoke`.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      - "$ref": "#/components/parameters/V3StorageGrantIdPath"
      responses:
        '200':
          description: Storage grant revoked
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageGrantRevokeResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/storage/{bucket_id}/credentials":
    post:
      tags:
      - V3Storage
      operationId: issueV3StorageCredential
      summary: Issue short-lived scoped storage credentials
      description: 'Issues direct S3-compatible credentials after GPUaaS IAM and storage
        grant checks. This endpoint may return provider credential material exactly
        once to the caller and must not be used by read models, cached responses,
        or browser local storage. For WEKA this maps to STS/session credentials when
        available. Audited as `auth.provider_credential.issue` and `storage.credential.issue`.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3StorageCredentialIssueRequest"
      responses:
        '201':
          description: Scoped storage credential issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3StorageCredentialIssueResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/access/quotas":
    get:
      tags:
      - V3ReadModels
      operationId: getV3AccessQuotaPosture
      summary: Get v3 access quota posture
      description: 'Returns the selected project/user effective allocation quota posture:
        concurrent allocation limit, current usage, launch headroom, and guidance
        links. This is the user/project quota surface; platform-level quota policy
        editing remains under Platform Config.

'
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      responses:
        '200':
          description: V3 access quota posture
          headers:
            X-Read-Model-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
                - bypass
                - stale
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/V3AccessQuotaResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/apps/artifacts":
    get:
      tags:
      - V3Apps
      operationId: listV3AppArtifacts
      summary: List registered app artifacts for the active V3 project
      description: Lists project-scoped app artifacts through the V3 project header
        contract. Registry credentials, wrapped pull tokens, and provider secrets
        are never returned by this list response.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: app_slug
        in: query
        required: false
        schema:
          type: string
      - name: lifecycle_state
        in: query
        required: false
        schema:
          type: string
          enum:
          - published
          - promoted
          - deprecated
          - retired
      responses:
        '200':
          description: V3 app artifacts
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifactListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3Apps
      operationId: registerV3AppArtifact
      summary: Register a published app artifact digest for the active V3 project
      description: Registers a previously published app artifact using the V3 project
        header contract. Audited by the app-artifact service and replay-protected
        by the V3 idempotency gate.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RegisterAppArtifactRequest"
      responses:
        '201':
          description: V3 app artifact registered
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/artifacts/publish-intents":
    post:
      tags:
      - V3Apps
      operationId: createV3AppArtifactPublishIntent
      summary: Issue a short-lived app artifact publish intent
      description: Issues a short-lived publish intent for direct artifact publication.
        The response may contain wrapped credential delivery material; clients must
        not persist or log credential fields.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAppArtifactPublishIntentRequest"
      responses:
        '201':
          description: V3 app artifact publish intent issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifactPublishIntent"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/artifacts/{artifact_id}/pull-intent":
    post:
      tags:
      - V3Apps
      operationId: createV3AppArtifactPullIntent
      summary: Issue a short-lived pull intent for a V3 app artifact
      description: Returns registry metadata and Vault-wrapped pull credentials for
        a project app artifact. Artifact bytes remain on the registry path; clients
        must not cache or persist the wrapped credential.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '201':
          description: V3 app artifact pull intent issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ArtifactPullIntent"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/apps/artifacts/{artifact_id}/promote":
    post:
      tags:
      - V3Apps
      operationId: promoteV3AppArtifact
      summary: Promote a V3 app artifact to a channel
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PromoteAppArtifactRequest"
      responses:
        '200':
          description: V3 app artifact promoted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/artifacts/{artifact_id}/verify":
    post:
      tags:
      - V3Apps
      operationId: verifyV3AppArtifact
      summary: Mark a V3 app artifact as verified
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '200':
          description: V3 app artifact verified
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/artifacts/{artifact_id}/revoke":
    post:
      tags:
      - V3Apps
      operationId: revokeV3AppArtifact
      summary: Revoke trust for a V3 app artifact
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '200':
          description: V3 app artifact trust revoked
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/artifacts/{artifact_id}/deprecate":
    post:
      tags:
      - V3Apps
      operationId: deprecateV3AppArtifact
      summary: Deprecate a V3 app artifact
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '200':
          description: V3 app artifact deprecated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/artifacts/{artifact_id}/retire":
    post:
      tags:
      - V3Apps
      operationId: retireV3AppArtifact
      summary: Retire a V3 app artifact from new use
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppArtifactIdPath"
      responses:
        '200':
          description: V3 app artifact retired
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppArtifact"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/finance/users/{user_id}/refunds":
    get:
      tags:
      - V3PlatformFinance
      operationId: listV3PlatformFinanceUserRefunds
      summary: List refund workflows for a user through the V3 finance boundary
      description: Lists refund workflow rows for a user. This is an actionable workflow
        surface; usage and ledger rows remain immutable read-only records.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/UserIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - accepted
          - completed
          - failed
      responses:
        '200':
          description: V3 finance user refund workflows
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RefundListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3PlatformFinance
      operationId: createV3PlatformFinanceUserRefund
      summary: Create a ledger-safe refund workflow for a user
      description: Creates an audited refund workflow. This endpoint does not mutate
        ledger rows directly; any ledger correction remains append-only and owned
        by the finance service boundary.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/UserIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateRefundRequest"
      responses:
        '201':
          description: V3 finance refund workflow created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminCreateRefundResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/finance/payment-sessions":
    get:
      tags:
      - V3PlatformFinance
      operationId: listV3PlatformFinancePaymentSessionsRaw
      summary: List raw payment sessions for V3 finance operators
      description: Raw payment-session support list for reconciliation workflows.
        Prefer `/api/v1/v3/platform/finance/sessions` for the operator workbench read
        model.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: user_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - initiated
          - checkout_completed
          - credited
          - failed_reconcile
          - expired
      responses:
        '200':
          description: V3 finance raw payment sessions
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      "$ref": "#/components/schemas/PaymentSession"
                  pagination:
                    "$ref": "#/components/schemas/Pagination"
                required:
                - items
                - pagination
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/finance/payment-sessions/{payment_session_id}":
    get:
      tags:
      - V3PlatformFinance
      operationId: getV3PlatformFinancePaymentSessionRaw
      summary: Get a raw payment session for V3 finance operators
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: payment_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: V3 finance raw payment session
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PaymentSession"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/finance/payment-sessions/{payment_session_id}/reconcile":
    post:
      tags:
      - V3PlatformFinance
      operationId: reconcileV3PlatformFinancePaymentSession
      summary: Reconcile a payment session through a ledger-safe V3 finance action
      description: Reconciles a stuck or failed payment session. `post_credit` appends
        an immutable ledger entry and marks the session credited; state-only actions
        mark expired or failed with an audited operator reason.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: payment_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminReconcilePaymentSessionRequest"
      responses:
        '200':
          description: V3 finance payment session reconciled
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PaymentSession"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/storage/{bucket_id}/objects/download":
    get:
      tags:
      - V3Storage
      operationId: downloadV3StorageObject
      summary: Download an object from a v3 storage bucket
      description: Downloads object bytes through the active V3 project context. The
        `path` query may be either bucket-relative or include the bucket prefix; the
        server normalizes it and rejects paths outside the bucket. No auth material
        is accepted in the query string.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      - "$ref": "#/components/parameters/V3StorageObjectPathQuery"
      responses:
        '200':
          description: Storage object bytes
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/storage/{bucket_id}/objects/upload":
    put:
      tags:
      - V3Storage
      operationId: uploadV3StorageObject
      summary: Upload object bytes to a v3 storage bucket
      description: Uploads object bytes through the active V3 project context. The
        `path` query may be bucket-relative or include the bucket prefix; the server
        normalizes it and rejects paths outside the bucket.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      - "$ref": "#/components/parameters/V3StorageObjectPathQuery"
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Storage object uploaded
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/storage/{bucket_id}/objects/mkdir":
    post:
      tags:
      - V3Storage
      operationId: createV3StorageDirectory
      summary: Create a directory marker in a v3 storage bucket
      description: Creates a provider-neutral directory marker through the active
        V3 project context. The supplied path may be bucket-relative or include the
        bucket prefix.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V3StorageObjectPathRequest"
      responses:
        '200':
          description: Storage directory created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/storage/{bucket_id}/objects":
    delete:
      tags:
      - V3Storage
      operationId: deleteV3StorageObject
      summary: Delete an object or prefix from a v3 storage bucket
      description: Deletes an object or prefix through the active V3 project context.
        The `path` query may be bucket-relative or include the bucket prefix; the
        server normalizes it and rejects paths outside the bucket.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/V3StorageBucketIdPath"
      - "$ref": "#/components/parameters/V3StorageObjectPathQuery"
      responses:
        '200':
          description: Storage object deleted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OkResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/maas-sites":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformMaasSites
      summary: List v3 MAAS provisioning sites
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: MAAS sites
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - V3ReadModels
      operationId: createV3PlatformMaasSite
      summary: Register a v3 MAAS provisioning site
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateMaasSiteRequest"
      responses:
        '201':
          description: Created MAAS site
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSite"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformMaasSite
      summary: Get a v3 MAAS provisioning site
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS site
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSite"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      tags:
      - V3ReadModels
      operationId: updateV3PlatformMaasSite
      summary: Update a v3 MAAS provisioning site
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateMaasSiteRequest"
      responses:
        '200':
          description: Updated MAAS site
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSite"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - V3ReadModels
      operationId: disableV3PlatformMaasSite
      summary: Disable a v3 MAAS provisioning site
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '204':
          description: MAAS site disabled
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/discovery-candidates":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformMaasDiscoveryCandidates
      summary: List v3 MAAS discovery candidates
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS discovery candidates
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDiscoveryCandidateListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/discovery-candidates/{maas_system_id}/enrichment":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformMaasDiscoveryCandidateEnrichment
      summary: Get v3 MAAS discovery candidate enrichment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: maas_system_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: MAAS discovery candidate enrichment
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDiscoveryCandidateEnrichment"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/discovery-candidates/{maas_system_id}/decision":
    put:
      tags:
      - V3ReadModels
      operationId: updateV3PlatformMaasDiscoveryCandidateDecision
      summary: Review a v3 MAAS discovery candidate
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: maas_system_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateMaasDiscoveryCandidateDecisionRequest"
      responses:
        '200':
          description: Updated MAAS discovery candidate decision
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDiscoveryCandidateDecision"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/profiles":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformMaasSiteProfiles
      summary: List v3 MAAS provisioning profiles
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS site profiles
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProfileListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3ReadModels
      operationId: createV3PlatformMaasSiteProfile
      summary: Create a v3 MAAS provisioning profile
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminCreateMaasSiteProfileRequest"
      responses:
        '201':
          description: Created MAAS site profile
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProfile"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/profiles/{profile_id}":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformMaasSiteProfile
      summary: Get a v3 MAAS provisioning profile
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - "$ref": "#/components/parameters/MaasSiteProfileIdPath"
      responses:
        '200':
          description: MAAS site profile
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProfile"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      tags:
      - V3ReadModels
      operationId: updateV3PlatformMaasSiteProfile
      summary: Update a v3 MAAS provisioning profile
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - "$ref": "#/components/parameters/MaasSiteProfileIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpdateMaasSiteProfileRequest"
      responses:
        '200':
          description: Updated MAAS site profile
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProfile"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
    delete:
      tags:
      - V3ReadModels
      operationId: disableV3PlatformMaasSiteProfile
      summary: Disable a v3 MAAS provisioning profile
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - "$ref": "#/components/parameters/MaasSiteProfileIdPath"
      responses:
        '204':
          description: MAAS site profile disabled
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/credentials":
    post:
      tags:
      - V3ReadModels
      operationId: writeV3PlatformMaasSiteCredentials
      summary: Write v3 MAAS site credentials
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsRequest"
      responses:
        '200':
          description: MAAS site credentials written and validated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/probe":
    post:
      tags:
      - V3ReadModels
      operationId: probeV3PlatformMaasSite
      summary: Probe a v3 MAAS site
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS site probed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasSiteProbeResult"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/roce-assignments":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformMaasRoceAssignments
      summary: List v3 MAAS RoCE assignments
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      responses:
        '200':
          description: MAAS site RoCE assignments
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasRoceAssignmentListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3ReadModels
      operationId: upsertV3PlatformMaasRoceAssignments
      summary: Upsert v3 MAAS RoCE assignments
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminBulkUpsertMaasRoceAssignmentsRequest"
      responses:
        '200':
          description: MAAS site RoCE assignments upserted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasRoceAssignmentListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}":
    delete:
      tags:
      - V3ReadModels
      operationId: deleteV3PlatformMaasRoceAssignment
      summary: Delete a v3 MAAS RoCE assignment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: assignment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: MAAS site RoCE assignment deleted
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}/enable":
    post:
      tags:
      - V3ReadModels
      operationId: enableV3PlatformMaasRoceAssignment
      summary: Enable a v3 MAAS RoCE assignment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: assignment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: MAAS site RoCE assignment enabled
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasRoceAssignment"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}/disable":
    post:
      tags:
      - V3ReadModels
      operationId: disableV3PlatformMaasRoceAssignment
      summary: Disable a v3 MAAS RoCE assignment
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/MaasSiteIdPath"
      - name: assignment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminSetMaasRoceAssignmentStatusRequest"
      responses:
        '200':
          description: MAAS site RoCE assignment disabled
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasRoceAssignment"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/reconciliation/status":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformMaasReconciliationStatus
      summary: Get v3 MAAS reconciliation status
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: MAAS reconciliation summary
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasReconciliationStatus"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/lifecycle/reconciliation/drift":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformMaasDrift
      summary: List v3 MAAS reconciliation drift
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: site_id
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: MAAS reconciliation drift records
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDriftListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/lifecycle/onboardings":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformMaasOnboardings
      summary: List v3 MAAS onboarding workflow runs
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: site_id
        in: query
        schema:
          type: string
          format: uuid
      - name: batch_id
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
      responses:
        '200':
          description: MAAS onboarding workflow runs
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasOnboardingListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/lifecycle/decommissions":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformMaasDecommissions
      summary: List v3 MAAS decommission workflow runs
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: site_id
        in: query
        schema:
          type: string
          format: uuid
      - name: node_id
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
      responses:
        '200':
          description: MAAS decommission workflow runs
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MaasDecommissionListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/resource-slots":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformNodeResourceSlots
      summary: List v3 platform node resource slots
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Node resource slots
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeResourceSlotListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    put:
      tags:
      - V3ReadModels
      operationId: upsertV3PlatformNodeResourceSlots
      summary: Upsert v3 platform node resource slots
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminUpsertNodeResourceSlotsRequest"
      responses:
        '200':
          description: Upserted node resource slots
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeResourceSlotListResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/slice-topology/discovery":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformNodeSliceTopologyDiscovery
      summary: Get v3 platform node slice topology discovery
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Latest topology discovery task, or null when none has run
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3ReadModels
      operationId: startV3PlatformNodeSliceTopologyDiscovery
      summary: Queue v3 platform node slice topology discovery
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '202':
          description: Discovery task queued or already in progress
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/probe":
    post:
      tags:
      - V3ReadModels
      operationId: probeV3PlatformNode
      summary: Probe a v3 platform node
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Probed
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                    enum:
                    - active
                    - offline
                required:
                - ok
                - status
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/reissue-enrollment":
    post:
      tags:
      - V3ReadModels
      operationId: reissueV3PlatformNodeEnrollment
      summary: Reissue v3 platform node enrollment material
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '201':
          description: Re-enrollment material created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminNodeReenrollmentResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/bootstrap-script":
    post:
      tags:
      - V3ReadModels
      operationId: createV3PlatformNodeBootstrapScript
      summary: Create v3 platform node bootstrap material
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      - name: mode
        in: query
        schema:
          type: string
          enum:
          - manual
          - cloud_init
          default: manual
      responses:
        '201':
          description: Bootstrap script created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminNodeBootstrapScriptResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/agent-lifecycle":
    get:
      tags:
      - V3ReadModels
      operationId: getV3PlatformNodeAgentLifecycle
      summary: Get v3 platform node-agent lifecycle state
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Current node-agent lifecycle state
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  node_id:
                    type: string
                    format: uuid
                  state:
                    "$ref": "#/components/schemas/NodeAgentLifecycleState"
                  latest_run:
                    allOf:
                    - "$ref": "#/components/schemas/NodeAgentLifecycleRun"
                    nullable: true
                required:
                - node_id
                - state
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3ReadModels
      operationId: startV3PlatformNodeAgentLifecycle
      summary: Start a v3 platform node-agent lifecycle run
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleRequest"
      responses:
        '202':
          description: Node-agent lifecycle accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/reactivate":
    post:
      tags:
      - V3ReadModels
      operationId: reactivateV3PlatformNode
      summary: Reactivate a retired v3 platform node
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Node reactivated
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                required:
                - ok
                - status
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/resume-lifecycle":
    post:
      tags:
      - V3ReadModels
      operationId: resumeV3PlatformNodeLifecycle
      summary: Resume a v3 platform node lifecycle transition
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '200':
          description: Node lifecycle resume accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminResumeNodeLifecycleResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/remove":
    delete:
      tags:
      - V3ReadModels
      operationId: removeV3PlatformNode
      summary: Permanently remove a retired v3 platform node
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '204':
          description: Node removal started
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/detach":
    delete:
      tags:
      - V3ReadModels
      operationId: detachV3PlatformNode
      summary: Detach a retired v3 platform node from GPUaaS only
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '204':
          description: Node detached from GPUaaS
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/lifecycle/nodes/{node_id}/force-detach":
    delete:
      tags:
      - V3ReadModels
      operationId: forceDetachV3PlatformNode
      summary: Force-detach a stuck v3 platform node from GPUaaS only
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/NodeIdPath"
      responses:
        '204':
          description: Node force-detached from GPUaaS
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/platform/evidence/audit":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformEvidenceAuditLogs
      summary: List v3 platform audit evidence rows
      description: Platform evidence audit drawer feed. This is the V3 platform-owned
        alias for platform audit-log review and supports the same filters as the frozen
        admin audit list while the broader user/project/tenant evidence ownership
        is migrated.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: actor_user_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: actor_role
        in: query
        required: false
        schema:
          type: string
      - name: action
        in: query
        required: false
        schema:
          type: string
      - name: target_type
        in: query
        required: false
        schema:
          type: string
      - name: correlation_id
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: V3 platform audit evidence rows
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuditLogListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/apps/instances/{app_instance_id}":
    get:
      tags:
      - V3Apps
      operationId: getV3AppInstance
      summary: Get V3 app runtime instance
      description: V3 project-scoped alias for app runtime management.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '200':
          description: V3 app runtime instance
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/apps/instances/{app_instance_id}/members":
    get:
      tags:
      - V3Apps
      operationId: listV3AppInstanceMembers
      summary: List V3 app runtime members
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: component_key
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 app runtime members
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMemberListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/apps/instances/{app_instance_id}/member-operations":
    get:
      tags:
      - V3Apps
      operationId: listV3AppInstanceMemberOperations
      summary: List V3 app runtime member operations
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: component_key
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 app runtime member operations
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMemberOperationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3Apps
      operationId: createV3AppInstanceMemberOperation
      summary: Queue a V3 app runtime member operation
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAppInstanceMemberOperationRequest"
      responses:
        '202':
          description: V3 app runtime member operation queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceMemberOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/instances/{app_instance_id}/upgrade":
    post:
      tags:
      - V3Apps
      operationId: upgradeV3AppInstance
      summary: Upgrade a V3 app runtime
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpgradeAppInstanceRequest"
      responses:
        '202':
          description: V3 app runtime upgrade queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/instances/{app_instance_id}/rollback":
    post:
      tags:
      - V3Apps
      operationId: rollbackV3AppInstance
      summary: Roll back a V3 app runtime
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RollbackAppInstanceRequest"
      responses:
        '202':
          description: V3 app runtime rollback queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/instances/{app_instance_id}/stop":
    post:
      tags:
      - V3Apps
      operationId: stopV3AppInstance
      summary: Stop a V3 app runtime
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: V3 app runtime stop queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/instances/{app_instance_id}/start":
    post:
      tags:
      - V3Apps
      operationId: startV3AppInstance
      summary: Start a V3 app runtime
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: V3 app runtime start queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/instances/{app_instance_id}/restart":
    post:
      tags:
      - V3Apps
      operationId: restartV3AppInstance
      summary: Restart a V3 app runtime
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: V3 app runtime restart queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/instances/{app_instance_id}/repair":
    post:
      tags:
      - V3Apps
      operationId: repairV3AppInstance
      summary: Queue V3 app runtime repair
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAppInstanceRepairRequest"
      responses:
        '202':
          description: V3 app runtime repair queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstanceRepairOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/apps/instances/{app_instance_id}/decommission":
    post:
      tags:
      - V3Apps
      operationId: decommissionV3AppInstance
      summary: Decommission a V3 app runtime
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AppInstanceIdPath"
      responses:
        '202':
          description: V3 app runtime decommission queued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AppInstance"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/schedulers/shared-runtimes":
    get:
      tags:
      - V3Schedulers
      operationId: listV3SharedAppRuntimes
      summary: List V3 tenant-shared scheduler runtimes
      description: V3 tenant-scoped alias for tenant-owned shared app runtimes.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: X-Tenant-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 tenant-shared scheduler runtimes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/schedulers/shared-runtimes/{shared_runtime_id}":
    get:
      tags:
      - V3Schedulers
      operationId: getV3SharedAppRuntime
      summary: Get V3 tenant-shared scheduler runtime
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: X-Tenant-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/SharedRuntimeIdPath"
      responses:
        '200':
          description: V3 tenant-shared scheduler runtime
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntime"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/schedulers/shared-runtimes/{shared_runtime_id}/attachments":
    get:
      tags:
      - V3Schedulers
      operationId: listV3SharedAppRuntimeAttachments
      summary: List V3 tenant-shared runtime project attachments
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: X-Tenant-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/SharedRuntimeIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 tenant-shared runtime attachments
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeAttachmentListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/schedulers/shared-runtimes/{shared_runtime_id}/workers":
    get:
      tags:
      - V3Schedulers
      operationId: listV3SharedAppRuntimeWorkers
      summary: List V3 tenant-shared runtime workers
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: X-Tenant-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/SharedRuntimeIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 tenant-shared runtime workers
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/schedulers/shared-runtimes/{shared_runtime_id}/worker-operations":
    get:
      tags:
      - V3Schedulers
      operationId: listV3SharedAppRuntimeWorkerOperations
      summary: List V3 tenant-shared runtime worker operations
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: X-Tenant-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/SharedRuntimeIdPath"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 tenant-shared runtime worker operations
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3Schedulers
      operationId: createV3SharedAppRuntimeWorkerOperation
      summary: Request a V3 tenant-shared runtime worker lifecycle change
      description: |
        Tenant operators request worker lifecycle changes through the V3 scheduler
        workbench. The operation is consumed by the shared-runtime operator contract.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: X-Tenant-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SharedRuntimeIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest"
      responses:
        '202':
          description: V3 shared runtime worker operation accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/developer/releases":
    get:
      tags:
      - V3Developer
      operationId: listV3DeveloperReleases
      summary: List V3 developer-downloadable platform releases
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: V3 platform release catalog
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatformReleaseListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/developer/releases/{version}":
    get:
      tags:
      - V3Developer
      operationId: getV3DeveloperRelease
      summary: Get a V3 developer platform release manifest
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: version
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: V3 platform release manifest
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatformRelease"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/developer/releases/{version}/artifacts/{artifact_id}/download":
    get:
      tags:
      - V3Developer
      operationId: downloadV3DeveloperReleaseArtifact
      summary: Download a V3 developer platform release artifact
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: version
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: artifact_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Artifact archive
          content:
            application/gzip:
              schema:
                type: string
                format: binary
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/developer/releases/{version}/artifacts/{artifact_id}/pull-intent":
    post:
      tags:
      - V3Developer
      operationId: createV3DeveloperReleaseArtifactPullIntent
      summary: Issue a V3 developer platform release artifact pull intent
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: version
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: artifact_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '201':
          description: V3 platform release artifact pull intent issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ArtifactPullIntent"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/developer/dev-ca":
    get:
      tags:
      - V3Developer
      operationId: getV3DeveloperDevCA
      summary: Get V3 platform-control dev CA download metadata
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: Platform-control dev CA metadata
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatformDevCA"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/developer/dev-ca/download":
    get:
      tags:
      - V3Developer
      operationId: downloadV3DeveloperDevCA
      summary: Download the V3 platform-control dev CA certificate
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      responses:
        '200':
          description: PEM-encoded CA certificate
          content:
            application/x-x509-ca-cert:
              schema:
                type: string
                format: binary
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/ops/outbox/failed":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformOpsFailedOutboxEvents
      summary: List failed outbox events for the V3 platform ops workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: cursor
        in: query
        schema:
          type: string
      - name: page_size
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
      responses:
        '200':
          description: Failed outbox events
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminOutboxFailedListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/ops/outbox/{event_id}/requeue":
    post:
      tags:
      - V3ReadModels
      operationId: requeueV3PlatformOpsOutboxEvent
      summary: Requeue a failed outbox event from the V3 platform ops workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Outbox event requeued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminOutboxMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/ops/outbox/{event_id}/discard":
    post:
      tags:
      - V3ReadModels
      operationId: discardV3PlatformOpsOutboxEvent
      summary: Discard a failed outbox event from the V3 platform ops workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Outbox event discarded
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminOutboxMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/ops/dlq/messages":
    get:
      tags:
      - V3ReadModels
      operationId: listV3PlatformOpsDLQMessages
      summary: List DLQ stream messages for the V3 platform ops workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: cursor
        in: query
        schema:
          type: string
      - name: page_size
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: subject_prefix
        in: query
        schema:
          type: string
        description: Optional DLQ subject prefix filter, for example dlq.provisioning.
      responses:
        '200':
          description: DLQ messages page
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminDLQMessageListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/ops/dlq/messages/{stream_seq}/requeue":
    post:
      tags:
      - V3ReadModels
      operationId: requeueV3PlatformOpsDLQMessage
      summary: Requeue a DLQ message from the V3 platform ops workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: stream_seq
        in: path
        required: true
        schema:
          type: integer
          format: uint64
          minimum: 1
      responses:
        '200':
          description: DLQ message requeued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminDLQMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/ops/dlq/messages/{stream_seq}/discard":
    post:
      tags:
      - V3ReadModels
      operationId: discardV3PlatformOpsDLQMessage
      summary: Discard a DLQ message from the V3 platform ops workbench
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: stream_seq
        in: path
        required: true
        schema:
          type: integer
          format: uint64
          minimum: 1
      responses:
        '200':
          description: DLQ message discarded
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminDLQMutationResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '503':
          "$ref": "#/components/responses/ServiceUnavailable"
  "/api/v1/v3/platform/finance/reconciliation":
    get:
      tags:
      - V3PlatformFinance
      operationId: listV3PlatformFinanceReconciliation
      summary: List billing reconciliation runs through the V3 finance boundary
      description: Lists usage-ledger reconciliation posture and recent runs for the
        operator finance workbench.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      responses:
        '200':
          description: V3 finance billing reconciliation posture
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BillingReconciliationListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
    post:
      tags:
      - V3PlatformFinance
      operationId: runV3PlatformFinanceReconciliation
      summary: Run usage-ledger reconciliation through the V3 finance boundary
      description: Starts an audited, idempotent reconciliation run for finance operators.
        Ledger corrections remain append-only and are not performed directly by this
        read-model action.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/IdempotencyKey"
      responses:
        '202':
          description: V3 finance billing reconciliation completed and recorded
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BillingReconciliationRun"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/finance/reconciliation/{job_id}":
    get:
      tags:
      - V3PlatformFinance
      operationId: getV3PlatformFinanceReconciliation
      summary: Get a billing reconciliation run through the V3 finance boundary
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: V3 finance billing reconciliation run
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BillingReconciliationRun"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/api/v1/v3/platform/finance/diagnostics":
    get:
      tags:
      - V3PlatformFinance
      operationId: getV3PlatformFinanceDiagnostics
      summary: Fetch billing evidence by correlation id through the V3 finance boundary
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: correlation_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: V3 finance billing diagnostic evidence
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BillingDiagnosticsResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/platform/ops/telemetry/fleet":
    get:
      tags:
      - V3PlatformOps
      operationId: getV3PlatformOpsFleetTelemetry
      summary: Get fleet telemetry rollups through the V3 ops boundary
      description: Read-only fleet telemetry subworkbench for platform operators.
        Returns CPU, GPU, memory, storage, and tenant/project rollups over a bounded
        window.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: range
        in: query
        required: false
        schema:
          type: string
          enum:
          - 15m
          - 1h
          - 6h
          - 24h
      - name: points
        in: query
        required: false
        schema:
          type: integer
          minimum: 10
          maximum: 240
      responses:
        '200':
          description: V3 ops fleet telemetry snapshot
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AdminFleetTelemetryResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/allocations/{allocation_id}/access-grants":
    get:
      tags:
      - V3Workloads
      operationId: listV3AllocationAccessGrants
      summary: List V3 allocation SSH access grants
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/AllocationIdPath"
      responses:
        '200':
          description: V3 allocation access grants
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AllocationAccessGrantListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
    post:
      tags:
      - V3Workloads
      operationId: createV3AllocationAccessGrant
      summary: Grant V3 allocation SSH access to a project member
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAllocationAccessGrantRequest"
      responses:
        '201':
          description: V3 allocation access grant created or updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateAllocationAccessGrantResponse"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/allocations/{allocation_id}/access-grants/{grant_id}":
    delete:
      tags:
      - V3Workloads
      operationId: revokeV3AllocationAccessGrant
      summary: Revoke a V3 allocation SSH access grant
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      - name: grant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: V3 allocation access grant revoked
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RevokeAllocationAccessGrantResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/allocations/{allocation_id}/ssh-keys":
    put:
      tags:
      - V3Workloads
      operationId: setV3AllocationSshKeys
      summary: Set V3 allocation owner SSH keys
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/AllocationIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SetAllocationSshKeysRequest"
      responses:
        '200':
          description: V3 allocation SSH keys updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Allocation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/schedulers/shared-runtime-attachments/{attachment_id}/worker-operations":
    post:
      tags:
      - V3Schedulers
      operationId: createV3ProjectSharedRuntimeWorkerOperation
      summary: Request V3 project worker contribution for an attached shared runtime
      description: |
        Consumer projects use this V3 path to request add, drain, or remove
        operations against a tenant-shared runtime attachment. The platform
        resolves tenant ownership and enforces the attachment contribution policy.
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/IdempotencyKey"
      - "$ref": "#/components/parameters/SharedRuntimeAttachmentIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest"
      responses:
        '202':
          description: V3 project shared runtime worker operation accepted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation"
        '400':
          "$ref": "#/components/responses/BadRequest"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '409':
          "$ref": "#/components/responses/Conflict"
  "/api/v1/v3/account/evidence/audit":
    get:
      tags:
      - V3Account
      operationId: listV3AccountEvidenceAuditLogs
      summary: List V3 account-scoped audit evidence
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: action
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 account audit evidence
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuditLogListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/api/v1/v3/project/evidence/audit":
    get:
      tags:
      - V3Project
      operationId: listV3ProjectEvidenceAuditLogs
      summary: List V3 current-project audit evidence
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - "$ref": "#/components/parameters/ProjectIdHeader"
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: action
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 project audit evidence
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuditLogListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
  "/api/v1/v3/access/evidence/audit":
    get:
      tags:
      - V3Access
      operationId: listV3TenantEvidenceAuditLogs
      summary: List V3 tenant-scoped audit evidence
      parameters:
      - "$ref": "#/components/parameters/XRequestId"
      - name: X-Tenant-ID
        in: header
        required: false
        schema:
          type: string
          format: uuid
      - "$ref": "#/components/parameters/Cursor"
      - "$ref": "#/components/parameters/PageSize"
      - name: action
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: V3 tenant audit evidence
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuditLogListResponse"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
x-notes:
  secure_key_download:
    rule: Use Authorization header for key retrieval; do not place auth tokens in
      query strings.
  pagination:
    rule: All V3 list endpoints support cursor/page_size and return a pagination block
      with next_cursor and page_size. User-facing V3 surfaces must not render unbounded
      tables by default; if a response is already bounded and complete, the UI may
      use a documented show-more cap instead of requesting another cursor page.
