ez-api/docs/swagger.yaml

basePath: /
definitions:
  api.APIKeyStatsSummaryResponse:
    properties:
      failure_rate:
        type: number
      failure_requests:
        type: integer
      success_rate:
        type: number
      success_requests:
        type: integer
      total_requests:
        type: integer
    type: object
  api.AboutResponse:
    properties:
      description:
        example: High-performance LLM API gateway
        type: string
      name:
        example: EZ-API Gateway
        type: string
      repository:
        example: https://github.com/ez-api/ez-api
        type: string
      version:
        example: 0.1.0
        type: string
    type: object
  api.AccessResponse:
    properties:
      default_namespace:
        type: string
      namespaces:
        items:
          type: string
        type: array
    type: object
  api.AckAlertRequest:
    properties:
      acked_by:
        type: string
    type: object
  api.AdminUsageStatsResponse:
    properties:
      active_masters:
        type: integer
      by_master:
        items:
          $ref: '#/definitions/api.MasterUsageAgg'
        type: array
      by_provider:
        items:
          $ref: '#/definitions/api.ProviderUsageAgg'
        type: array
      period:
        type: string
      total_masters:
        type: integer
      total_requests:
        type: integer
      total_tokens:
        type: integer
    type: object
  api.AlertStats:
    properties:
      acknowledged:
        type: integer
      active:
        type: integer
      critical:
        type: integer
      info:
        type: integer
      resolved:
        type: integer
      total:
        type: integer
      warning:
        type: integer
    type: object
  api.AlertThresholdView:
    properties:
      global_qps:
        type: integer
      master_rpd:
        type: integer
      master_rpm:
        type: integer
      master_tpd:
        type: integer
      master_tpm:
        type: integer
      min_rpm_requests_1m:
        type: integer
      min_tpm_tokens_1m:
        type: integer
      updated_at:
        type: integer
    type: object
  api.AlertView:
    properties:
      acked_at:
        type: integer
      acked_by:
        type: string
      created_at:
        type: integer
      expires_at:
        type: integer
      id:
        type: integer
      message:
        type: string
      metadata:
        type: string
      related_id:
        type: integer
      related_name:
        type: string
      related_type:
        type: string
      resolved_at:
        type: integer
      severity:
        type: string
      status:
        type: string
      title:
        type: string
      type:
        type: string
      updated_at:
        type: integer
    type: object
  api.BatchActionRequest:
    properties:
      action:
        type: string
      ids:
        items:
          type: integer
        type: array
      status:
        type: string
    type: object
  api.BatchResponse:
    properties:
      action:
        type: string
      failed:
        items:
          $ref: '#/definitions/api.BatchResult'
        type: array
      success:
        items:
          type: integer
        type: array
    type: object
  api.BatchResult:
    properties:
      error:
        type: string
      id:
        type: integer
    type: object
  api.CountStats:
    properties:
      active:
        type: integer
      total:
        type: integer
    type: object
  api.CreateAlertRequest:
    properties:
      expires_at:
        type: integer
      message:
        type: string
      metadata:
        type: string
      related_id:
        type: integer
      related_name:
        type: string
      related_type:
        type: string
      severity:
        type: string
      title:
        type: string
      type:
        type: string
    required:
    - severity
    - title
    - type
    type: object
  api.CreateIPBanRequest:
    properties:
      cidr:
        type: string
      expires_at:
        type: integer
      reason:
        type: string
    required:
    - cidr
    type: object
  api.CreateMasterRequest:
    properties:
      global_qps:
        type: integer
      group:
        type: string
      max_child_keys:
        type: integer
      name:
        type: string
    required:
    - group
    - name
    type: object
  api.DashboardSummaryResponse:
    properties:
      keys:
        $ref: '#/definitions/api.CountStats'
      latency:
        $ref: '#/definitions/api.LatencyStats'
      masters:
        $ref: '#/definitions/api.CountStats'
      period:
        type: string
      provider_keys:
        $ref: '#/definitions/api.ProviderKeyStats'
      requests:
        $ref: '#/definitions/api.RequestStats'
      tokens:
        $ref: '#/definitions/api.TokenStats'
      top_models:
        items:
          $ref: '#/definitions/api.TopModelStat'
        type: array
      trends:
        allOf:
        - $ref: '#/definitions/api.DashboardTrends'
        description: Only present when include_trends=true
      updated_at:
        type: integer
    type: object
  api.DashboardTrends:
    properties:
      error_rate:
        $ref: '#/definitions/api.TrendInfo'
      latency:
        $ref: '#/definitions/api.TrendInfo'
      requests:
        $ref: '#/definitions/api.TrendInfo'
      tokens:
        $ref: '#/definitions/api.TrendInfo'
    type: object
  api.DeleteLogsRequest:
    properties:
      before:
        type: string
      key_id:
        type: integer
      model:
        type: string
    type: object
  api.DeleteLogsResponse:
    properties:
      deleted_count:
        type: integer
    type: object
  api.GroupedStatsItem:
    properties:
      avg_latency_ms:
        type: number
      count:
        type: integer
      date:
        description: For group_by=day
        type: string
      hour:
        description: For group_by=hour
        type: string
      minute:
        description: For group_by=minute
        type: string
      model:
        description: For group_by=model
        type: string
      month:
        description: For group_by=month
        type: string
      tokens_in:
        type: integer
      tokens_out:
        type: integer
    type: object
  api.GroupedStatsResponse:
    properties:
      items:
        items:
          $ref: '#/definitions/api.GroupedStatsItem'
        type: array
    type: object
  api.IPBanView:
    properties:
      cidr:
        type: string
      created_at:
        type: integer
      created_by:
        type: string
      expires_at:
        type: integer
      hit_count:
        type: integer
      id:
        type: integer
      reason:
        type: string
      status:
        type: string
      updated_at:
        type: integer
    type: object
  api.IssueChildKeyRequest:
    properties:
      allow_ips:
        type: string
      deny_ips:
        type: string
      expires_at:
        type: string
      group:
        type: string
      model_limits:
        type: string
      model_limits_enabled:
        type: boolean
      scopes:
        type: string
    type: object
  api.KeyUsageStat:
    properties:
      key_id:
        type: integer
      requests:
        type: integer
      tokens:
        type: integer
    type: object
  api.LatencyStats:
    properties:
      avg_ms:
        type: number
    type: object
  api.ListAlertsResponse:
    properties:
      items:
        items:
          $ref: '#/definitions/api.AlertView'
        type: array
      limit:
        type: integer
      offset:
        type: integer
      total:
        type: integer
    type: object
  api.ListLogsResponse:
    properties:
      items:
        items:
          $ref: '#/definitions/api.LogView'
        type: array
      limit:
        type: integer
      offset:
        type: integer
      total:
        type: integer
    type: object
  api.ListMasterLogsResponse:
    properties:
      items:
        items:
          $ref: '#/definitions/api.MasterLogView'
        type: array
      limit:
        type: integer
      offset:
        type: integer
      total:
        type: integer
    type: object
  api.LogStatsResponse:
    properties:
      avg_latency_ms:
        type: number
      by_status:
        additionalProperties:
          format: int64
          type: integer
        type: object
      tokens_in:
        type: integer
      tokens_out:
        type: integer
      total:
        type: integer
    type: object
  api.LogView:
    properties:
      audit_reason:
        type: string
      client_ip:
        type: string
      created_at:
        type: integer
      error_message:
        type: string
      group:
        type: string
      id:
        type: integer
      key_id:
        type: integer
      latency_ms:
        type: integer
      model:
        type: string
      provider_id:
        type: integer
      provider_name:
        type: string
      provider_type:
        type: string
      request_body:
        type: string
      request_size:
        type: integer
      response_size:
        type: integer
      status_code:
        type: integer
      tokens_in:
        type: integer
      tokens_out:
        type: integer
    type: object
  api.ManageMasterRequest:
    properties:
      action:
        description: freeze/unfreeze
        type: string
    required:
    - action
    type: object
  api.MapData:
    additionalProperties: {}
    type: object
  api.MasterLogView:
    properties:
      created_at:
        type: integer
      error_message:
        type: string
      group:
        type: string
      id:
        type: integer
      key_id:
        type: integer
      latency_ms:
        type: integer
      model:
        type: string
      request_size:
        type: integer
      response_size:
        type: integer
      status_code:
        type: integer
      tokens_in:
        type: integer
      tokens_out:
        type: integer
    type: object
  api.MasterRealtimeSummaryView:
    properties:
      master_id:
        type: integer
      qps:
        type: integer
      rate_limited:
        type: boolean
    type: object
  api.MasterRealtimeView:
    properties:
      qps:
        type: integer
      qps_limit:
        type: integer
      rate_limited:
        type: boolean
      requests:
        type: integer
      tokens:
        type: integer
      updated_at:
        type: integer
    type: object
  api.MasterUsageAgg:
    properties:
      master_id:
        type: integer
      requests:
        type: integer
      tokens:
        type: integer
    type: object
  api.MasterUsageStatsResponse:
    properties:
      by_key:
        items:
          $ref: '#/definitions/api.KeyUsageStat'
        type: array
      by_model:
        items:
          $ref: '#/definitions/api.ModelUsageStat'
        type: array
      period:
        type: string
      total_requests:
        type: integer
      total_tokens:
        type: integer
    type: object
  api.MasterView:
    properties:
      created_at:
        type: integer
      default_namespace:
        type: string
      epoch:
        type: integer
      global_qps:
        type: integer
      group:
        type: string
      id:
        type: integer
      max_child_keys:
        type: integer
      name:
        type: string
      namespaces:
        type: string
      realtime:
        $ref: '#/definitions/api.MasterRealtimeView'
      status:
        type: string
      updated_at:
        type: integer
    type: object
  api.ModelUsageStat:
    properties:
      model:
        type: string
      requests:
        type: integer
      tokens:
        type: integer
    type: object
  api.OperationLogView:
    properties:
      actor:
        type: string
      client_ip:
        type: string
      created_at:
        type: integer
      error_message:
        type: string
      id:
        type: integer
      latency_ms:
        type: integer
      method:
        type: string
      path:
        type: string
      query:
        type: string
      request_id:
        type: string
      status_code:
        type: integer
      user_agent:
        type: string
    type: object
  api.ProviderKeyStats:
    properties:
      active:
        type: integer
      auto_disabled:
        type: integer
      suspended:
        type: integer
      total:
        type: integer
    type: object
  api.ProviderUsageAgg:
    properties:
      provider_id:
        type: integer
      provider_name:
        type: string
      provider_type:
        type: string
      requests:
        type: integer
      tokens:
        type: integer
    type: object
  api.RequestStats:
    properties:
      error_rate:
        type: number
      failed:
        type: integer
      success:
        type: integer
      total:
        type: integer
    type: object
  api.ResponseEnvelope:
    properties:
      code:
        example: 0
        type: integer
      data:
        type: object
      details:
        type: object
      message:
        example: success
        type: string
      trace_id:
        example: a1b2c3d4e5f6g7h8
        type: string
    type: object
  api.StatusResponse:
    properties:
      status:
        example: ok
        type: string
      uptime:
        example: 72h30m15s
        type: string
      version:
        example: 0.1.0
        type: string
    type: object
  api.SystemRealtimeView:
    properties:
      by_master:
        items:
          $ref: '#/definitions/api.MasterRealtimeSummaryView'
        type: array
      qps:
        type: integer
      rate_limited_count:
        type: integer
      rpm:
        type: integer
      updated_at:
        type: integer
    type: object
  api.TokenStats:
    properties:
      input:
        type: integer
      output:
        type: integer
      total:
        type: integer
    type: object
  api.TokenView:
    properties:
      allow_ips:
        type: string
      created_at:
        type: integer
      default_namespace:
        type: string
      deny_ips:
        type: string
      expires_at:
        type: string
      group:
        type: string
      id:
        type: integer
      issued_at_epoch:
        type: integer
      issued_by:
        type: string
      last_accessed_at:
        type: string
      model_limits:
        type: string
      model_limits_enabled:
        type: boolean
      namespaces:
        type: string
      quota_limit:
        type: integer
      quota_reset_at:
        type: string
      quota_reset_type:
        type: string
      quota_used:
        type: integer
      request_count:
        type: integer
      scopes:
        type: string
      status:
        type: string
      updated_at:
        type: integer
      used_tokens:
        type: integer
    type: object
  api.TopModelStat:
    properties:
      model:
        type: string
      requests:
        type: integer
      tokens:
        type: integer
    type: object
  api.TrafficChartAxis:
    properties:
      labels:
        items:
          type: string
        type: array
      timestamps:
        items:
          type: integer
        type: array
      totals:
        $ref: '#/definitions/api.TrafficTotals'
    type: object
  api.TrafficChartResponse:
    properties:
      granularity:
        type: string
      series:
        items:
          $ref: '#/definitions/api.TrafficSeries'
        type: array
      since:
        type: integer
      until:
        type: integer
      x:
        $ref: '#/definitions/api.TrafficChartAxis'
    type: object
  api.TrafficSeries:
    properties:
      data:
        items:
          type: integer
        type: array
      name:
        type: string
      tokens_in:
        items:
          type: integer
        type: array
      tokens_out:
        items:
          type: integer
        type: array
    type: object
  api.TrafficTotals:
    properties:
      data:
        items:
          type: integer
        type: array
      tokens_in:
        items:
          type: integer
        type: array
      tokens_out:
        items:
          type: integer
        type: array
    type: object
  api.TrendInfo:
    properties:
      delta:
        description: Percentage change from previous period (nil if no baseline)
        type: number
      direction:
        description: '"up", "down", "stable", or "new" (no baseline)'
        type: string
    type: object
  api.UpdateAccessRequest:
    properties:
      default_namespace:
        type: string
      namespaces:
        items:
          type: string
        type: array
      propagate_to_keys:
        type: boolean
    type: object
  api.UpdateAlertThresholdsRequest:
    properties:
      global_qps:
        type: integer
      master_rpd:
        type: integer
      master_rpm:
        type: integer
      master_tpd:
        type: integer
      master_tpm:
        type: integer
      min_rpm_requests_1m:
        type: integer
      min_tpm_tokens_1m:
        type: integer
    type: object
  api.UpdateIPBanRequest:
    properties:
      expires_at:
        $ref: '#/definitions/api.optionalInt64'
      reason:
        type: string
      status:
        type: string
    type: object
  api.UpdateMasterRequest:
    properties:
      global_qps:
        type: integer
      group:
        type: string
      max_child_keys:
        type: integer
      name:
        type: string
      propagate_to_keys:
        type: boolean
    type: object
  api.UpdateNamespaceRequest:
    properties:
      description:
        type: string
      name:
        type: string
      status:
        type: string
    type: object
  api.UpdateTokenRequest:
    properties:
      allow_ips:
        type: string
      deny_ips:
        type: string
      expires_at:
        type: string
      model_limits:
        type: string
      model_limits_enabled:
        type: boolean
      scopes:
        type: string
      status:
        description: active/suspended
        type: string
    type: object
  api.WhoamiRealtimeView:
    properties:
      qps:
        description: Current QPS
        example: 5
        type: integer
      qps_limit:
        description: QPS limit
        example: 100
        type: integer
      rate_limited:
        description: Whether currently rate limited
        example: false
        type: boolean
      requests:
        description: Total requests
        example: 100
        type: integer
      tokens:
        description: Total tokens used
        example: 50000
        type: integer
      updated_at:
        description: Last updated timestamp
        example: 1703505600
        type: integer
    type: object
  api.WhoamiResponse:
    properties:
      allow_ips:
        description: IP whitelist (for diagnostics)
        example: ""
        type: string
      created_at:
        example: 1703505600
        type: integer
      default_namespace:
        example: default
        type: string
      deny_ips:
        description: IP blacklist (for diagnostics)
        example: ""
        type: string
      epoch:
        example: 1
        type: integer
      expires_at:
        description: Expiration timestamp (0 = never)
        example: 0
        type: integer
      global_qps:
        example: 100
        type: integer
      group:
        example: default
        type: string
      id:
        description: Master fields (only present when type is "master")
        example: 1
        type: integer
      issued_at_epoch:
        example: 1
        type: integer
      issued_by:
        example: master
        type: string
      last_accessed_at:
        description: Last access timestamp
        example: 0
        type: integer
      master_id:
        description: Key fields (only present when type is "key")
        example: 1
        type: integer
      master_name:
        description: Parent master name (for display)
        example: tenant-a
        type: string
      max_child_keys:
        example: 5
        type: integer
      model_limits:
        description: Model restrictions
        example: gpt-4,claude
        type: string
      model_limits_enabled:
        description: Whether model limits are active
        example: false
        type: boolean
      name:
        example: tenant-a
        type: string
      namespaces:
        example: default,ns1
        type: string
      permissions:
        description: Admin permissions (always ["*"])
        items:
          type: string
        type: array
      quota_limit:
        description: Token quota limit (-1 = unlimited)
        example: -1
        type: integer
      quota_reset_at:
        description: Quota reset timestamp
        example: 0
        type: integer
      quota_reset_type:
        description: Quota reset type
        example: monthly
        type: string
      quota_used:
        description: Token quota used
        example: 0
        type: integer
      realtime:
        allOf:
        - $ref: '#/definitions/api.WhoamiRealtimeView'
        description: Realtime stats (for master and key types)
      request_count:
        description: Total request count (from DB)
        example: 0
        type: integer
      role:
        description: Admin fields (only present when type is "admin")
        example: admin
        type: string
      scopes:
        example: chat:write
        type: string
      status:
        example: active
        type: string
      type:
        description: 'Type of the authenticated identity: "admin", "master", or "key"'
        example: master
        type: string
      updated_at:
        example: 1703505600
        type: integer
      used_tokens:
        description: Total tokens used (from DB)
        example: 0
        type: integer
    type: object
  api.apiKeyStatsFlushEntry:
    properties:
      api_key_id:
        type: integer
      requests:
        type: integer
      success_requests:
        type: integer
    type: object
  api.apiKeyStatsFlushRequest:
    properties:
      keys:
        items:
          $ref: '#/definitions/api.apiKeyStatsFlushEntry'
        type: array
    type: object
  api.optionalInt64:
    properties:
      set:
        type: boolean
      value:
        format: int64
        type: integer
    type: object
  api.refreshModelRegistryRequest:
    properties:
      ref:
        type: string
    type: object
  api.reportAlertEntry:
    properties:
      fingerprint:
        type: string
      message:
        type: string
      metadata:
        type: string
      related_id:
        type: integer
      related_name:
        type: string
      related_type:
        type: string
      severity:
        type: string
      title:
        type: string
      type:
        type: string
    required:
    - severity
    - title
    - type
    type: object
  api.reportAlertsRequest:
    properties:
      alerts:
        items:
          $ref: '#/definitions/api.reportAlertEntry'
        type: array
    required:
    - alerts
    type: object
  api.reportAlertsResponse:
    properties:
      accepted:
        type: integer
      deduplicated:
        type: integer
      errors:
        items:
          type: string
        type: array
    type: object
  api.statsFlushEntry:
    properties:
      last_accessed_at:
        type: integer
      requests:
        type: integer
      token_hash:
        type: string
      tokens:
        type: integer
    type: object
  api.statsFlushRequest:
    properties:
      keys:
        items:
          $ref: '#/definitions/api.statsFlushEntry'
        type: array
    type: object
  dto.APIKeyDTO:
    description: API key create/update request
    properties:
      access_token:
        type: string
      account_id:
        type: string
      api_key:
        example: sk-xxx...
        type: string
      auto_ban:
        example: true
        type: boolean
      ban_reason:
        type: string
      ban_until:
        type: string
      expires_at:
        type: string
      group_id:
        example: 1
        type: integer
      project_id:
        type: string
      refresh_token:
        type: string
      status:
        example: active
        type: string
      weight:
        example: 1
        type: integer
    type: object
  dto.APIKeyResponse:
    description: API key response
    properties:
      access_token:
        type: string
      account_id:
        type: string
      api_key:
        example: sk-xxx...
        type: string
      auto_ban:
        example: true
        type: boolean
      ban_reason:
        type: string
      ban_until:
        type: string
      created_at:
        type: string
      expires_at:
        type: string
      failure_rate:
        example: 0.05
        type: number
      failure_requests:
        example: 50
        type: integer
      group_id:
        example: 1
        type: integer
      id:
        example: 1
        type: integer
      project_id:
        type: string
      status:
        example: active
        type: string
      success_rate:
        example: 0.95
        type: number
      success_requests:
        example: 950
        type: integer
      total_requests:
        example: 1000
        type: integer
      updated_at:
        type: string
      weight:
        example: 1
        type: integer
    type: object
  dto.BindingDTO:
    description: Binding create/update request
    properties:
      group_id:
        example: 1
        type: integer
      namespace:
        example: default
        type: string
      public_model:
        example: gpt-4
        type: string
      selector_type:
        example: exact
        type: string
      selector_value:
        example: gpt-4-turbo
        type: string
      status:
        example: active
        type: string
      weight:
        example: 1
        type: integer
    type: object
  dto.BindingResponse:
    description: Binding response
    properties:
      created_at:
        type: string
      group_id:
        example: 1
        type: integer
      id:
        example: 1
        type: integer
      namespace:
        example: default
        type: string
      public_model:
        example: gpt-4
        type: string
      selector_type:
        example: exact
        type: string
      selector_value:
        example: gpt-4-turbo
        type: string
      status:
        example: active
        type: string
      updated_at:
        type: string
      weight:
        example: 1
        type: integer
    type: object
  dto.DeleteResponse:
    description: Delete operation response
    properties:
      status:
        example: deleted
        type: string
    type: object
  dto.LogRecordRequest:
    description: Log record ingest request
    properties:
      audit_reason:
        type: string
      client_ip:
        example: 192.168.1.1
        type: string
      error_message:
        type: string
      group:
        example: default
        type: string
      key_id:
        example: 1
        type: integer
      latency_ms:
        example: 150
        type: integer
      master_id:
        example: 1
        type: integer
      model:
        example: gpt-4
        type: string
      provider_id:
        example: 1
        type: integer
      provider_name:
        example: openai-prod
        type: string
      provider_type:
        example: openai
        type: string
      request_body:
        type: string
      request_size:
        example: 1024
        type: integer
      response_body:
        type: string
      response_size:
        example: 2048
        type: integer
      status_code:
        example: 200
        type: integer
      tokens_in:
        example: 100
        type: integer
      tokens_out:
        example: 50
        type: integer
    type: object
  dto.LogWebhookConfigResponse:
    description: Log webhook configuration response
    properties:
      cooldown_seconds:
        example: 300
        type: integer
      enabled:
        example: true
        type: boolean
      secret:
        example: webhook-secret-key
        type: string
      status_code_threshold:
        example: 500
        type: integer
      threshold:
        example: 10
        type: integer
      url:
        example: https://webhook.example.com/alerts
        type: string
      window_seconds:
        example: 60
        type: integer
    type: object
  dto.ModelCacheFile:
    description: Cached model registry file
    properties:
      timestamp:
        type: integer
      version:
        type: string
    type: object
  dto.ModelDTO:
    description: Model create/update request
    properties:
      context_window:
        example: 128000
        type: integer
      cost_per_token:
        example: 3e-05
        type: number
      kind:
        example: chat
        type: string
      max_output_tokens:
        example: 4096
        type: integer
      name:
        example: gpt-4
        type: string
      supports_fim:
        example: false
        type: boolean
      supports_functions:
        example: true
        type: boolean
      supports_tool_choice:
        example: true
        type: boolean
      supports_vision:
        example: true
        type: boolean
    type: object
  dto.ModelRegistryCheckResponse:
    description: Model registry check result
    properties:
      current_upstream_ref:
        example: main
        type: string
      current_version:
        example: abc123
        type: string
      enabled:
        example: true
        type: boolean
      latest_version:
        example: def456
        type: string
      needs_refresh:
        example: true
        type: boolean
      upstream_ref:
        example: main
        type: string
    type: object
  dto.ModelRegistryStatusResponse:
    description: Model registry status response
    properties:
      cache_current:
        $ref: '#/definitions/dto.ModelCacheFile'
      cache_prev:
        $ref: '#/definitions/dto.ModelCacheFile'
      enabled:
        example: true
        type: boolean
      last_error:
        type: string
      last_refresh_at:
        example: 1704067200
        type: integer
      models_dev_ref:
        example: main
        type: string
      models_dev_url:
        example: https://models.dev/v1/models.json
        type: string
      redis_meta:
        additionalProperties:
          type: string
        type: object
    type: object
  dto.ModelResponse:
    description: Model response
    properties:
      context_window:
        example: 128000
        type: integer
      cost_per_token:
        example: 3e-05
        type: number
      created_at:
        type: string
      id:
        example: 1
        type: integer
      kind:
        example: chat
        type: string
      max_output_tokens:
        example: 4096
        type: integer
      name:
        example: gpt-4
        type: string
      supports_fim:
        example: false
        type: boolean
      supports_functions:
        example: true
        type: boolean
      supports_tool_choice:
        example: true
        type: boolean
      supports_vision:
        example: true
        type: boolean
      updated_at:
        type: string
    type: object
  dto.NamespaceDTO:
    description: Namespace create/update request
    properties:
      description:
        example: Default namespace
        type: string
      name:
        example: default
        type: string
      status:
        example: active
        type: string
    type: object
  dto.NamespaceResponse:
    description: Namespace response
    properties:
      created_at:
        type: string
      description:
        example: Default namespace
        type: string
      id:
        example: 1
        type: integer
      name:
        example: default
        type: string
      status:
        example: active
        type: string
      updated_at:
        type: string
    type: object
  dto.ProviderGroupDTO:
    description: Provider group create/update request
    properties:
      base_url:
        example: https://api.openai.com
        type: string
      google_location:
        type: string
      google_project:
        type: string
      headers_profile:
        type: string
      models:
        example:
        - gpt-4
        - gpt-3.5-turbo
        items:
          type: string
        type: array
      name:
        example: openai-prod
        type: string
      static_headers:
        type: string
      status:
        example: active
        type: string
      type:
        example: openai
        type: string
    type: object
  dto.ProviderGroupResponse:
    description: Provider group response
    properties:
      base_url:
        example: https://api.openai.com
        type: string
      created_at:
        type: string
      failure_rate:
        example: 0.05
        type: number
      failure_requests:
        example: 50
        type: integer
      google_location:
        type: string
      google_project:
        type: string
      headers_profile:
        type: string
      id:
        example: 1
        type: integer
      models:
        example: gpt-4,gpt-3.5-turbo
        type: string
      name:
        example: openai-prod
        type: string
      static_headers:
        type: string
      status:
        example: active
        type: string
      success_rate:
        example: 0.95
        type: number
      success_requests:
        example: 950
        type: integer
      total_requests:
        example: 1000
        type: integer
      type:
        example: openai
        type: string
      updated_at:
        type: string
    type: object
  dto.UpdateLogWebhookConfigRequest:
    description: Update log webhook configuration request
    properties:
      cooldown_seconds:
        example: 300
        type: integer
      enabled:
        example: true
        type: boolean
      secret:
        example: webhook-secret-key
        type: string
      status_code_threshold:
        example: 500
        type: integer
      threshold:
        example: 10
        type: integer
      url:
        example: https://webhook.example.com/alerts
        type: string
      window_seconds:
        example: 60
        type: integer
    type: object
host: localhost:8080
info:
  contact:
    email: support@swagger.io
    name: API Support
    url: http://www.swagger.io/support
  description: Management API for EZ-API Gateway system.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: EZ-API Control Plane
  version: 0.0.1
paths:
  /about:
    get:
      description: Returns system metadata for display on an about page
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AboutResponse'
              type: object
      summary: Get system information
      tags:
      - Public
  /admin/alerts:
    get:
      description: List system alerts with optional filters
      parameters:
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: offset
        in: query
        name: offset
        type: integer
      - description: filter by status (active, acknowledged, resolved, dismissed)
        in: query
        name: status
        type: string
      - description: filter by severity (info, warning, critical)
        in: query
        name: severity
        type: string
      - description: filter by type (rate_limit, error_spike, quota_exceeded, key_disabled,
          key_expired, provider_down, traffic_spike)
        in: query
        name: type
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.ListAlertsResponse'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List alerts
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: Create a new system alert
      parameters:
      - description: Alert data
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.CreateAlertRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AlertView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Create alert
      tags:
      - admin
  /admin/alerts/{id}:
    delete:
      description: Dismiss an alert (soft delete)
      parameters:
      - description: Alert ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Dismiss alert
      tags:
      - admin
    get:
      description: Get a single alert by ID
      parameters:
      - description: Alert ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AlertView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get alert
      tags:
      - admin
  /admin/alerts/{id}/ack:
    post:
      consumes:
      - application/json
      description: Mark an alert as acknowledged
      parameters:
      - description: Alert ID
        in: path
        name: id
        required: true
        type: integer
      - description: Ack data
        in: body
        name: request
        schema:
          $ref: '#/definitions/api.AckAlertRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AlertView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Acknowledge alert
      tags:
      - admin
  /admin/alerts/{id}/resolve:
    post:
      description: Mark an alert as resolved
      parameters:
      - description: Alert ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AlertView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Resolve alert
      tags:
      - admin
  /admin/alerts/stats:
    get:
      description: Get alert count statistics by status and severity
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AlertStats'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Alert statistics
      tags:
      - admin
  /admin/alerts/thresholds:
    get:
      description: Get current alert threshold configuration for traffic spike detection
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AlertThresholdView'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get alert thresholds
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Update alert threshold configuration for traffic spike detection
      parameters:
      - description: Threshold configuration
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.UpdateAlertThresholdsRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AlertThresholdView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update alert thresholds
      tags:
      - admin
  /admin/api-keys:
    get:
      description: List API keys with optional filters
      parameters:
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: filter by group_id
        in: query
        name: group_id
        type: integer
      - description: filter by status (active, suspended, auto_disabled, manual_disabled)
        in: query
        name: status
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/dto.APIKeyResponse'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List API keys
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: Create an API key for a provider group
      parameters:
      - description: API key payload
        in: body
        name: key
        required: true
        schema:
          $ref: '#/definitions/dto.APIKeyDTO'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.APIKeyResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Create an API key
      tags:
      - admin
  /admin/api-keys/{id}:
    delete:
      description: Delete an API key
      parameters:
      - description: APIKey ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete API key
      tags:
      - admin
    get:
      description: Get an API key by id
      parameters:
      - description: APIKey ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.APIKeyResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get API key
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Update an API key
      parameters:
      - description: APIKey ID
        in: path
        name: id
        required: true
        type: integer
      - description: API key payload
        in: body
        name: key
        required: true
        schema:
          $ref: '#/definitions/dto.APIKeyDTO'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.APIKeyResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update API key
      tags:
      - admin
  /admin/api-keys/batch:
    post:
      consumes:
      - application/json
      description: Batch delete or status update for api keys
      parameters:
      - description: Batch payload
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.BatchActionRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.BatchResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Batch api keys
      tags:
      - admin
  /admin/apikey-stats/summary:
    get:
      description: Aggregate APIKey success/failure stats across all provider groups
      parameters:
      - description: Start time (unix seconds)
        in: query
        name: since
        type: integer
      - description: End time (unix seconds)
        in: query
        name: until
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.APIKeyStatsSummaryResponse'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: APIKey stats summary (admin)
      tags:
      - admin
  /admin/bindings:
    get:
      description: List all configured bindings
      parameters:
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: search by namespace/public_model
        in: query
        name: search
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/dto.BindingResponse'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List bindings
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: Create a new (namespace, public_model) binding to a provider group
        and selector
      parameters:
      - description: Binding Info
        in: body
        name: binding
        required: true
        schema:
          $ref: '#/definitions/dto.BindingDTO'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.BindingResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Create a new binding
      tags:
      - admin
  /admin/bindings/{id}:
    delete:
      description: Delete a binding by id and rebuild bindings snapshot
      parameters:
      - description: Binding ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete a binding
      tags:
      - admin
    get:
      description: Get a binding by id
      parameters:
      - description: Binding ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.BindingResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get a binding
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Update an existing binding
      parameters:
      - description: Binding ID
        in: path
        name: id
        required: true
        type: integer
      - description: Binding Info
        in: body
        name: binding
        required: true
        schema:
          $ref: '#/definitions/dto.BindingDTO'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.BindingResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update a binding
      tags:
      - admin
  /admin/bindings/batch:
    post:
      consumes:
      - application/json
      description: Batch delete or status update for bindings
      parameters:
      - description: Batch payload
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.BatchActionRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.BatchResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Batch bindings
      tags:
      - admin
  /admin/dashboard/summary:
    get:
      description: Returns aggregated metrics for dashboard display including requests,
        tokens, latency, masters, keys, and provider keys statistics
      parameters:
      - description: 'time period: today, week, month, last7d, last30d, all'
        in: query
        name: period
        type: string
      - description: unix seconds
        in: query
        name: since
        type: integer
      - description: unix seconds
        in: query
        name: until
        type: integer
      - description: include trend data comparing to previous period
        in: query
        name: include_trends
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.DashboardSummaryResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Dashboard summary
      tags:
      - admin
  /admin/features:
    get:
      description: Returns all feature flags stored in Redis (meta:features)
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List feature flags
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Updates selected feature flags (meta:features). Values are stored
        as strings.
      parameters:
      - description: Feature map
        in: body
        name: request
        required: true
        schema:
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update feature flags
      tags:
      - admin
  /admin/ip-bans:
    get:
      consumes:
      - application/json
      description: List all global IP/CIDR ban rules
      parameters:
      - description: Filter by status (active, expired)
        in: query
        name: status
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/api.IPBanView'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List IP bans
      tags:
      - admin
      - ip-bans
    post:
      consumes:
      - application/json
      description: Create a new global IP/CIDR ban rule
      parameters:
      - description: IP Ban Info
        in: body
        name: ban
        required: true
        schema:
          $ref: '#/definitions/api.CreateIPBanRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.IPBanView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "409":
          description: Conflict
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Create an IP ban
      tags:
      - admin
      - ip-bans
  /admin/ip-bans/{id}:
    delete:
      consumes:
      - application/json
      description: Delete a global IP/CIDR ban rule
      parameters:
      - description: IP Ban ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "204":
          description: No Content
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete an IP ban
      tags:
      - admin
      - ip-bans
    get:
      consumes:
      - application/json
      description: Get a single global IP/CIDR ban rule by ID
      parameters:
      - description: IP Ban ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.IPBanView'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get an IP ban
      tags:
      - admin
      - ip-bans
    put:
      consumes:
      - application/json
      description: Update a global IP/CIDR ban rule
      parameters:
      - description: IP Ban ID
        in: path
        name: id
        required: true
        type: integer
      - description: IP Ban Update
        in: body
        name: ban
        required: true
        schema:
          $ref: '#/definitions/api.UpdateIPBanRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.IPBanView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "409":
          description: Conflict
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update an IP ban
      tags:
      - admin
      - ip-bans
  /admin/keys/{id}/access:
    get:
      description: Returns key default_namespace and namespaces
      parameters:
      - description: Key ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AccessResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get key access settings
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Updates key default_namespace and namespaces and syncs to Redis
      parameters:
      - description: Key ID
        in: path
        name: id
        required: true
        type: integer
      - description: Access settings
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.UpdateAccessRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AccessResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update key access settings
      tags:
      - admin
  /admin/logs:
    delete:
      consumes:
      - application/json
      description: Delete logs before a given timestamp with optional filters
      parameters:
      - description: Delete filters
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.DeleteLogsRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.DeleteLogsResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete logs (admin)
      tags:
      - admin
    get:
      description: List request logs with basic filtering/pagination. Returns full
        log records including request_body.
      parameters:
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: offset
        in: query
        name: offset
        type: integer
      - description: unix seconds
        in: query
        name: since
        type: integer
      - description: unix seconds
        in: query
        name: until
        type: integer
      - description: key id
        in: query
        name: key_id
        type: integer
      - description: route group
        in: query
        name: group
        type: string
      - description: model
        in: query
        name: model
        type: string
      - description: status code
        in: query
        name: status_code
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.ListLogsResponse'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List logs (admin)
      tags:
      - admin
  /admin/logs/stats:
    get:
      description: 'Aggregate log stats with basic filtering. Use group_by param for
        grouped statistics (model/day/month/hour/minute). Without group_by returns
        LogStatsResponse; with group_by returns GroupedStatsResponse. Note: minute-level
        aggregation is limited to 6-hour time ranges.'
      parameters:
      - description: unix seconds
        in: query
        name: since
        type: integer
      - description: unix seconds
        in: query
        name: until
        type: integer
      - description: 'group by dimension: model, day, month, hour, minute. Returns
          GroupedStatsResponse when specified.'
        enum:
        - model
        - day
        - month
        - hour
        - minute
        in: query
        name: group_by
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Grouped stats (when group_by is specified)
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.GroupedStatsResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Log stats (admin)
      tags:
      - admin
  /admin/logs/stats/traffic-chart:
    get:
      description: Get time × model aggregated data for stacked traffic charts. Returns
        a shared time axis under `x` and per-model series arrays aligned to that axis.
        Models outside top_n are aggregated under the series name "other".
      parameters:
      - description: 'Time granularity: hour (default) or minute'
        enum:
        - hour
        - minute
        in: query
        name: granularity
        type: string
      - description: Start time (unix seconds), defaults to 24h ago
        in: query
        name: since
        type: integer
      - description: End time (unix seconds), defaults to now
        in: query
        name: until
        type: integer
      - description: Number of top models to return (1-20), defaults to 5
        in: query
        name: top_n
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.TrafficChartResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Traffic chart data (admin)
      tags:
      - admin
  /admin/logs/webhook:
    get:
      description: Returns current webhook notification config
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.LogWebhookConfigResponse'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get log webhook config
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Updates webhook notification config
      parameters:
      - description: Webhook config
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/dto.UpdateLogWebhookConfigRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.LogWebhookConfigResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update log webhook config
      tags:
      - admin
  /admin/masters:
    get:
      description: List all master tenants
      parameters:
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: search by name/group
        in: query
        name: search
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/api.MasterView'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List masters
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: Create a new master account (tenant)
      parameters:
      - description: Master Info
        in: body
        name: master
        required: true
        schema:
          $ref: '#/definitions/api.CreateMasterRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Create a new master tenant
      tags:
      - admin
  /admin/masters/{id}:
    delete:
      description: Suspends a master and revokes all existing keys by bumping epoch
        and syncing to Redis
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete (revoke) master
      tags:
      - admin
    get:
      description: Get a master tenant by id
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MasterView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get master
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Update master fields; optionally propagate group to existing keys
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      - description: Update payload
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.UpdateMasterRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MasterView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update master
      tags:
      - admin
  /admin/masters/{id}/access:
    get:
      description: Returns master default_namespace and namespaces
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AccessResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get master access settings
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Updates master default_namespace and namespaces; optionally propagate
        to existing keys
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      - description: Access settings
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.UpdateAccessRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AccessResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update master access settings
      tags:
      - admin
  /admin/masters/{id}/keys:
    get:
      description: List child keys issued under a master (admin view)
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: search by group/scopes/namespaces/status
        in: query
        name: search
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/api.TokenView'
                  type: array
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List child keys for a master
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: Issue a new access token (child key) for a specified master. The
        key still belongs to the master; issuer is recorded as admin for audit.
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      - description: Key Request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.IssueChildKeyRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "403":
          description: Forbidden
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Issue a child key on behalf of a master
      tags:
      - admin
  /admin/masters/{id}/keys/{key_id}:
    delete:
      description: Revokes and removes a child key under the specified master
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      - description: Token ID
        in: path
        name: key_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.DeleteResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete child key
      tags:
      - admin
  /admin/masters/{id}/manage:
    post:
      consumes:
      - application/json
      description: Freeze or unfreeze a master tenant
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      - description: Action
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.ManageMasterRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MasterView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Manage master status
      tags:
      - admin
  /admin/masters/{id}/realtime:
    get:
      description: Return realtime counters for the specified master
      parameters:
      - description: Master ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MasterRealtimeView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Master realtime stats (admin)
      tags:
      - admin
  /admin/masters/batch:
    post:
      consumes:
      - application/json
      description: Batch delete or status update for masters
      parameters:
      - description: Batch payload
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.BatchActionRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.BatchResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Batch masters
      tags:
      - admin
  /admin/model-registry/check:
    post:
      consumes:
      - application/json
      description: Checks models.dev commit SHA for a ref and indicates whether refresh
        is needed (does not apply changes)
      parameters:
      - description: optional override ref
        in: body
        name: body
        schema:
          $ref: '#/definitions/api.refreshModelRegistryRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.ModelRegistryCheckResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Check model registry upstream version
      tags:
      - admin
  /admin/model-registry/refresh:
    post:
      consumes:
      - application/json
      description: Fetches models.dev, computes per-binding capabilities, and updates
        Redis meta:models
      parameters:
      - description: optional override ref
        in: body
        name: body
        schema:
          $ref: '#/definitions/api.refreshModelRegistryRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Refresh model registry from models.dev
      tags:
      - admin
  /admin/model-registry/rollback:
    post:
      description: Rollback meta:models to previous cached last-good version
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Rollback model registry
      tags:
      - admin
  /admin/model-registry/status:
    get:
      description: Returns Redis meta and local last-good cache info for model capability
        registry
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.ModelRegistryStatusResponse'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get model registry status
      tags:
      - admin
  /admin/models:
    get:
      description: Get a list of all registered models
      parameters:
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: search by name/kind
        in: query
        name: search
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/dto.ModelResponse'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List all models
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: Register a supported model with its capabilities
      parameters:
      - description: Model Info
        in: body
        name: model
        required: true
        schema:
          $ref: '#/definitions/dto.ModelDTO'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.ModelResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Register a new model
      tags:
      - admin
  /admin/models/{id}:
    delete:
      description: Delete a model by id
      parameters:
      - description: Model ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete a model
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Update an existing model's configuration
      parameters:
      - description: Model ID
        in: path
        name: id
        required: true
        type: integer
      - description: Model Info
        in: body
        name: model
        required: true
        schema:
          $ref: '#/definitions/dto.ModelDTO'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.ModelResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update a model
      tags:
      - admin
  /admin/models/batch:
    post:
      consumes:
      - application/json
      description: Batch delete for models
      parameters:
      - description: Batch payload
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.BatchActionRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.BatchResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Batch models
      tags:
      - admin
  /admin/namespaces:
    get:
      description: List all namespaces
      parameters:
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: search by name/description
        in: query
        name: search
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/dto.NamespaceResponse'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List namespaces
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: Create a namespace for bindings
      parameters:
      - description: Namespace payload
        in: body
        name: namespace
        required: true
        schema:
          $ref: '#/definitions/dto.NamespaceDTO'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.NamespaceResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Create namespace
      tags:
      - admin
  /admin/namespaces/{id}:
    delete:
      description: Delete a namespace and its bindings
      parameters:
      - description: Namespace ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete namespace
      tags:
      - admin
    get:
      description: Get a namespace by id
      parameters:
      - description: Namespace ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.NamespaceResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get namespace
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Update a namespace
      parameters:
      - description: Namespace ID
        in: path
        name: id
        required: true
        type: integer
      - description: Update payload
        in: body
        name: namespace
        required: true
        schema:
          $ref: '#/definitions/api.UpdateNamespaceRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.NamespaceResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update namespace
      tags:
      - admin
  /admin/operation-logs:
    get:
      description: List admin operation logs
      parameters:
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: search by actor/method/path
        in: query
        name: search
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/api.OperationLogView'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List operation logs
      tags:
      - admin
  /admin/provider-groups:
    get:
      description: List all provider groups
      parameters:
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: search by name/type
        in: query
        name: search
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/dto.ProviderGroupResponse'
                  type: array
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: List provider groups
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: Create a provider group definition
      parameters:
      - description: Provider group payload
        in: body
        name: group
        required: true
        schema:
          $ref: '#/definitions/dto.ProviderGroupDTO'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.ProviderGroupResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Create a provider group
      tags:
      - admin
  /admin/provider-groups/{id}:
    delete:
      description: Delete a provider group and its api keys/bindings
      parameters:
      - description: ProviderGroup ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Delete provider group
      tags:
      - admin
    get:
      description: Get a provider group by id
      parameters:
      - description: ProviderGroup ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.ProviderGroupResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Get provider group
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: Update a provider group
      parameters:
      - description: ProviderGroup ID
        in: path
        name: id
        required: true
        type: integer
      - description: Provider group payload
        in: body
        name: group
        required: true
        schema:
          $ref: '#/definitions/dto.ProviderGroupDTO'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/dto.ProviderGroupResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Update provider group
      tags:
      - admin
  /admin/realtime:
    get:
      description: Return aggregated realtime counters across all masters
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.SystemRealtimeView'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: System-level realtime stats (admin)
      tags:
      - admin
  /admin/stats:
    get:
      description: Aggregate request stats across all masters
      parameters:
      - description: today|week|month|all
        in: query
        name: period
        type: string
      - description: unix seconds
        in: query
        name: since
        type: integer
      - description: unix seconds
        in: query
        name: until
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.AdminUsageStatsResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Usage stats (admin)
      tags:
      - admin
  /admin/sync/snapshot:
    post:
      description: Force full synchronization of DB state to Redis
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      summary: Force sync snapshot
      tags:
      - admin
  /auth/whoami:
    get:
      description: |-
        Returns complete identity and realtime statistics of the authenticated user.
        Supports Admin Token, Master Key, and Child Key (API Key) authentication.
        This endpoint is designed for frontend initialization - call once after login
        and store the response for subsequent use.

        **Response varies by token type:**

        **Admin Token:**
        - type: "admin"
        - role: "admin"
        - permissions: ["*"] (full access)

        **Master Key:**
        - type: "master"
        - Basic info: id, name, group, namespaces, status, epoch, max_child_keys, global_qps
        - Timestamps: created_at, updated_at
        - Realtime stats: requests, tokens, qps, qps_limit, rate_limited

        **Child Key (API Key):**
        - type: "key"
        - Basic info: id, master_id, master_name, group, scopes, namespaces, status
        - Security: issued_at_epoch, issued_by, allow_ips, deny_ips, expires_at
        - Model limits: model_limits, model_limits_enabled
        - Quota: quota_limit, quota_used, quota_reset_at, quota_reset_type
        - Usage stats: request_count, used_tokens, last_accessed_at
        - Realtime stats: requests, tokens, qps, qps_limit, rate_limited

        **Error responses:**
        - 401: authorization header required
        - 401: invalid authorization header format
        - 401: invalid token
        - 401: token is not active
        - 401: token has expired
        - 401: token has been revoked
        - 401: master is not active
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.WhoamiResponse'
              type: object
        "401":
          description: Invalid or missing token
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - AdminAuth: []
      - MasterAuth: []
      summary: Get current identity
      tags:
      - auth
  /internal/alerts/report:
    post:
      consumes:
      - application/json
      description: Internal endpoint for Data Plane to report alerts to Control Plane
      parameters:
      - description: Alerts to report
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.reportAlertsRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.reportAlertsResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      summary: Report alerts from DP
      tags:
      - internal
  /internal/apikey-stats/flush:
    post:
      consumes:
      - application/json
      description: Internal endpoint for flushing accumulated APIKey stats from DP
        to CP database
      parameters:
      - description: Stats to flush
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.apiKeyStatsFlushRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      summary: Flush API key stats
      tags:
      - internal
  /internal/stats/flush:
    post:
      consumes:
      - application/json
      description: Internal endpoint for flushing accumulated key usage stats from
        DP to CP database
      parameters:
      - description: Stats to flush
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.statsFlushRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      summary: Flush key stats
      tags:
      - internal
  /logs:
    post:
      consumes:
      - application/json
      description: Internal endpoint for ingesting logs from Balancer
      parameters:
      - description: Log Record
        in: body
        name: log
        required: true
        schema:
          $ref: '#/definitions/dto.LogRecordRequest'
      produces:
      - application/json
      responses:
        "202":
          description: Accepted
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      summary: Ingest logs
      tags:
      - system
  /status:
    get:
      description: Returns public runtime status information without sensitive data
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.StatusResponse'
              type: object
      summary: Get system status
      tags:
      - Public
  /v1/logs:
    get:
      description: List request logs for the authenticated master
      parameters:
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: offset
        in: query
        name: offset
        type: integer
      - description: unix seconds
        in: query
        name: since
        type: integer
      - description: unix seconds
        in: query
        name: until
        type: integer
      - description: model
        in: query
        name: model
        type: string
      - description: status code
        in: query
        name: status_code
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.ListMasterLogsResponse'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: List logs (master)
      tags:
      - master
  /v1/logs/stats:
    get:
      description: Aggregate request log stats for the authenticated master
      parameters:
      - description: unix seconds
        in: query
        name: since
        type: integer
      - description: unix seconds
        in: query
        name: until
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.LogStatsResponse'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: Log stats (master)
      tags:
      - master
  /v1/realtime:
    get:
      description: Return realtime counters for the authenticated master
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MasterRealtimeView'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: Master realtime stats
      tags:
      - master
  /v1/self:
    get:
      description: Returns master metadata for the authenticated master key
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MasterView'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: Get current master info
      tags:
      - master
  /v1/stats:
    get:
      description: Aggregate request stats for the authenticated master
      parameters:
      - description: today|week|month|all
        in: query
        name: period
        type: string
      - description: unix seconds
        in: query
        name: since
        type: integer
      - description: unix seconds
        in: query
        name: until
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MasterUsageStatsResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: Usage stats (master)
      tags:
      - master
  /v1/tokens:
    get:
      description: List child keys issued under the authenticated master
      parameters:
      - description: page (1-based)
        in: query
        name: page
        type: integer
      - description: limit (default 50, max 200)
        in: query
        name: limit
        type: integer
      - description: search by group/scopes/namespaces/status
        in: query
        name: search
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/api.TokenView'
                  type: array
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: List child keys
      tags:
      - master
    post:
      consumes:
      - application/json
      description: Issue a new access token (child key) for the authenticated master
      parameters:
      - description: Key Request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.IssueChildKeyRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "403":
          description: Forbidden
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: Issue a child key
      tags:
      - master
  /v1/tokens/{id}:
    delete:
      description: Suspends a child key under the authenticated master
      parameters:
      - description: Token ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: Delete (revoke) child key
      tags:
      - master
    get:
      description: Get a child key by id under the authenticated master
      parameters:
      - description: Token ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.TokenView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: Get child key
      tags:
      - master
    put:
      consumes:
      - application/json
      description: Update token scopes/status under the authenticated master
      parameters:
      - description: Token ID
        in: path
        name: id
        required: true
        type: integer
      - description: Update payload
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.UpdateTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.TokenView'
              type: object
        "400":
          description: Bad Request
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "404":
          description: Not Found
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/api.ResponseEnvelope'
            - properties:
                data:
                  $ref: '#/definitions/api.MapData'
              type: object
      security:
      - MasterAuth: []
      summary: Update child key
      tags:
      - master
securityDefinitions:
  AdminAuth:
    description: 'Type "Bearer" followed by a space and the admin token. Example:
      Bearer admin123'
    in: header
    name: Authorization
    type: apiKey
  MasterAuth:
    description: 'Type "Bearer" followed by a space and the master key. Example: Bearer
      sk-xxx'
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"