swagger.yaml

basePath: /api/v1
definitions:
  auth.TokenPair:
    properties:
      access_token:
        type: string
      refresh_token:
        type: string
    type: object
  gorm.DeletedAt:
    properties:
      time:
        type: string
      valid:
        description: Valid is true if Time is not NULL
        type: boolean
    type: object
  gridtypes.Unit:
    enum:
    - 1024
    - 1048576
    - 1073741824
    - 1099511627776
    format: int64
    type: integer
    x-enum-varnames:
    - Kilobyte
    - Megabyte
    - Gigabyte
    - Terabyte
  handlers.APIResponse:
    properties:
      data: {}
      message:
        type: string
      status:
        type: integer
    type: object
  handlers.ChangePasswordInput:
    properties:
      confirm_password:
        type: string
      email:
        type: string
      password:
        maxLength: 64
        minLength: 8
        type: string
    required:
    - confirm_password
    - email
    - password
    type: object
  handlers.ChargeBalanceInput:
    properties:
      amount:
        type: number
      card_type:
        type: string
      payment_method_id:
        type: string
    required:
    - amount
    - card_type
    - payment_method_id
    type: object
  handlers.ChargeBalanceResponse:
    properties:
      email:
        type: string
      workflow_id:
        type: string
    type: object
  handlers.ClusterInput:
    properties:
      name:
        type: string
      nodes:
        items:
          $ref: '#/definitions/handlers.NodeInput'
        type: array
      token:
        type: string
    required:
    - name
    - nodes
    type: object
  handlers.CreditRequestInput:
    properties:
      amount:
        type: number
      memo:
        maxLength: 255
        minLength: 3
        type: string
    required:
    - amount
    - memo
    type: object
  handlers.CreditUserResponse:
    properties:
      amount:
        type: number
      memo:
        type: string
      user:
        type: string
    type: object
  handlers.DeploymentListResponse:
    properties:
      count:
        type: integer
      deployments:
        items:
          $ref: '#/definitions/services.ClusterData'
        type: array
    type: object
  handlers.DeploymentWorkflowResponse:
    properties:
      status:
        type: string
      task_id:
        type: string
    type: object
  handlers.EmailInput:
    properties:
      email:
        type: string
    required:
    - email
    type: object
  handlers.GenerateVouchersInput:
    properties:
      count:
        type: integer
      expire_after_days:
        type: integer
      value:
        type: number
    required:
    - count
    - expire_after_days
    - value
    type: object
  handlers.KubeconfigResponse:
    properties:
      kubeconfig:
        type: string
    type: object
  handlers.ListNodesResponse:
    properties:
      nodes:
        items:
          $ref: '#/definitions/types.Node'
        type: array
      total:
        type: integer
    type: object
  handlers.ListNodesWithDiscountResponse:
    properties:
      nodes:
        items:
          $ref: '#/definitions/handlers.NodesWithDiscount'
        type: array
      total:
        type: integer
    type: object
  handlers.LoginInput:
    properties:
      email:
        type: string
      password:
        maxLength: 64
        minLength: 3
        type: string
    required:
    - email
    - password
    type: object
  handlers.MaintenanceModeStatus:
    properties:
      enabled:
        type: boolean
    type: object
  handlers.NodeInput:
    properties:
      cpu:
        type: integer
      data_disks:
        description: Storage in MB
        items:
          type: integer
        type: array
      entrypoint:
        type: string
      env_vars:
        additionalProperties:
          type: string
        description: SSH_KEY, etc.
        type: object
      flist:
        type: string
      gpu_ids:
        description: List of GPU IDs
        items:
          type: string
        type: array
      memory:
        description: Memory in MB
        type: integer
      name:
        type: string
      node_id:
        type: integer
      root_size:
        description: Storage in MB
        type: integer
      type:
        enum:
        - worker
        - master
        - leader
        type: string
    required:
    - cpu
    - memory
    - name
    - node_id
    - root_size
    - type
    type: object
  handlers.NodeStoragePoolResponse:
    properties:
      pools:
        items:
          $ref: '#/definitions/services.Pool'
        type: array
    type: object
  handlers.NodesWithDiscount:
    properties:
      certificationType:
        type: string
      city:
        type: string
      country:
        type: string
      cpu_benchmark:
        $ref: '#/definitions/types.CpuBenchmark'
      created:
        type: integer
      dedicated:
        type: boolean
      discount_price:
        type: number
      dmi:
        $ref: '#/definitions/types.Dmi'
      extraFee:
        type: integer
      farm_free_ips:
        type: integer
      farmId:
        type: integer
      farmName:
        type: string
      farmingPolicyId:
        type: integer
      features:
        items:
          type: string
        type: array
      gpus:
        items:
          $ref: '#/definitions/types.NodeGPU'
        type: array
      gridVersion:
        type: integer
      healthy:
        type: boolean
      id:
        type: string
      inDedicatedFarm:
        type: boolean
      location:
        $ref: '#/definitions/types.Location'
      nodeId:
        type: integer
      num_gpu:
        type: integer
      power:
        $ref: '#/definitions/types.NodePower'
      price_usd:
        type: number
      publicConfig:
        $ref: '#/definitions/types.PublicConfig'
      rentContractId:
        type: integer
      rentable:
        type: boolean
      rented:
        type: boolean
      rentedByTwinId:
        type: integer
      serialNumber:
        type: string
      speed:
        $ref: '#/definitions/types.Speed'
      status:
        type: string
      total_resources:
        $ref: '#/definitions/types.Capacity'
      twinId:
        type: integer
      updatedAt:
        type: integer
      uptime:
        type: integer
      used_resources:
        $ref: '#/definitions/types.Capacity'
    type: object
  handlers.NotificationResponse:
    description: A notification response
    properties:
      created_at:
        type: string
      id:
        type: string
      payload:
        additionalProperties:
          type: string
        type: object
      read_at:
        type: string
      severity:
        $ref: '#/definitions/models.NotificationSeverity'
      status:
        $ref: '#/definitions/models.NotificationStatus'
      task_id:
        type: string
      type:
        $ref: '#/definitions/models.NotificationType'
    type: object
  handlers.PendingRecordsResponse:
    properties:
      pending_records:
        items:
          $ref: '#/definitions/services.PendingRecordsWithUSDAmounts'
        type: array
    type: object
  handlers.RedeemVoucherResponse:
    properties:
      amount:
        type: number
      email:
        type: string
      voucher_code:
        type: string
      workflow_id:
        type: string
    type: object
  handlers.RefreshTokenInput:
    properties:
      refresh_token:
        type: string
    required:
    - refresh_token
    type: object
  handlers.RefreshTokenResponse:
    properties:
      access_token:
        type: string
    type: object
  handlers.RegisterInput:
    properties:
      confirm_password:
        type: string
      email:
        type: string
      name:
        maxLength: 64
        minLength: 3
        type: string
      password:
        maxLength: 64
        minLength: 8
        type: string
    required:
    - confirm_password
    - email
    - name
    - password
    type: object
  handlers.RegisterResponse:
    properties:
      email:
        type: string
      timeout:
        type: string
    type: object
  handlers.RegisterUserResponse:
    properties:
      email:
        type: string
      workflow_id:
        type: string
    type: object
  handlers.ReserveNodeResponse:
    properties:
      email:
        type: string
      node_id:
        type: integer
      workflow_id:
        type: string
    type: object
  handlers.SSHKeyInput:
    properties:
      name:
        type: string
      public_key:
        type: string
    required:
    - name
    - public_key
    type: object
  handlers.TwinResponse:
    properties:
      account_id:
        type: string
      public_key:
        type: string
      relay:
        type: string
      twin_id:
        type: integer
    type: object
  handlers.UnreserveNodeResponse:
    properties:
      contract_id:
        type: integer
      email:
        type: string
      workflow_id:
        type: string
    type: object
  handlers.UserBalanceResponse:
    properties:
      balance_usd:
        type: number
      debt_usd:
        type: number
      pending_balance_usd:
        type: number
    type: object
  handlers.UserWorkflow:
    properties:
      created_at:
        type: string
      current_step:
        type: integer
      metadata:
        additionalProperties:
          type: string
        type: object
      name:
        type: string
      status:
        type: string
      step_name:
        type: string
      total_steps:
        type: integer
      workflow_id:
        type: string
    type: object
  handlers.UserWorkflowsResponse:
    properties:
      workflows:
        items:
          $ref: '#/definitions/handlers.UserWorkflow'
        type: array
    type: object
  handlers.VerifyCodeInput:
    properties:
      code:
        type: integer
      email:
        type: string
    required:
    - code
    - email
    type: object
  handlers.VerifyRegisterUserResponse:
    properties:
      access_token:
        type: string
      email:
        type: string
      refresh_token:
        type: string
      workflow_id:
        type: string
    type: object
  kubedeployer.Cluster:
    properties:
      name:
        maxLength: 20
        minLength: 3
        type: string
      network:
        allOf:
        - $ref: '#/definitions/workloads.ZNet'
        description: Computed
      nodes:
        items:
          $ref: '#/definitions/kubedeployer.Node'
        minItems: 1
        type: array
      project_name:
        type: string
      token:
        type: string
    required:
    - name
    - nodes
    type: object
  kubedeployer.Node:
    properties:
      contract_id:
        type: integer
      cpu:
        minimum: 1
        type: integer
      data_disks:
        description: Storage in MB
        items:
          type: integer
        minItems: 1
        type: array
      entrypoint:
        type: string
      env_vars:
        additionalProperties:
          type: string
        type: object
      flist:
        description: Optional fields
        type: string
      gpu_ids:
        description: List of GPU IDs
        items:
          type: string
        type: array
      ip:
        description: Computed
        type: string
      memory:
        description: Memory in MB
        minimum: 2048
        type: integer
      mycelium_ip:
        type: string
      name:
        maxLength: 20
        minLength: 3
        type: string
      node_id:
        type: integer
      original_name:
        type: string
      planetary_ip:
        type: string
      root_size:
        description: Storage in MB
        minimum: 5120
        type: integer
      type:
        allOf:
        - $ref: '#/definitions/kubedeployer.NodeType'
        enum:
        - worker
        - master
        - leader
    required:
    - cpu
    - data_disks
    - memory
    - name
    - node_id
    - root_size
    - type
    type: object
  kubedeployer.NodeType:
    enum:
    - worker
    - master
    - leader
    type: string
    x-enum-varnames:
    - NodeTypeWorker
    - NodeTypeMaster
    - NodeTypeLeader
  models.Invoice:
    properties:
      created_at:
        type: string
      id:
        type: integer
      nodes:
        items:
          $ref: '#/definitions/models.NodeItem'
        type: array
      tax:
        description: 'TODO:'
        type: number
      total:
        type: number
      user_id:
        type: integer
    required:
    - user_id
    type: object
  models.NodeItem:
    properties:
      contract_id:
        type: integer
      cost:
        type: number
      id:
        type: integer
      invoice_id:
        type: integer
      node_id:
        type: integer
      period:
        type: number
      rent_created_at:
        type: string
    type: object
  models.NotificationSeverity:
    enum:
    - info
    - error
    - warning
    - success
    type: string
    x-enum-varnames:
    - NotificationSeverityInfo
    - NotificationSeverityError
    - NotificationSeverityWarning
    - NotificationSeveritySuccess
  models.NotificationStatus:
    enum:
    - unread
    - read
    type: string
    x-enum-varnames:
    - NotificationStatusUnread
    - NotificationStatusRead
  models.NotificationType:
    enum:
    - deployment
    - billing
    - user
    - connected
    - node
    - admin
    type: string
    x-enum-varnames:
    - NotificationTypeDeployment
    - NotificationTypeBilling
    - NotificationTypeUser
    - NotificationTypeConnected
    - NotificationTypeNode
    - NotificationTypeAdmin
  models.SSHKey:
    properties:
      created_at:
        type: string
      deleted_at:
        $ref: '#/definitions/gorm.DeletedAt'
      id:
        description: Primary key
        type: integer
      name:
        description: Unique name per user
        type: string
      public_key:
        description: Unique public key per user
        type: string
      updated_at:
        type: string
      userID:
        description: User owner
        type: integer
    required:
    - name
    - public_key
    - userID
    type: object
  models.Voucher:
    properties:
      code:
        type: string
      created_at:
        type: string
      expires_at:
        type: string
      id:
        type: integer
      redeemed:
        type: boolean
      value:
        type: number
    required:
    - code
    - created_at
    - expires_at
    - value
    type: object
  services.AdminWorkflow:
    properties:
      created_at:
        type: string
      current_step:
        type: integer
      display_name:
        type: string
      error:
        type: string
      metadata:
        additionalProperties:
          type: string
        type: object
      name:
        type: string
      queue_name:
        type: string
      state:
        additionalProperties: {}
        type: object
      status:
        type: string
      step_name:
        type: string
      total_steps:
        type: integer
      user_id:
        type: integer
      uuid:
        type: string
    type: object
  services.ClusterData:
    properties:
      cluster:
        $ref: '#/definitions/kubedeployer.Cluster'
      created_at:
        type: string
      id:
        type: integer
      project_name:
        type: string
      updated_at:
        type: string
    type: object
  services.PendingRecordsWithUSDAmounts:
    properties:
      created_at:
        type: string
      id:
        type: integer
      tft_amount:
        description: TFTs are multiplied by 1e7
        type: integer
      transfer_mode:
        type: string
      transferred_tft_amount:
        type: integer
      transferred_usd_amount:
        type: number
      updated_at:
        type: string
      usd_amount:
        type: number
      user_id:
        type: integer
      username:
        type: string
    type: object
  services.Pool:
    properties:
      free:
        description: free space in bytes
        type: integer
      name:
        type: string
      type:
        description: type of the disk wither ssd or hdd
        type: string
    type: object
  services.Stats:
    properties:
      cores:
        type: integer
      countries:
        type: integer
      ssd:
        type: number
      system_account_balance:
        type: number
      total_clusters:
        type: integer
      total_users:
        type: integer
      up_nodes:
        type: integer
    type: object
  services.UserWithPendingBalance:
    properties:
      account_address:
        type: string
      admin:
        type: boolean
      code:
        type: integer
      created_at:
        type: string
      credit_card_balance:
        description: millicent, money from credit card
        type: integer
      credited_balance:
        description: millicent, manually added by admin or from vouchers
        type: integer
      debt:
        description: millicent
        type: integer
      email:
        type: string
      id:
        type: integer
      pending_balance_usd:
        type: number
      sponsored:
        type: boolean
      ssh_key:
        type: string
      stripe_customer_id:
        type: string
      updated_at:
        type: string
      username:
        type: string
      verified:
        type: boolean
    required:
    - email
    - username
    type: object
  services.UserWithUSDBalance:
    properties:
      account_address:
        type: string
      admin:
        type: boolean
      balance:
        description: USD balance
        type: number
      code:
        type: integer
      created_at:
        type: string
      credit_card_balance:
        description: millicent, money from credit card
        type: integer
      credited_balance:
        description: millicent, manually added by admin or from vouchers
        type: integer
      debt:
        description: millicent
        type: integer
      email:
        type: string
      id:
        type: integer
      sponsored:
        type: boolean
      ssh_key:
        type: string
      stripe_customer_id:
        type: string
      updated_at:
        type: string
      username:
        type: string
      verified:
        type: boolean
    required:
    - email
    - username
    type: object
  types.BIOS:
    properties:
      vendor:
        type: string
      version:
        type: string
    type: object
  types.Baseboard:
    properties:
      manufacturer:
        type: string
      product_name:
        type: string
    type: object
  types.Capacity:
    properties:
      cru:
        type: integer
      hru:
        $ref: '#/definitions/gridtypes.Unit'
      mru:
        $ref: '#/definitions/gridtypes.Unit'
      sru:
        $ref: '#/definitions/gridtypes.Unit'
    type: object
  types.CpuBenchmark:
    properties:
      multi:
        type: number
      node_twin_id:
        type: integer
      single:
        type: number
      threads:
        type: integer
      updated_at:
        type: integer
      workloads:
        type: integer
    type: object
  types.Dmi:
    properties:
      baseboard:
        $ref: '#/definitions/types.Baseboard'
      bios:
        $ref: '#/definitions/types.BIOS'
      memory:
        items:
          $ref: '#/definitions/types.Memory'
        type: array
      node_twin_id:
        type: integer
      processor:
        items:
          $ref: '#/definitions/types.Processor'
        type: array
      updated_at:
        type: integer
    type: object
  types.Location:
    properties:
      city:
        type: string
      country:
        type: string
      latitude:
        type: number
      longitude:
        type: number
      region:
        type: string
    type: object
  types.Memory:
    properties:
      manufacturer:
        type: string
      type:
        type: string
    type: object
  types.Node:
    properties:
      certificationType:
        type: string
      city:
        type: string
      country:
        type: string
      cpu_benchmark:
        $ref: '#/definitions/types.CpuBenchmark'
      created:
        type: integer
      dedicated:
        type: boolean
      dmi:
        $ref: '#/definitions/types.Dmi'
      extraFee:
        type: integer
      farm_free_ips:
        type: integer
      farmId:
        type: integer
      farmName:
        type: string
      farmingPolicyId:
        type: integer
      features:
        items:
          type: string
        type: array
      gpus:
        items:
          $ref: '#/definitions/types.NodeGPU'
        type: array
      gridVersion:
        type: integer
      healthy:
        type: boolean
      id:
        type: string
      inDedicatedFarm:
        type: boolean
      location:
        $ref: '#/definitions/types.Location'
      nodeId:
        type: integer
      num_gpu:
        type: integer
      power:
        $ref: '#/definitions/types.NodePower'
      price_usd:
        type: number
      publicConfig:
        $ref: '#/definitions/types.PublicConfig'
      rentContractId:
        type: integer
      rentable:
        type: boolean
      rented:
        type: boolean
      rentedByTwinId:
        type: integer
      serialNumber:
        type: string
      speed:
        $ref: '#/definitions/types.Speed'
      status:
        type: string
      total_resources:
        $ref: '#/definitions/types.Capacity'
      twinId:
        type: integer
      updatedAt:
        type: integer
      uptime:
        type: integer
      used_resources:
        $ref: '#/definitions/types.Capacity'
    type: object
  types.NodeGPU:
    properties:
      contract:
        type: integer
      device:
        type: string
      id:
        type: string
      node_twin_id:
        type: integer
      updated_at:
        type: integer
      vendor:
        type: string
      vram:
        type: integer
    type: object
  types.NodePower:
    properties:
      state:
        type: string
      target:
        type: string
    type: object
  types.Processor:
    properties:
      thread_count:
        type: string
      version:
        type: string
    type: object
  types.PublicConfig:
    properties:
      domain:
        type: string
      gw4:
        type: string
      gw6:
        type: string
      ipv4:
        type: string
      ipv6:
        type: string
    type: object
  types.Speed:
    properties:
      download:
        description: in bit/sec
        type: number
      node_twin_id:
        type: integer
      tcp_download_ipv6:
        description: in bit/sec
        type: number
      tcp_upload_ipv6:
        description: in bit/sec
        type: number
      udp_download_ipv4:
        description: in bit/sec
        type: number
      udp_download_ipv6:
        description: in bit/sec
        type: number
      udp_upload_ipv4:
        description: in bit/sec
        type: number
      udp_upload_ipv6:
        description: in bit/sec
        type: number
      updated_at:
        type: integer
      upload:
        description: in bit/sec let's suppose default is ipv4/tcp
        type: number
    type: object
  workloads.ZNet:
    properties:
      accessWGConfig:
        description: computed
        type: string
      addWGAccess:
        type: boolean
      description:
        type: string
      externalIP:
        $ref: '#/definitions/zos.IPNet'
      externalSK:
        items:
          format: int32
          type: integer
        type: array
      iprange:
        $ref: '#/definitions/zos.IPNet'
      keys:
        additionalProperties:
          items:
            format: int32
            type: integer
          type: array
        type: object
      myceliumKeys:
        additionalProperties:
          items:
            format: int32
            type: integer
          type: array
        type: object
      name:
        type: string
      nodeDeploymentID:
        additionalProperties:
          format: int64
          type: integer
        type: object
      nodes:
        items:
          format: int32
          type: integer
        type: array
      nodesIPRange:
        additionalProperties:
          $ref: '#/definitions/zos.IPNet'
        type: object
      publicNodeID:
        format: int32
        type: integer
      solutionType:
        type: string
      wgport:
        additionalProperties:
          type: integer
        type: object
    type: object
  zos.IPNet:
    properties:
      ip:
        description: network number
        items:
          format: int32
          type: integer
        type: array
      mask:
        description: network mask
        items:
          format: int32
          type: integer
        type: array
    type: object
info:
  contact: {}
  description: API documentation for Mycelium Cloud.
  title: Mycelium Cloud API
  version: "1.0"
paths:
  /deployments:
    delete:
      description: Deletes all deployments and their resources for the authenticated
        user
      produces:
      - application/json
      responses:
        "202":
          description: Delete all deployments workflow started successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.DeploymentWorkflowResponse'
              type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Delete all deployments
      tags:
      - deployments
    get:
      description: Retrieves a list of all deployments (clusters) for the authenticated
        user
      produces:
      - application/json
      responses:
        "200":
          description: Deployments retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.DeploymentListResponse'
              type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: List deployments
      tags:
      - deployments
    post:
      consumes:
      - application/json
      description: Creates and deploys a new Kubernetes cluster
      parameters:
      - description: Cluster configuration
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/handlers.ClusterInput'
      produces:
      - application/json
      responses:
        "202":
          description: Deployment workflow started successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.DeploymentWorkflowResponse'
              type: object
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Deploy cluster
      tags:
      - deployments
  /deployments/{name}:
    delete:
      description: Deletes a specific deployment and all its resources
      parameters:
      - description: Deployment name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        "202":
          description: Deployment deletion workflow started successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.DeploymentWorkflowResponse'
              type: object
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Deployment not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Delete deployment
      tags:
      - deployments
    get:
      description: Retrieves details of a specific deployment by name
      parameters:
      - description: Deployment name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Deployment details retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/services.ClusterData'
              type: object
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Deployment not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Get deployment
      tags:
      - deployments
  /deployments/{name}/kubeconfig:
    get:
      description: Retrieves the kubeconfig file for a specific deployment
      parameters:
      - description: Deployment name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Kubeconfig retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.KubeconfigResponse'
              type: object
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Deployment not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Get kubeconfig
      tags:
      - deployments
  /deployments/{name}/nodes:
    post:
      consumes:
      - application/json
      description: Adds a new node to an existing deployment
      parameters:
      - description: Cluster configuration with new node
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/handlers.ClusterInput'
      produces:
      - application/json
      responses:
        "202":
          description: Node addition workflow started successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.DeploymentWorkflowResponse'
              type: object
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Deployment not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Add node to deployment
      tags:
      - deployments
  /deployments/{name}/nodes/{node_name}:
    delete:
      description: Removes a specific node from an existing deployment
      parameters:
      - description: Deployment name
        in: path
        name: name
        required: true
        type: string
      - description: Node name to remove
        in: path
        name: node_name
        required: true
        type: string
      produces:
      - application/json
      responses:
        "202":
          description: Node removal workflow started successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.DeploymentWorkflowResponse'
              type: object
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Deployment not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Remove node from deployment
      tags:
      - deployments
  /invoices:
    get:
      consumes:
      - application/json
      description: Returns a list of all invoices
      operationId: get-all-invoices
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/models.Invoice'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Get all invoices
      tags:
      - admin
  /nodes:
    get:
      consumes:
      - application/json
      description: List all nodes from the grid proxy (no user-specific filtering)
      operationId: list-all-grid-nodes
      parameters:
      - description: 'Filter by healthy nodes (default: false)'
        in: query
        name: healthy
        type: boolean
      - description: 'Limit the number of nodes returned (default: 50)'
        in: query
        name: size
        type: integer
      - description: 'page number (default: 1)'
        in: query
        name: page
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: All grid nodes retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.ListNodesResponse'
              type: object
        "400":
          description: Invalid filter parameters
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: List all grid nodes
      tags:
      - nodes
  /nodes/{node_id}/storage-pool:
    get:
      consumes:
      - application/json
      description: Returns node storage pool
      operationId: get-node-storage-pool
      parameters:
      - description: Node ID
        in: path
        name: node_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Node storage pool is retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.NodeStoragePoolResponse'
              type: object
        "400":
          description: Bad Request or Invalid params
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Node not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Get node storage pool
      tags:
      - nodes
  /notifications:
    delete:
      consumes:
      - application/json
      description: Deletes all notifications for a user
      produces:
      - application/json
      responses:
        "200":
          description: All notifications deleted successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  type: object
              type: object
        "401":
          description: Authentication required
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Failed to delete notifications
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Delete all notifications
      tags:
      - notifications
    get:
      consumes:
      - application/json
      description: Retrieves all user notifications with pagination
      parameters:
      - description: 'Maximum number of notifications to return (default: 20, max:
          100)'
        in: query
        name: limit
        type: integer
      - description: 'Number of notifications to skip (default: 0)'
        in: query
        name: offset
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Notifications retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  properties:
                    count:
                      type: integer
                    limit:
                      type: integer
                    notifications:
                      items:
                        $ref: '#/definitions/handlers.NotificationResponse'
                      type: array
                    offset:
                      type: integer
                  type: object
              type: object
        "400":
          description: Invalid pagination parameters
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Failed to retrieve notifications
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Get all notifications
      tags:
      - notifications
  /notifications/{notification_id}:
    delete:
      consumes:
      - application/json
      description: Deletes a specific notification for a user
      parameters:
      - description: Notification ID
        in: path
        name: notification_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Notification deleted successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  type: object
              type: object
        "400":
          description: Invalid notification ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Authentication required
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Notification not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Failed to delete notification
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Delete a specific notification
      tags:
      - notifications
  /notifications/{notification_id}/read:
    patch:
      consumes:
      - application/json
      description: Marks a specific notification as read for a user
      parameters:
      - description: Notification ID
        in: path
        name: notification_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Notification marked as read successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  type: object
              type: object
        "400":
          description: Invalid notification ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Authentication required
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Notification not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Failed to mark notification as read
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Mark a specific notification as read
      tags:
      - notifications
  /notifications/{notification_id}/unread:
    patch:
      consumes:
      - application/json
      description: Marks a specific notification as unread for a user
      parameters:
      - description: Notification ID
        in: path
        name: notification_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Notification marked as unread successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  type: object
              type: object
        "400":
          description: Invalid notification ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Authentication required
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Notification not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Failed to mark notification as unread
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Mark a specific notification as unread
      tags:
      - notifications
  /notifications/read-all:
    patch:
      consumes:
      - application/json
      description: Marks all notifications as read for a user
      produces:
      - application/json
      responses:
        "200":
          description: All notifications marked as read successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  type: object
              type: object
        "400":
          description: Invalid notification ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Authentication required
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Failed to mark notifications as read
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Mark all notifications as read
      tags:
      - notifications
  /notifications/unread:
    get:
      consumes:
      - application/json
      description: Retrieves only unread notifications for a user
      parameters:
      - description: Limit
        in: query
        name: limit
        type: integer
      - description: Offset
        in: query
        name: offset
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Unread notifications retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  properties:
                    count:
                      type: integer
                    limit:
                      type: integer
                    notifications:
                      items:
                        $ref: '#/definitions/handlers.NotificationResponse'
                      type: array
                    offset:
                      type: integer
                  type: object
              type: object
        "400":
          description: Invalid pagination parameters
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Failed to retrieve unread notifications
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Get unread notifications
      tags:
      - notifications
  /pending-records:
    get:
      consumes:
      - application/json
      description: Returns all pending records in the system
      operationId: list-pending-records
      produces:
      - application/json
      responses:
        "200":
          description: Pending records are retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/services.PendingRecordsWithUSDAmounts'
              type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: List pending records
      tags:
      - admin
  /stats:
    get:
      consumes:
      - application/json
      description: Retrieves comprehensive system statistics.
      operationId: get-stats
      produces:
      - application/json
      responses:
        "200":
          description: System statistics retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/services.Stats'
              type: object
        "500":
          description: Internal Server Error - Failed to retrieve statistics
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Get system statistics
      tags:
      - admin
  /system/maintenance/status:
    get:
      consumes:
      - application/json
      description: Gets maintenance mode for the system
      operationId: get-maintenance-mode
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.MaintenanceModeStatus'
              type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Get maintenance mode
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Sets maintenance mode for the system
      operationId: set-maintenance-mode
      parameters:
      - description: Maintenance Mode Status
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.MaintenanceModeStatus'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Set maintenance mode
      tags:
      - admin
  /twins/{twin_id}/account:
    get:
      consumes:
      - application/json
      description: Retrieve the account ID associated with a specific twin ID
      parameters:
      - description: Twin ID
        in: path
        name: twin_id
        required: true
        type: integer
      - description: Pagination limit
        in: query
        name: limit
        type: integer
      - description: Pagination offset
        in: query
        name: offset
        type: integer
      - description: Other optional filter params
        in: query
        name: filterParam
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Account ID is retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.TwinResponse'
              type: object
        "400":
          description: Bad Request or Invalid params
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Twin ID not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Get account ID by twin ID
      tags:
      - twins
  /user:
    get:
      description: Retrieves all data of the user
      operationId: get-user
      produces:
      - application/json
      responses:
        "200":
          description: User is retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/services.UserWithPendingBalance'
              type: object
        "404":
          description: User is not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Get user details
      tags:
      - users
  /user/balance:
    get:
      description: Retrieves the user's balance in USD
      operationId: get-user-balance
      produces:
      - application/json
      responses:
        "200":
          description: Balance fetched successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.UserBalanceResponse'
              type: object
        "404":
          description: User is not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Get user balance
      tags:
      - users
  /user/balance/charge:
    post:
      consumes:
      - application/json
      description: Charges the user's balance using a payment method
      operationId: charge-balance
      parameters:
      - description: Charge Balance Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.ChargeBalanceInput'
      produces:
      - application/json
      responses:
        "202":
          description: 'workflow_id: string, email: string'
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.ChargeBalanceResponse'
              type: object
        "400":
          description: Invalid request format or amount
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: User is not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Charge user balance
      tags:
      - users
  /user/change_password:
    put:
      consumes:
      - application/json
      description: Changes the user's password
      operationId: change-password
      parameters:
      - description: Change Password Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.ChangePasswordInput'
      produces:
      - application/json
      responses:
        "200":
          description: Password updated successfully
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "400":
          description: Invalid request format or password mismatch
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: User is not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Change password
      tags:
      - users
  /user/forgot_password:
    post:
      consumes:
      - application/json
      description: Sends a verification code to the user's email for password reset
      operationId: forgot-password
      parameters:
      - description: Email Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.EmailInput'
      produces:
      - application/json
      responses:
        "200":
          description: Verification code sent successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.RegisterResponse'
              type: object
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: User is not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Forgot password
      tags:
      - users
  /user/forgot_password/verify:
    post:
      consumes:
      - application/json
      description: Verifies the code sent to the user's email for password reset
      operationId: verify-forgot-password-code
      parameters:
      - description: Verify Code Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.VerifyCodeInput'
      produces:
      - application/json
      responses:
        "201":
          description: Verification successful
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/auth.TokenPair'
              type: object
        "400":
          description: Invalid request format or verification failed
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Verify forgot password code
      tags:
      - users
  /user/invoice:
    get:
      consumes:
      - application/json
      description: Returns a list of invoices for a user
      operationId: get-invoices
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/models.Invoice'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - UserMiddleware: []
      summary: Get invoices
      tags:
      - invoices
  /user/invoice/{invoice_id}:
    get:
      consumes:
      - application/json
      description: Downloads an invoice by ID
      operationId: download-invoice
      parameters:
      - description: Invoice ID
        in: path
        name: invoice_id
        required: true
        type: string
      produces:
      - application/octet-stream
      responses:
        "200":
          description: OK
          schema:
            type: file
        "404":
          description: Invoice is not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - UserMiddleware: []
      summary: Download invoice
      tags:
      - invoices
  /user/login:
    post:
      consumes:
      - application/json
      description: Logs a user in. Checks KYC verification status and updates user
        sponsorship status if needed. Login is not blocked by KYC errors.
      operationId: login-user
      parameters:
      - description: Login Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.LoginInput'
      produces:
      - application/json
      responses:
        "201":
          description: token pair generated
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/auth.TokenPair'
              type: object
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Login failed
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Login user (KYC verification checked)
      tags:
      - users
  /user/nodes:
    get:
      consumes:
      - application/json
      description: List nodes from proxy [rented nodes first, then available nodes
        sorted by uptime]
      operationId: list-nodes
      parameters:
      - description: 'Filter by healthy nodes (default: true)'
        in: query
        name: healthy
        type: boolean
      - description: 'Filter by rentable nodes (default: true)'
        in: query
        name: rentable
        type: boolean
      - description: 'Limit the number of nodes returned (default: 50)'
        in: query
        name: limit
        type: integer
      - description: 'Offset for pagination (default: 0)'
        in: query
        name: offset
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Nodes are retrieved successfully
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "400":
          description: Invalid filter parameters
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - UserMiddleware: []
      summary: List nodes
      tags:
      - nodes
  /user/nodes/{node_id}:
    post:
      consumes:
      - application/json
      description: Reserves a node for a user
      operationId: reserve-node
      parameters:
      - description: Node ID
        in: path
        name: node_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "202":
          description: Node reservation in progress
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.ReserveNodeResponse'
              type: object
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: No nodes are available for rent.
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - UserMiddleware: []
      summary: Reserve node
      tags:
      - nodes
  /user/nodes/rentable:
    get:
      consumes:
      - application/json
      description: Retrieves a list of rentable nodes from the grid proxy. These are
        healthy nodes that are available for rent.
      operationId: list-rentable-nodes
      produces:
      - application/json
      responses:
        "200":
          description: Rentable nodes retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.ListNodesWithDiscountResponse'
              type: object
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: List rentable nodes
      tags:
      - nodes
  /user/nodes/rented:
    get:
      consumes:
      - application/json
      description: Returns a list of reserved nodes for a user
      operationId: list-reserved-nodes
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.ListNodesWithDiscountResponse'
              type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - UserMiddleware: []
      summary: List reserved nodes
      tags:
      - nodes
  /user/nodes/unreserve/{contract_id}:
    delete:
      consumes:
      - application/json
      description: Unreserve a node for a user
      operationId: unreserve-node
      parameters:
      - description: Contract ID
        in: path
        name: contract_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "202":
          description: Accepted
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.UnreserveNodeResponse'
              type: object
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: User is not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - UserMiddleware: []
      summary: Unreserve node
      tags:
      - nodes
  /user/pending-records:
    get:
      consumes:
      - application/json
      description: Returns user pending records in the system
      operationId: list-user-pending-records
      produces:
      - application/json
      responses:
        "200":
          description: Pending records returned successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.PendingRecordsResponse'
              type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: List user pending records
      tags:
      - users
  /user/redeem/{voucher_code}:
    put:
      description: Redeems a voucher for the user
      operationId: redeem-voucher
      parameters:
      - description: Voucher Code
        in: path
        name: voucher_code
        required: true
        type: string
      produces:
      - application/json
      responses:
        "202":
          description: 'workflow_id: string, voucher_code: string, amount: float64,
            email: string'
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.RedeemVoucherResponse'
              type: object
        "400":
          description: Invalid voucher code, already redeemed, or expired
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: User or voucher are not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Redeem voucher
      tags:
      - users
  /user/refresh:
    post:
      consumes:
      - application/json
      description: Refreshes the access token using a valid refresh token
      operationId: refresh-token
      parameters:
      - description: Refresh Token Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.RefreshTokenInput'
      produces:
      - application/json
      responses:
        "201":
          description: access token refreshed successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.RefreshTokenResponse'
              type: object
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Invalid or expired refresh token
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Refresh access token
      tags:
      - users
  /user/register:
    post:
      consumes:
      - application/json
      description: Registers a new user, sets up blockchain account, and creates KYC
        sponsorship. Sends verification code to email.
      operationId: register-user
      parameters:
      - description: Register Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.RegisterInput'
      produces:
      - application/json
      responses:
        "202":
          description: 'workflow_id: string, email: string'
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.RegisterUserResponse'
              type: object
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "409":
          description: User is already registered
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Register user (with KYC sponsorship)
      tags:
      - users
  /user/register/verify:
    post:
      consumes:
      - application/json
      description: Verifies the email using the registration code
      operationId: verify-register-code
      parameters:
      - description: Verification details
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handlers.VerifyCodeInput'
      produces:
      - application/json
      responses:
        "202":
          description: 'workflow_id: string, email: string, token_pair: object'
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.VerifyRegisterUserResponse'
              type: object
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "409":
          description: User is already registered
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Verify registration code
      tags:
      - users
  /user/ssh-keys:
    get:
      consumes:
      - application/json
      description: Lists all SSH keys for the authenticated user
      operationId: list-ssh-keys
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/models.SSHKey'
                  type: array
              type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: List user SSH keys
      tags:
      - users
    post:
      consumes:
      - application/json
      description: Adds a new SSH key for the authenticated user
      operationId: add-ssh-key
      parameters:
      - description: SSH Key Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.SSHKeyInput'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/models.SSHKey'
              type: object
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Add SSH key
      tags:
      - users
  /user/ssh-keys/{ssh_key_id}:
    delete:
      consumes:
      - application/json
      description: Deletes an SSH key for the authenticated user
      operationId: delete-ssh-key
      parameters:
      - description: SSH Key ID
        in: path
        name: ssh_key_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "400":
          description: Invalid SSH key ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: SSH key not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: Delete SSH key
      tags:
      - users
  /user/workflows:
    get:
      consumes:
      - application/json
      description: Returns all pending/running workflows belonging to the authenticated
        user.
      operationId: list-user-workflows
      produces:
      - application/json
      responses:
        "200":
          description: User workflows retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.UserWorkflowsResponse'
              type: object
        "401":
          description: Unauthorized user
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - BearerAuth: []
      summary: List remaining user workflows
      tags:
      - workflow
  /users:
    get:
      consumes:
      - application/json
      description: Returns a list of all users
      operationId: get-all-users
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/services.UserWithUSDBalance'
            type: array
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Get all users
      tags:
      - admin
  /users/{user_id}:
    delete:
      consumes:
      - application/json
      description: Deletes a user from the system
      operationId: delete-user
      parameters:
      - description: User ID
        in: path
        name: user_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "400":
          description: Invalid user ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "403":
          description: Admins cannot delete their own account
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Delete a user
      tags:
      - admin
  /users/{user_id}/credit:
    post:
      consumes:
      - application/json
      description: Credits a specific user's balance
      operationId: credit-user
      parameters:
      - description: User ID
        in: path
        name: user_id
        required: true
        type: string
      - description: Credit Request Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.CreditRequestInput'
      produces:
      - application/json
      responses:
        "202":
          description: Accepted
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handlers.CreditUserResponse'
              type: object
        "400":
          description: Invalid request format or user ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Credit user balance
      tags:
      - admin
  /users/{user_id}/drain:
    post:
      consumes:
      - application/json
      description: Drains a specific user's balance to the system account
      operationId: drain-user
      parameters:
      - description: User ID
        in: path
        name: user_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "202":
          description: User balance drain initiated
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "400":
          description: Invalid user ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Drain user balance
      tags:
      - admin
  /users/drain-all:
    post:
      consumes:
      - application/json
      description: Drains all users' balances to the system account
      operationId: drain-all-users
      produces:
      - application/json
      responses:
        "202":
          description: All users' balance drain initiated
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Drain all users' balances
      tags:
      - admin
  /users/mail:
    post:
      consumes:
      - multipart/form-data
      description: Allows admin to send a custom email to all users with optional
        file attachments.
      operationId: admin-mail-all-users
      parameters:
      - description: Email subject
        in: formData
        name: subject
        required: true
        type: string
      - description: Email body content
        in: formData
        name: body
        required: true
        type: string
      - description: Email attachments (multiple files allowed)
        in: formData
        name: attachments
        type: file
      produces:
      - application/json
      responses:
        "200":
          description: Mail sending started
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Start sending mail to all users (async)
      tags:
      - admin
  /vouchers:
    get:
      consumes:
      - application/json
      description: Returns all vouchers in the system
      operationId: list-vouchers
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/models.Voucher'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: List vouchers
      tags:
      - admin
  /vouchers/generate:
    post:
      consumes:
      - application/json
      description: Generates a bulk of vouchers
      operationId: generate-vouchers
      parameters:
      - description: Generate Vouchers Input
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handlers.GenerateVouchersInput'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/models.Voucher'
                  type: array
              type: object
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: Generate vouchers
      tags:
      - admin
  /workflow/{workflow_id}:
    get:
      consumes:
      - application/json
      description: Returns the status of a workflow by its ID.
      operationId: get-workflow-status
      parameters:
      - description: Workflow ID
        in: path
        name: workflow_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Workflow status returned successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: Invalid request or missing workflow ID
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "404":
          description: Workflow not found
          schema:
            $ref: '#/definitions/handlers.APIResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      summary: Get workflow status
      tags:
      - workflow
  /workflows:
    get:
      consumes:
      - application/json
      description: Returns all workflows in the system with optional filtering by
        status
      operationId: list-all-workflows
      parameters:
      - description: Filter workflows by status (pending, running, completed, failed)
        in: query
        name: status
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Workflows retrieved successfully
          schema:
            allOf:
            - $ref: '#/definitions/handlers.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/services.AdminWorkflow'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/handlers.APIResponse'
      security:
      - AdminMiddleware: []
      summary: List all workflows
      tags:
      - admin
securityDefinitions:
  BearerAuth:
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"