openapi: 3.1.0
info:
  title: Chamber Capacity Metrics API
  version: 1.0.0
  description: The Chamber REST API provides programmatic access to manage GPU capacity, monitor workloads, and query GPU metrics across your organization. Chamber is an AIOps control plane for enterprise AI infrastructure that helps ML teams monitor, diagnose, and resolve GPU workload issues across AWS, GCP, Azure, and on-premise clusters. All requests (except the health check) require a Bearer token and an organization context header.
  contact:
    name: Chamber Support
    email: support@usechamber.io
    url: https://docs.usechamber.io/api-reference/introduction
  x-provider: Chamber
  x-source: https://docs.usechamber.io/api-reference/introduction
servers:
- url: https://api.usechamber.io/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Metrics
  description: Query GPU utilization, memory, temperature, and power metrics
paths:
  /workloads/metrics:
    get:
      operationId: listRankedWorkloadMetrics
      summary: Get ranked workload metrics
      description: Retrieve metrics across workloads, ranked by utilization or consumption.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: sort_by
        in: query
        description: Sort metric
        schema:
          type: string
          enum:
          - gpu_utilization
          - memory_utilization
          - power_usage
          - gpu_hours
      - name: order
        in: query
        description: Sort order
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - $ref: '#/components/parameters/LimitParam'
      - name: initiative_id
        in: query
        description: Filter to specific team
        schema:
          type: string
      - name: status
        in: query
        description: Filter by workload status
        schema:
          type: string
      responses:
        '200':
          description: Ranked workload metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  metadata:
                    $ref: '#/components/schemas/PageMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /workloads/{workload_id}/metrics:
    get:
      operationId: getWorkloadMetrics
      summary: Get workload metrics
      description: Retrieve GPU metrics for a specific workload.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/WorkloadIdPath'
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: time_range
        in: query
        description: Time range for the metrics window
        schema:
          type: string
          enum:
          - last_1h
          - last_6h
          - last_24h
          - job_lifetime
          default: last_1h
      - name: metrics
        in: query
        description: Comma-separated list of metrics to include
        schema:
          type: string
      responses:
        '200':
          description: GPU metrics for the workload
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  request_id:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PageMetadata:
      type: object
      properties:
        next_token:
          type: string
        total_count:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: object
        request_id:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The caller's role does not permit access to this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    WorkloadIdPath:
      name: workload_id
      in: path
      required: true
      description: The unique workload identifier
      schema:
        type: string
    LimitParam:
      name: limit
      in: query
      description: Number of results per page (1-100, default 20)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    OrganizationIdHeader:
      name: X-Organization-Id
      in: header
      required: true
      description: Your organization ID (not required for /health).
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token — a JWT from Cognito or a Chamber API token (prefix `ch.`). Generate API tokens in the dashboard under Settings > API Tokens.