components:
  schemas:
    dto.AnnotationResponse:
      properties:
        created_at:
          type: string
        id:
          type: string
        key:
          type: string
        organization_id:
          type: string
        updated_at:
          type: string
        value:
          type: string
      type: object
    dto.AttachAnnotationsRequest:
      properties:
        annotation_ids:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    dto.AttachBastionRequest:
      properties:
        server_id:
          type: string
      type: object
    dto.AttachCaptainDomainRequest:
      properties:
        domain_id:
          type: string
      type: object
    dto.AttachLabelsRequest:
      properties:
        label_ids:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    dto.AttachLoadBalancerRequest:
      properties:
        load_balancer_id:
          type: string
      type: object
    dto.AttachRecordSetRequest:
      properties:
        record_set_id:
          type: string
      type: object
    dto.AttachServersRequest:
      properties:
        server_ids:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    dto.AttachTaintsRequest:
      properties:
        taint_ids:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    dto.AuthStartResponse:
      properties:
        auth_url:
          example: https://accounts.google.com/o/oauth2/v2/auth?client_id=...
          type: string
      type: object
    dto.ClusterResponse:
      properties:
        apps_load_balancer:
          $ref: '#/components/schemas/dto.LoadBalancerResponse'
        bastion_server:
          $ref: '#/components/schemas/dto.ServerResponse'
        captain_domain:
          $ref: '#/components/schemas/dto.DomainResponse'
        certificate_key:
          type: string
        control_plane_record_set:
          $ref: '#/components/schemas/dto.RecordSetResponse'
        created_at:
          type: string
        glueops_load_balancer:
          $ref: '#/components/schemas/dto.LoadBalancerResponse'
        id:
          type: string
        last_error:
          type: string
        name:
          type: string
        node_pools:
          items:
            $ref: '#/components/schemas/dto.NodePoolResponse'
          type: array
          uniqueItems: false
        provider:
          type: string
        random_token:
          type: string
        region:
          type: string
        status:
          type: string
        updated_at:
          type: string
      type: object
    dto.CreateAnnotationRequest:
      properties:
        key:
          type: string
        value:
          type: string
      type: object
    dto.CreateClusterRequest:
      properties:
        name:
          type: string
        provider:
          type: string
        region:
          type: string
      type: object
    dto.CreateCredentialRequest:
      properties:
        account_id:
          maxLength: 32
          type: string
        kind:
          description: aws_access_key, api_token, basic_auth, oauth2
          type: string
        name:
          description: human label
          maxLength: 100
          type: string
        provider:
          enum:
          - aws
          - cloudflare
          - hetzner
          - digitalocean
          - generic
          type: string
        region:
          maxLength: 32
          type: string
        schema_version:
          description: secret schema version
          minimum: 1
          type: integer
        scope:
          description: '{"service":"route53"} or {"arn":"..."}'
          type: object
        scope_kind:
          enum:
          - provider
          - service
          - resource
          type: string
        scope_version:
          description: scope schema version
          minimum: 1
          type: integer
        secret:
          description: encrypted later
          type: object
      required:
      - kind
      - provider
      - schema_version
      - scope
      - scope_kind
      - scope_version
      - secret
      type: object
    dto.CreateDomainRequest:
      properties:
        credential_id:
          type: string
        domain_name:
          type: string
        zone_id:
          maxLength: 128
          type: string
      required:
      - credential_id
      - domain_name
      type: object
    dto.CreateLabelRequest:
      properties:
        key:
          type: string
        value:
          type: string
      type: object
    dto.CreateLoadBalancerRequest:
      properties:
        kind:
          enum:
          - glueops
          - public
          example: public
          type: string
        name:
          example: glueops
          type: string
        private_ip_address:
          example: 192.168.0.2
          type: string
        public_ip_address:
          example: 8.8.8.8
          type: string
      type: object
    dto.CreateNodePoolRequest:
      properties:
        name:
          type: string
        role:
          enum:
          - master
          - worker
          type: string
      type: object
    dto.CreateRecordSetRequest:
      properties:
        name:
          description: |-
            Name relative to domain ("endpoint") OR FQDN ("endpoint.example.com").
            Server normalizes to relative.
          maxLength: 253
          type: string
        ttl:
          maximum: 86400
          minimum: 1
          type: integer
        type:
          type: string
        values:
          items:
            type: string
          type: array
          uniqueItems: false
      required:
      - name
      - type
      type: object
    dto.CreateSSHRequest:
      properties:
        bits:
          description: Only for RSA
          type: integer
        comment:
          example: deploy@autoglue
          type: string
        name:
          type: string
        type:
          description: '"rsa" (default) or "ed25519"'
          type: string
      type: object
    dto.CreateServerRequest:
      properties:
        hostname:
          type: string
        private_ip_address:
          type: string
        public_ip_address:
          type: string
        role:
          enum:
          - master
          - worker
          - bastion
          example: master|worker|bastion
          type: string
        ssh_key_id:
          type: string
        ssh_user:
          type: string
        status:
          enum:
          - pending
          - provisioning
          - ready
          - failed
          example: pending|provisioning|ready|failed
          type: string
      type: object
    dto.CreateTaintRequest:
      properties:
        effect:
          type: string
        key:
          type: string
        value:
          type: string
      type: object
    dto.CredentialOut:
      properties:
        account_id:
          type: string
        created_at:
          type: string
        id:
          type: string
        kind:
          type: string
        name:
          type: string
        provider:
          type: string
        region:
          type: string
        schema_version:
          type: integer
        scope:
          type: object
        scope_kind:
          type: string
        scope_version:
          type: integer
        updated_at:
          type: string
      type: object
    dto.DomainResponse:
      properties:
        created_at:
          type: string
        credential_id:
          type: string
        domain_name:
          type: string
        id:
          type: string
        last_error:
          type: string
        organization_id:
          type: string
        status:
          type: string
        updated_at:
          type: string
        zone_id:
          type: string
      type: object
    dto.EnqueueRequest:
      properties:
        payload:
          type: object
        queue:
          example: default
          type: string
        run_at:
          example: "2025-11-05T08:00:00Z"
          type: string
        type:
          example: email.send
          type: string
      type: object
    dto.JWK:
      properties:
        alg:
          example: RS256
          type: string
        e:
          example: AQAB
          type: string
        kid:
          example: 7c6f1d0a-7a98-4e6a-9dbf-6b1af4b9f345
          type: string
        kty:
          example: RSA
          type: string
        "n":
          type: string
        use:
          example: sig
          type: string
        x:
          type: string
      type: object
    dto.JWKS:
      properties:
        keys:
          items:
            $ref: '#/components/schemas/dto.JWK'
          type: array
          uniqueItems: false
      type: object
    dto.Job:
      properties:
        attempts:
          example: 0
          type: integer
        created_at:
          example: "2025-11-04T09:30:00Z"
          type: string
        id:
          example: 01HF7SZK8Z8WG1M3J7S2Z8M2N6
          type: string
        last_error:
          example: error message
          type: string
        max_attempts:
          example: 3
          type: integer
        payload: {}
        queue:
          example: default
          type: string
        run_at:
          example: "2025-11-04T09:30:00Z"
          type: string
        status:
          $ref: '#/components/schemas/dto.JobStatus'
        type:
          example: email.send
          type: string
        updated_at:
          example: "2025-11-04T09:30:00Z"
          type: string
      type: object
    dto.JobStatus:
      enum:
      - queued|running|succeeded|failed|canceled|retrying|scheduled
      example: queued
      type: string
      x-enum-varnames:
      - StatusQueued
      - StatusRunning
      - StatusSucceeded
      - StatusFailed
      - StatusCanceled
      - StatusRetrying
      - StatusScheduled
    dto.LabelResponse:
      properties:
        created_at:
          type: string
        id:
          type: string
        key:
          type: string
        organization_id:
          type: string
        updated_at:
          type: string
        value:
          type: string
      type: object
    dto.LoadBalancerResponse:
      properties:
        created_at:
          type: string
        id:
          type: string
        kind:
          type: string
        name:
          type: string
        organization_id:
          type: string
        private_ip_address:
          type: string
        public_ip_address:
          type: string
        updated_at:
          type: string
      type: object
    dto.LogoutRequest:
      properties:
        refresh_token:
          example: m0l9o8rT3t0V8d3eFf...
          type: string
      type: object
    dto.NodePoolResponse:
      properties:
        annotations:
          items:
            $ref: '#/components/schemas/dto.AnnotationResponse'
          type: array
          uniqueItems: false
        created_at:
          type: string
        id:
          type: string
        labels:
          items:
            $ref: '#/components/schemas/dto.LabelResponse'
          type: array
          uniqueItems: false
        name:
          type: string
        organization_id:
          type: string
        role:
          enum:
          - master
          - worker
          type: string
        servers:
          items:
            $ref: '#/components/schemas/dto.ServerResponse'
          type: array
          uniqueItems: false
        taints:
          items:
            $ref: '#/components/schemas/dto.TaintResponse'
          type: array
          uniqueItems: false
        updated_at:
          type: string
      type: object
    dto.PageJob:
      properties:
        items:
          items:
            $ref: '#/components/schemas/dto.Job'
          type: array
          uniqueItems: false
        page:
          example: 1
          type: integer
        page_size:
          example: 25
          type: integer
        total:
          example: 120
          type: integer
      type: object
    dto.QueueInfo:
      properties:
        failed:
          example: 5
          type: integer
        name:
          example: default
          type: string
        pending:
          example: 42
          type: integer
        running:
          example: 3
          type: integer
        scheduled:
          example: 7
          type: integer
      type: object
    dto.RecordSetResponse:
      properties:
        created_at:
          type: string
        domain_id:
          type: string
        fingerprint:
          type: string
        id:
          type: string
        last_error:
          type: string
        name:
          type: string
        owner:
          type: string
        status:
          type: string
        ttl:
          type: integer
        type:
          type: string
        updated_at:
          type: string
        values:
          description: '[]string JSON'
          type: object
      type: object
    dto.RefreshRequest:
      properties:
        refresh_token:
          example: m0l9o8rT3t0V8d3eFf...
          type: string
      type: object
    dto.ServerResponse:
      properties:
        created_at:
          type: string
        hostname:
          type: string
        id:
          type: string
        organization_id:
          type: string
        private_ip_address:
          type: string
        public_ip_address:
          type: string
        role:
          enum:
          - master
          - worker
          - bastion
          example: master|worker|bastion
          type: string
        ssh_key_id:
          type: string
        ssh_user:
          type: string
        status:
          enum:
          - pending
          - provisioning
          - ready
          - failed
          example: pending|provisioning|ready|failed
          type: string
        updated_at:
          type: string
      type: object
    dto.SetKubeconfigRequest:
      properties:
        kubeconfig:
          type: string
      type: object
    dto.SshResponse:
      properties:
        created_at:
          type: string
        fingerprint:
          type: string
        id:
          type: string
        name:
          type: string
        organization_id:
          type: string
        public_key:
          type: string
        updated_at:
          type: string
      type: object
    dto.SshRevealResponse:
      properties:
        created_at:
          type: string
        fingerprint:
          type: string
        id:
          type: string
        name:
          type: string
        organization_id:
          type: string
        private_key:
          type: string
        public_key:
          type: string
        updated_at:
          type: string
      type: object
    dto.TaintResponse:
      properties:
        created_at:
          type: string
        effect:
          type: string
        id:
          type: string
        key:
          type: string
        organization_id:
          type: string
        updated_at:
          type: string
        value:
          type: string
      type: object
    dto.TokenPair:
      properties:
        access_token:
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ij...
          type: string
        expires_in:
          example: 3600
          type: integer
        refresh_token:
          example: m0l9o8rT3t0V8d3eFf....
          type: string
        token_type:
          example: Bearer
          type: string
      type: object
    dto.UpdateAnnotationRequest:
      properties:
        key:
          type: string
        value:
          type: string
      type: object
    dto.UpdateClusterRequest:
      properties:
        name:
          type: string
        provider:
          type: string
        region:
          type: string
      type: object
    dto.UpdateCredentialRequest:
      properties:
        account_id:
          type: string
        name:
          type: string
        region:
          type: string
        scope:
          type: object
        scope_kind:
          type: string
        scope_version:
          type: integer
        secret:
          description: set if rotating
          type: object
      type: object
    dto.UpdateDomainRequest:
      properties:
        credential_id:
          type: string
        domain_name:
          type: string
        status:
          enum:
          - pending
          - provisioning
          - ready
          - failed
          type: string
        zone_id:
          maxLength: 128
          type: string
      type: object
    dto.UpdateLabelRequest:
      properties:
        key:
          type: string
        value:
          type: string
      type: object
    dto.UpdateLoadBalancerRequest:
      properties:
        kind:
          enum:
          - glueops
          - public
          example: public
          type: string
        name:
          example: glue
          type: string
        private_ip_address:
          example: 192.168.0.2
          type: string
        public_ip_address:
          example: 8.8.8.8
          type: string
      type: object
    dto.UpdateNodePoolRequest:
      properties:
        name:
          type: string
        role:
          enum:
          - master
          - worker
          type: string
      type: object
    dto.UpdateRecordSetRequest:
      properties:
        name:
          description: Any change flips status back to pending (worker will UPSERT)
          maxLength: 253
          type: string
        status:
          enum:
          - pending
          - provisioning
          - ready
          - failed
          type: string
        ttl:
          maximum: 86400
          minimum: 1
          type: integer
        type:
          type: string
        values:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    dto.UpdateServerRequest:
      properties:
        hostname:
          type: string
        private_ip_address:
          type: string
        public_ip_address:
          type: string
        role:
          enum:
          - master
          - worker
          - bastion
          example: master|worker|bastion
          type: string
        ssh_key_id:
          type: string
        ssh_user:
          type: string
        status:
          enum:
          - pending
          - provisioning
          - ready
          - failed
          example: pending|provisioning|ready|failed
          type: string
      type: object
    dto.UpdateTaintRequest:
      properties:
        effect:
          type: string
        key:
          type: string
        value:
          type: string
      type: object
    handlers.HealthStatus:
      properties:
        status:
          example: ok
          type: string
      type: object
    handlers.VersionResponse:
      properties:
        built:
          example: "2025-11-08T12:34:56Z"
          type: string
        builtBy:
          example: ci
          type: string
        commit:
          example: a1b2c3d
          type: string
        commitTime:
          example: "2025-11-08T12:31:00Z"
          type: string
        go:
          example: go1.23.3
          type: string
        goArch:
          example: amd64
          type: string
        goOS:
          example: linux
          type: string
        modified:
          example: false
          type: boolean
        revision:
          example: a1b2c3d4e5f6abcdef
          type: string
        vcs:
          example: git
          type: string
        version:
          example: 1.4.2
          type: string
      type: object
    handlers.createUserKeyRequest:
      properties:
        expires_in_hours:
          description: optional TTL
          type: integer
        name:
          type: string
      type: object
    handlers.meResponse:
      properties:
        avatar_url:
          type: string
        created_at:
          format: date-time
          type: string
        display_name:
          type: string
        emails:
          items:
            $ref: '#/components/schemas/models.UserEmail'
          type: array
          uniqueItems: false
        id:
          description: 'example: 3fa85f64-5717-4562-b3fc-2c963f66afa6'
          format: uuid
          type: string
        is_admin:
          type: boolean
        is_disabled:
          type: boolean
        organizations:
          items:
            $ref: '#/components/schemas/models.Organization'
          type: array
          uniqueItems: false
        primary_email:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    handlers.memberOut:
      properties:
        email:
          type: string
        role:
          description: owner/admin/member
          type: string
        user_id:
          format: uuid
          type: string
      type: object
    handlers.memberUpsertReq:
      properties:
        role:
          example: member
          type: string
        user_id:
          format: uuid
          type: string
      type: object
    handlers.orgCreateReq:
      properties:
        domain:
          example: acme.com
          type: string
        name:
          example: Acme Corp
          type: string
      type: object
    handlers.orgKeyCreateReq:
      properties:
        expires_in_hours:
          example: 720
          type: integer
        name:
          example: automation-bot
          type: string
      type: object
    handlers.orgKeyCreateResp:
      properties:
        created_at:
          type: string
        expires_at:
          type: string
        id:
          type: string
        name:
          type: string
        org_key:
          description: 'shown once:'
          type: string
        org_secret:
          description: 'shown once:'
          type: string
        scope:
          description: '"org"'
          type: string
      type: object
    handlers.orgUpdateReq:
      properties:
        domain:
          type: string
        name:
          type: string
      type: object
    handlers.updateMeRequest:
      properties:
        display_name:
          type: string
      type: object
    handlers.userAPIKeyOut:
      properties:
        created_at:
          type: string
        expires_at:
          type: string
        id:
          format: uuid
          type: string
        last_used_at:
          type: string
        name:
          type: string
        plain:
          description: 'Shown only on create:'
          type: string
        scope:
          description: '"user"'
          type: string
      type: object
    models.APIKey:
      properties:
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        last_used_at:
          format: date-time
          type: string
        name:
          type: string
        org_id:
          format: uuid
          type: string
        prefix:
          type: string
        revoked:
          type: boolean
        scope:
          type: string
        updated_at:
          format: date-time
          type: string
        user_id:
          format: uuid
          type: string
      type: object
    models.Organization:
      properties:
        created_at:
          format: date-time
          type: string
        domain:
          type: string
        id:
          description: 'example: 3fa85f64-5717-4562-b3fc-2c963f66afa6'
          format: uuid
          type: string
        name:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    models.User:
      properties:
        avatar_url:
          type: string
        created_at:
          format: date-time
          type: string
        display_name:
          type: string
        id:
          description: 'example: 3fa85f64-5717-4562-b3fc-2c963f66afa6'
          format: uuid
          type: string
        is_admin:
          type: boolean
        is_disabled:
          type: boolean
        primary_email:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    models.UserEmail:
      properties:
        created_at:
          format: date-time
          type: string
        email:
          type: string
        id:
          description: 'example: 3fa85f64-5717-4562-b3fc-2c963f66afa6'
          format: uuid
          type: string
        is_primary:
          type: boolean
        is_verified:
          type: boolean
        updated_at:
          format: date-time
          type: string
        user:
          $ref: '#/components/schemas/models.User'
        user_id:
          format: uuid
          type: string
      type: object
    utils.ErrorResponse:
      properties:
        code:
          description: |-
            A machine-readable error code, e.g. "validation_error"
            example: validation_error
          type: string
        message:
          description: |-
            Human-readable message
            example: slug is required
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: User API key
      in: header
      name: X-API-KEY
      type: apiKey
    BearerAuth:
      description: Bearer token authentication
      in: header
      name: Authorization
      type: apiKey
    OrgKeyAuth:
      description: Org-level key/secret authentication
      in: header
      name: X-ORG-KEY
      type: apiKey
    OrgSecretAuth:
      description: Org-level secret
      in: header
      name: X-ORG-SECRET
      type: apiKey
externalDocs:
  description: ""
  url: ""
info:
  contact:
    name: GlueOps
  description: API for managing K3s clusters across cloud providers
  title: AutoGlue API
  version: "1.0"
openapi: 3.1.0
paths:
  /.well-known/jwks.json:
    get:
      description: Returns the JSON Web Key Set for token verification
      operationId: getJWKS
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.JWKS'
          description: OK
      summary: Get JWKS
      tags:
      - Auth
  /admin/archer/jobs:
    get:
      description: Paginated background jobs with optional filters. Search `q` may
        match id, type, error, payload (implementation-dependent).
      operationId: AdminListArcherJobs
      parameters:
      - description: Filter by status
        in: query
        name: status
        schema:
          enum:
          - queued
          - running
          - succeeded
          - failed
          - canceled
          - retrying
          - scheduled
          type: string
      - description: Filter by queue name / worker name
        in: query
        name: queue
        schema:
          type: string
      - description: Free-text search
        in: query
        name: q
        schema:
          type: string
      - description: Page number
        in: query
        name: page
        schema:
          default: 1
          type: integer
      - description: Items per page
        in: query
        name: page_size
        schema:
          default: 25
          maximum: 100
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.PageJob'
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: forbidden
        "500":
          content:
            application/json:
              schema:
                type: string
          description: internal error
      security:
      - BearerAuth: []
      summary: List Archer jobs (admin)
      tags:
      - ArcherAdmin
    post:
      description: Create a job immediately or schedule it for the future via `run_at`.
      operationId: AdminEnqueueArcherJob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.EnqueueRequest'
        description: Job parameters
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.Job'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid json or missing fields
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: forbidden
        "500":
          content:
            application/json:
              schema:
                type: string
          description: internal error
      security:
      - BearerAuth: []
      summary: Enqueue a new Archer job (admin)
      tags:
      - ArcherAdmin
  /admin/archer/jobs/{id}/cancel:
    post:
      description: Set job status to canceled if cancellable. For running jobs, this
        only affects future picks; wire to Archer if you need active kill.
      operationId: AdminCancelArcherJob
      parameters:
      - description: Job ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.Job'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid job or not cancellable
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: forbidden
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      summary: Cancel an Archer job (admin)
      tags:
      - ArcherAdmin
  /admin/archer/jobs/{id}/retry:
    post:
      description: Marks the job retriable (DB flip). Swap this for an Archer admin
        call if you expose one.
      operationId: AdminRetryArcherJob
      parameters:
      - description: Job ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.Job'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid job or not eligible
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: forbidden
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      summary: Retry a failed/canceled Archer job (admin)
      tags:
      - ArcherAdmin
  /admin/archer/queues:
    get:
      description: Summary metrics per queue (pending, running, failed, scheduled).
      operationId: AdminListArcherQueues
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.QueueInfo'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: forbidden
        "500":
          content:
            application/json:
              schema:
                type: string
          description: internal error
      security:
      - BearerAuth: []
      summary: List Archer queues (admin)
      tags:
      - ArcherAdmin
  /annotations:
    get:
      description: 'Returns annotations for the organization in X-Org-ID. Filters:
        `key`, `value`, and `q` (key contains). Add `include=node_pools` to include
        linked node pools.'
      operationId: ListAnnotations
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Exact key
        in: query
        name: key
        schema:
          type: string
      - description: Exact value
        in: query
        name: value
        schema:
          type: string
      - description: key contains (case-insensitive)
        in: query
        name: q
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.AnnotationResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list annotations
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List annotations (org scoped)
      tags:
      - Annotations
    post:
      description: Creates an annotation.
      operationId: CreateAnnotation
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateAnnotationRequest'
        description: Annotation payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.AnnotationResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid json / missing fields
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: create failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create annotation (org scoped)
      tags:
      - Annotations
  /annotations/{id}:
    delete:
      description: Permanently deletes the annotation.
      operationId: DeleteAnnotation
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Annotation ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: delete failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete annotation (org scoped)
      tags:
      - Annotations
    get:
      description: Returns one annotation. Add `include=node_pools` to include node
        pools.
      operationId: GetAnnotation
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Annotation ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.AnnotationResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get annotation by ID (org scoped)
      tags:
      - Annotations
    patch:
      description: Partially update annotation fields.
      operationId: UpdateAnnotation
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Annotation ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateAnnotationRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.AnnotationResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid json
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: update failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update annotation (org scoped)
      tags:
      - Annotations
  /auth/{provider}/callback:
    get:
      operationId: AuthCallback
      parameters:
      - description: google|github
        in: path
        name: provider
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.TokenPair'
          description: OK
      summary: Handle social login callback
      tags:
      - Auth
  /auth/{provider}/start:
    post:
      description: Returns provider authorization URL for the frontend to redirect
      operationId: AuthStart
      parameters:
      - description: google|github
        in: path
        name: provider
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.AuthStartResponse'
          description: OK
      summary: Begin social login
      tags:
      - Auth
  /auth/logout:
    post:
      operationId: Logout
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.LogoutRequest'
        description: Refresh token
        required: true
      responses:
        "204":
          description: No Content
      summary: Revoke refresh token family (logout everywhere)
      tags:
      - Auth
  /auth/refresh:
    post:
      operationId: Refresh
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.RefreshRequest'
        description: Refresh token
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.TokenPair'
          description: OK
      summary: Rotate refresh token
      tags:
      - Auth
  /clusters:
    get:
      description: Returns clusters for the organization in X-Org-ID. Filter by `q`
        (name contains).
      operationId: ListClusters
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Name contains (case-insensitive)
        in: query
        name: q
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.ClusterResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list clusters
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List clusters (org scoped)
      tags:
      - Clusters
    post:
      description: Creates a cluster. Status is managed by the system and starts as
        `pre_pending` for validation.
      operationId: CreateCluster
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateClusterRequest'
        description: payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid json
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: create failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create cluster (org scoped)
      tags:
      - Clusters
  /clusters/{clusterID}:
    delete:
      description: Deletes the cluster. Related resources are cleaned up via DB constraints
        (e.g. CASCADE).
      operationId: DeleteCluster
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: deleted
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete a cluster (org scoped)
      tags:
      - Clusters
    get:
      description: Returns a cluster with all related resources (domain, record set,
        load balancers, bastion, node pools).
      operationId: GetCluster
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get a single cluster by ID (org scoped)
      tags:
      - Clusters
    patch:
      description: Updates the cluster name, provider, and/or region. Status is managed
        by the system.
      operationId: UpdateCluster
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateClusterRequest'
        description: payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update basic cluster details (org scoped)
      tags:
      - Clusters
  /clusters/{clusterID}/apps-load-balancer:
    delete:
      description: Clears apps_load_balancer_id on the cluster.
      operationId: DetachAppsLoadBalancer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach the apps load balancer from a cluster
      tags:
      - Clusters
    post:
      description: Sets apps_load_balancer_id on the cluster.
      operationId: AttachAppsLoadBalancer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachLoadBalancerRequest'
        description: payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster or load balancer not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach an apps load balancer to a cluster
      tags:
      - Clusters
  /clusters/{clusterID}/bastion:
    delete:
      description: Clears bastion_server_id on the cluster.
      operationId: DetachBastionServer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach the bastion server from a cluster
      tags:
      - Clusters
    post:
      description: Sets bastion_server_id on the cluster.
      operationId: AttachBastionServer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachBastionRequest'
        description: payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster or server not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach a bastion server to a cluster
      tags:
      - Clusters
  /clusters/{clusterID}/captain-domain:
    delete:
      description: Clears captain_domain_id on the cluster. This will likely cause
        the cluster to become incomplete.
      operationId: DetachCaptainDomain
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach the captain domain from a cluster
      tags:
      - Clusters
    post:
      description: Sets captain_domain_id on the cluster. Validation of shape happens
        asynchronously.
      operationId: AttachCaptainDomain
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachCaptainDomainRequest'
        description: payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster or domain not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach a captain domain to a cluster
      tags:
      - Clusters
  /clusters/{clusterID}/control-plane-record-set:
    delete:
      description: Clears control_plane_record_set_id on the cluster.
      operationId: DetachControlPlaneRecordSet
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach the control plane record set from a cluster
      tags:
      - Clusters
    post:
      description: Sets control_plane_record_set_id on the cluster.
      operationId: AttachControlPlaneRecordSet
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachRecordSetRequest'
        description: payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster or record set not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach a control plane record set to a cluster
      tags:
      - Clusters
  /clusters/{clusterID}/glueops-load-balancer:
    delete:
      description: Clears glueops_load_balancer_id on the cluster.
      operationId: DetachGlueOpsLoadBalancer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach the GlueOps/control-plane load balancer from a cluster
      tags:
      - Clusters
    post:
      description: Sets glueops_load_balancer_id on the cluster.
      operationId: AttachGlueOpsLoadBalancer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachLoadBalancerRequest'
        description: payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster or load balancer not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach a GlueOps/control-plane load balancer to a cluster
      tags:
      - Clusters
  /clusters/{clusterID}/kubeconfig:
    delete:
      description: Removes the encrypted kubeconfig, IV, and tag from the cluster
        record.
      operationId: ClearClusterKubeconfig
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Clear the kubeconfig for a cluster
      tags:
      - Clusters
    post:
      description: Stores the kubeconfig encrypted per organization. The kubeconfig
        is never returned in responses.
      operationId: SetClusterKubeconfig
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Cluster ID
        in: path
        name: clusterID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.SetKubeconfigRequest'
        description: payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ClusterResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: bad request
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: cluster not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Set (or replace) the kubeconfig for a cluster
      tags:
      - Clusters
  /credentials:
    get:
      description: Returns credential metadata for the current org. Secrets are never
        returned.
      operationId: ListCredentials
      parameters:
      - description: Organization ID (UUID)
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Filter by provider (e.g., aws)
        in: query
        name: provider
        schema:
          type: string
      - description: Filter by kind (e.g., aws_access_key)
        in: query
        name: kind
        schema:
          type: string
      - description: Filter by scope kind (provider/service/resource)
        in: query
        name: scope_kind
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.CredentialOut'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: internal server error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List credentials (metadata only)
      tags:
      - Credentials
    post:
      operationId: CreateCredential
      parameters:
      - description: Organization ID (UUID)
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateCredentialRequest'
        description: Credential payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CredentialOut'
          description: Created
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: internal server error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create a credential (encrypts secret)
      tags:
      - Credentials
  /credentials/{id}:
    delete:
      operationId: DeleteCredential
      parameters:
      - description: Organization ID (UUID)
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Credential ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete credential
      tags:
      - Credentials
    get:
      operationId: GetCredential
      parameters:
      - description: Organization ID (UUID)
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Credential ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CredentialOut'
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: internal server error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get credential by ID (metadata only)
      tags:
      - Credentials
    patch:
      operationId: UpdateCredential
      parameters:
      - description: Organization ID (UUID)
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Credential ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateCredentialRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CredentialOut'
          description: OK
        "403":
          content:
            application/json:
              schema:
                type: string
          description: X-Org-ID required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update credential metadata and/or rotate secret
      tags:
      - Credentials
  /credentials/{id}/reveal:
    post:
      operationId: RevealCredential
      parameters:
      - description: Organization ID (UUID)
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Credential ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: OK
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Reveal decrypted secret (one-time read)
      tags:
      - Credentials
  /dns/domains:
    get:
      description: 'Returns domains for X-Org-ID. Filters: `domain_name`, `status`,
        `q` (contains).'
      operationId: ListDomains
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Exact domain name (lowercase, no trailing dot)
        in: query
        name: domain_name
        schema:
          type: string
      - description: pending|provisioning|ready|failed
        in: query
        name: status
        schema:
          type: string
      - description: Domain contains (case-insensitive)
        in: query
        name: q
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.DomainResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List domains (org scoped)
      tags:
      - DNS
    post:
      description: Creates a domain bound to a Route 53 scoped credential. Archer
        will backfill ZoneID if omitted.
      operationId: CreateDomain
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateDomainRequest'
        description: Domain payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.DomainResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: validation error
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: db error
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create a domain (org scoped)
      tags:
      - DNS
  /dns/domains/{domain_id}/records:
    get:
      description: 'Filters: `name`, `type`, `status`.'
      operationId: ListRecordSets
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Domain ID (UUID)
        in: path
        name: domain_id
        required: true
        schema:
          type: string
      - description: Exact relative name or FQDN (server normalizes)
        in: query
        name: name
        schema:
          type: string
      - description: RR type (A, AAAA, CNAME, TXT, MX, NS, SRV, CAA)
        in: query
        name: type
        schema:
          type: string
      - description: pending|provisioning|ready|failed
        in: query
        name: status
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.RecordSetResponse'
                type: array
          description: OK
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: domain not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List record sets for a domain
      tags:
      - DNS
    post:
      operationId: CreateRecordSet
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Domain ID (UUID)
        in: path
        name: domain_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateRecordSetRequest'
        description: Record set payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.RecordSetResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: validation error
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: domain not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create a record set (pending; Archer will UPSERT to Route 53)
      tags:
      - DNS
  /dns/domains/{id}:
    delete:
      operationId: DeleteDomain
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Domain ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete a domain
      tags:
      - DNS
    get:
      operationId: GetDomain
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Domain ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.DomainResponse'
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get a domain (org scoped)
      tags:
      - DNS
    patch:
      operationId: UpdateDomain
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Domain ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateDomainRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.DomainResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: validation error
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update a domain (org scoped)
      tags:
      - DNS
  /dns/records/{id}:
    delete:
      operationId: DeleteRecordSet
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Record Set ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete a record set (API removes row; worker can optionally handle
        external deletion policy)
      tags:
      - DNS
    patch:
      operationId: UpdateRecordSet
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Record Set ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateRecordSetRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.RecordSetResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: validation error
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update a record set (flips to pending for reconciliation)
      tags:
      - DNS
  /healthz:
    get:
      description: Returns 200 OK when the service is up
      operationId: HealthCheck               // operationId
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.HealthStatus'
          description: OK
      summary: Basic health check
      tags:
      - Health
  /labels:
    get:
      description: 'Returns node labels for the organization in X-Org-ID. Filters:
        `key`, `value`, and `q` (key contains). Add `include=node_pools` to include
        linked node groups.'
      operationId: ListLabels
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Exact key
        in: query
        name: key
        schema:
          type: string
      - description: Exact value
        in: query
        name: value
        schema:
          type: string
      - description: Key contains (case-insensitive)
        in: query
        name: q
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.LabelResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list node taints
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List node labels (org scoped)
      tags:
      - Labels
    post:
      description: Creates a label.
      operationId: CreateLabel
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateLabelRequest'
        description: Label payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.LabelResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid json / missing fields / invalid node_pool_ids
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: create failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create label (org scoped)
      tags:
      - Labels
  /labels/{id}:
    delete:
      description: Permanently deletes the label.
      operationId: DeleteLabel
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Label ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: delete failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete label (org scoped)
      tags:
      - Labels
    get:
      description: Returns one label.
      operationId: GetLabel
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Label ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.LabelResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get label by ID (org scoped)
      tags:
      - Labels
    patch:
      description: Partially update label fields.
      operationId: UpdateLabel
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Label ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateLabelRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.LabelResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid json
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: update failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update label (org scoped)
      tags:
      - Labels
  /load-balancers:
    get:
      description: Returns load balancers for the organization in X-Org-ID.
      operationId: ListLoadBalancers
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.LoadBalancerResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list clusters
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List load balancers (org scoped)
      tags:
      - LoadBalancers
    post:
      operationId: CreateLoadBalancer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateLoadBalancerRequest'
        description: Record set payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.LoadBalancerResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: validation error
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: domain not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create a load balancer
      tags:
      - LoadBalancers
  /load-balancers/{id}:
    delete:
      operationId: DeleteLoadBalancer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Load Balancer ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete a load balancer
      tags:
      - LoadBalancers
    get:
      description: Returns load balancer for the organization in X-Org-ID.
      operationId: GetLoadBalancers
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: LoadBalancer ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.LoadBalancerResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list clusters
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get a load balancer (org scoped)
      tags:
      - LoadBalancers
    patch:
      operationId: UpdateLoadBalancer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Load Balancer ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateLoadBalancerRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.LoadBalancerResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: validation error
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update a load balancer (org scoped)
      tags:
      - LoadBalancers
  /me:
    get:
      operationId: GetMe
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.meResponse'
          description: OK
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      summary: Get current user profile
      tags:
      - Me
    patch:
      operationId: UpdateMe
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.updateMeRequest'
        description: Patch profile
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.User'
          description: OK
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      summary: Update current user profile
      tags:
      - Me
  /me/api-keys:
    get:
      operationId: ListUserAPIKeys
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/handlers.userAPIKeyOut'
                type: array
          description: OK
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      summary: List my API keys
      tags:
      - MeAPIKeys
    post:
      description: Returns the plaintext key once. Store it securely on the client
        side.
      operationId: CreateUserAPIKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.createUserKeyRequest'
        description: Key options
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.userAPIKeyOut'
          description: Created
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      summary: Create a new user API key
      tags:
      - MeAPIKeys
  /me/api-keys/{id}:
    delete:
      operationId: DeleteUserAPIKey
      parameters:
      - description: Key ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
      security:
      - BearerAuth: []
      summary: Delete a user API key
      tags:
      - MeAPIKeys
  /node-pools:
    get:
      description: Returns node pools for the organization in X-Org-ID.
      operationId: ListNodePools
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Name contains (case-insensitive)
        in: query
        name: q
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.NodePoolResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list node pools
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List node pools (org scoped)
      tags:
      - NodePools
    post:
      description: Creates a node pool. Optionally attach initial servers.
      operationId: CreateNodePool
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateNodePoolRequest'
        description: NodePool payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.NodePoolResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid json / missing fields / invalid server_ids
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: create failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}:
    delete:
      description: Permanently deletes the node pool.
      operationId: DeleteNodePool
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: delete failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete node pool (org scoped)
      tags:
      - NodePools
    get:
      description: Returns one node pool. Add `include=servers` to include servers.
      operationId: GetNodePool
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.NodePoolResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get node pool by ID (org scoped)
      tags:
      - NodePools
    patch:
      description: Partially update node pool fields.
      operationId: UpdateNodePool
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateNodePoolRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.NodePoolResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid json
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: update failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}/annotations:
    get:
      operationId: ListNodePoolAnnotations
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.AnnotationResponse'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List annotations attached to a node pool (org scoped)
      tags:
      - NodePools
    post:
      operationId: AttachNodePoolAnnotations
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Group ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachAnnotationsRequest'
        description: Annotation IDs to attach
        required: true
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid server_ids
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: attach failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach annotation to a node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}/annotations/{annotationId}:
    delete:
      operationId: DetachNodePoolAnnotation
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Annotation ID (UUID)
        in: path
        name: annotationId
        required: true
        schema:
          type: string
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: detach failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach one annotation from a node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}/labels:
    get:
      operationId: ListNodePoolLabels
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Label Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.LabelResponse'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List labels attached to a node pool (org scoped)
      tags:
      - NodePools
    post:
      operationId: AttachNodePoolLabels
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachLabelsRequest'
        description: Label IDs to attach
        required: true
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid server_ids
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: attach failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach labels to a node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}/labels/{labelId}:
    delete:
      operationId: DetachNodePoolLabel
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Label ID (UUID)
        in: path
        name: labelId
        required: true
        schema:
          type: string
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: detach failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach one label from a node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}/servers:
    get:
      operationId: ListNodePoolServers
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.ServerResponse'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List servers attached to a node pool (org scoped)
      tags:
      - NodePools
    post:
      operationId: AttachNodePoolServers
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachServersRequest'
        description: Server IDs to attach
        required: true
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid server_ids
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: attach failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach servers to a node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}/servers/{serverId}:
    delete:
      operationId: DetachNodePoolServer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Server ID (UUID)
        in: path
        name: serverId
        required: true
        schema:
          type: string
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: detach failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach one server from a node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}/taints:
    get:
      operationId: ListNodePoolTaints
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.TaintResponse'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List taints attached to a node pool (org scoped)
      tags:
      - NodePools
    post:
      operationId: AttachNodePoolTaints
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.AttachTaintsRequest'
        description: Taint IDs to attach
        required: true
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid taint_ids
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: attach failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Attach taints to a node pool (org scoped)
      tags:
      - NodePools
  /node-pools/{id}/taints/{taintId}:
    delete:
      operationId: DetachNodePoolTaint
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Pool ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Taint ID (UUID)
        in: path
        name: taintId
        required: true
        schema:
          type: string
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: detach failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Detach one taint from a node pool (org scoped)
      tags:
      - NodePools
  /orgs:
    get:
      operationId: listMyOrgs
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.Organization'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
      security:
      - BearerAuth: []
      summary: List organizations I belong to
      tags:
      - Orgs
    post:
      operationId: createOrg
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.orgCreateReq'
        description: Org payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Organization'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Conflict
      security:
      - BearerAuth: []
      summary: Create organization
      tags:
      - Orgs
  /orgs/{id}:
    delete:
      operationId: deleteOrg
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Deleted
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Not Found
      security:
      - BearerAuth: []
      summary: Delete organization (owner)
      tags:
      - Orgs
    get:
      operationId: getOrg
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Organization'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Not Found
      security:
      - BearerAuth: []
      summary: Get organization
      tags:
      - Orgs
    patch:
      operationId: updateOrg
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.orgUpdateReq'
        description: Update payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Organization'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Not Found
      security:
      - BearerAuth: []
      summary: Update organization (owner/admin)
      tags:
      - Orgs
  /orgs/{id}/api-keys:
    get:
      operationId: listOrgKeys
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.APIKey'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
      security:
      - BearerAuth: []
      summary: List org-scoped API keys (no secrets)
      tags:
      - Orgs
    post:
      operationId: createOrgKey
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.orgKeyCreateReq'
        description: Key name + optional expiry
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.orgKeyCreateResp'
          description: Created
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
      security:
      - BearerAuth: []
      summary: Create org key/secret pair (owner/admin)
      tags:
      - Orgs
  /orgs/{id}/api-keys/{key_id}:
    delete:
      operationId: deleteOrgKey
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Key ID (UUID)
        in: path
        name: key_id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Deleted
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
      security:
      - BearerAuth: []
      summary: Delete org key (owner/admin)
      tags:
      - Orgs
  /orgs/{id}/members:
    get:
      operationId: listMembers
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/handlers.memberOut'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
      security:
      - BearerAuth: []
      summary: List members in org
      tags:
      - Orgs
    post:
      operationId: addOrUpdateMember
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.memberUpsertReq'
        description: User & role
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.memberOut'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
      security:
      - BearerAuth: []
      summary: Add or update a member (owner/admin)
      tags:
      - Orgs
  /orgs/{id}/members/{user_id}:
    delete:
      operationId: removeMember
      parameters:
      - description: Org ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: User ID (UUID)
        in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Removed
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/utils.ErrorResponse'
          description: Unauthorized
      security:
      - BearerAuth: []
      summary: Remove a member (owner/admin)
      tags:
      - Orgs
  /servers:
    get:
      description: 'Returns servers for the organization in X-Org-ID. Optional filters:
        status, role.'
      operationId: ListServers
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Filter by status (pending|provisioning|ready|failed)
        in: query
        name: status
        schema:
          type: string
      - description: Filter by role
        in: query
        name: role
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.ServerResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list servers
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List servers (org scoped)
      tags:
      - Servers
    post:
      description: Creates a server bound to the org in X-Org-ID. Validates that ssh_key_id
        belongs to the org.
      operationId: CreateServer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateServerRequest'
        description: Server payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ServerResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid json / missing fields / invalid status / invalid ssh_key_id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: create failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create server (org scoped)
      tags:
      - Servers
  /servers/{id}:
    delete:
      description: Permanently deletes the server.
      operationId: DeleteServer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Server ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: delete failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete server (org scoped)
      tags:
      - Servers
    get:
      description: Returns one server in the given organization.
      operationId: GetServer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Server ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ServerResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get server by ID (org scoped)
      tags:
      - Servers
    patch:
      description: Partially update fields; changing ssh_key_id validates ownership.
      operationId: UpdateServer
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Server ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateServerRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ServerResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid json / invalid status / invalid ssh_key_id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: update failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update server (org scoped)
      tags:
      - Servers
  /servers/{id}/reset-hostkey:
    post:
      description: Clears the stored SSH host key for this server. The next SSH connection
        will re-learn the host key (trust-on-first-use).
      operationId: ResetServerHostKey
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Server ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ServerResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: reset failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Reset SSH host key (org scoped)
      tags:
      - Servers
  /ssh:
    get:
      description: Returns ssh keys for the organization in X-Org-ID.
      operationId: ListPublicSshKeys
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.SshResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list keys
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List ssh keys (org scoped)
      tags:
      - Ssh
    post:
      description: Generates an RSA or ED25519 keypair, saves it, and returns metadata.
        For RSA you may set bits (2048/3072/4096). Default is 4096. ED25519 ignores
        bits.
      operationId: CreateSSHKey
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateSSHRequest'
        description: Key generation options
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.SshResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid json / invalid bits
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: generation/create failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create ssh keypair (org scoped)
      tags:
      - Ssh
  /ssh/{id}:
    delete:
      description: Permanently deletes a keypair.
      operationId: DeleteSSHKey
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: SSH Key ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: delete failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete ssh keypair (org scoped)
      tags:
      - Ssh
    get:
      description: Returns public key fields. Append `?reveal=true` to include the
        private key PEM.
      operationId: GetSSHKey
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: SSH Key ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Reveal private key PEM
        in: query
        name: reveal
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/dto.SshResponse'
                - $ref: '#/components/schemas/dto.SshRevealResponse'
          description: When reveal=true
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get ssh key by ID (org scoped)
      tags:
      - Ssh
  /ssh/{id}/download:
    get:
      description: Download `part=public|private|both` of the keypair. `both` returns
        a zip file.
      operationId: DownloadSSHKey
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        required: true
        schema:
          type: string
      - description: SSH Key ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Which part to download
        in: query
        name: part
        required: true
        schema:
          enum:
          - public
          - private
          - both
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
          description: file content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid part
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: download failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Download ssh key files by ID (org scoped)
      tags:
      - Ssh
  /taints:
    get:
      description: 'Returns node taints for the organization in X-Org-ID. Filters:
        `key`, `value`, and `q` (key contains). Add `include=node_pools` to include
        linked node pools.'
      operationId: ListTaints
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Exact key
        in: query
        name: key
        schema:
          type: string
      - description: Exact value
        in: query
        name: value
        schema:
          type: string
      - description: key contains (case-insensitive)
        in: query
        name: q
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/dto.TaintResponse'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: failed to list node taints
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: List node pool taints (org scoped)
      tags:
      - Taints
    post:
      description: Creates a taint.
      operationId: CreateTaint
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CreateTaintRequest'
        description: Taint payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.TaintResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid json / missing fields / invalid node_pool_ids
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: create failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Create node taint (org scoped)
      tags:
      - Taints
  /taints/{id}:
    delete:
      description: Permanently deletes the taint.
      operationId: DeleteTaint
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Taint ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "500":
          content:
            application/json:
              schema:
                type: string
          description: delete failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Delete taint (org scoped)
      tags:
      - Taints
    get:
      operationId: GetTaint
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Taint ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.TaintResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: fetch failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Get node taint by ID (org scoped)
      tags:
      - Taints
    patch:
      description: Partially update taint fields.
      operationId: UpdateTaint
      parameters:
      - description: Organization UUID
        in: header
        name: X-Org-ID
        schema:
          type: string
      - description: Node Taint ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.UpdateTaintRequest'
        description: Fields to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.TaintResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                type: string
          description: invalid id / invalid json
        "401":
          content:
            application/json:
              schema:
                type: string
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                type: string
          description: organization required
        "404":
          content:
            application/json:
              schema:
                type: string
          description: not found
        "500":
          content:
            application/json:
              schema:
                type: string
          description: update failed
      security:
      - BearerAuth: []
      - OrgKeyAuth: []
      - OrgSecretAuth: []
      summary: Update node taint (org scoped)
      tags:
      - Taints
  /version:
    get:
      description: Returns build/runtime metadata for the running service.
      operationId: Version                 // operationId
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.VersionResponse'
          description: OK
      summary: Service version information
      tags:
      - Meta
servers:
- description: Production API
  url: https://autoglue.onglueops.rocks/api/v1
- description: Staging API
  url: https://autoglue.apps.nonprod.earth.onglueops.rocks/api/v1
- description: Local dev
  url: http://localhost:8080/api/v1