YugabyteDB Universe information API

openapi: 3.2.0
info:
  title: Yugabytedb Universe information API
  version: v1
  contact:
    name: https://docs.yugabyte.com
  license:
    name: Polyform Free Trial License 1.0.0
    url: https://github.com/yugabyte/yugabyte-db/blob/master/licenses/POLYFORM-FREE-TRIAL-LICENSE-1.0.0.txt
  termsOfService: TODO(chirag)
  description: 'Operations tagged Universe information across 2 of this provider''s published API definitions: openapi_2.yaml, platform.swagger.json. Each path carries the servers of the definition it was published in.'
servers:
- url: /
tags:
- name: Universe information
paths:
  /api/v1/customers/{cUUID}/cost:
    get:
      description: YbaApi Internal. (Will be removed in next iteration)
      operationId: getUniverseCostForAll
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UniverseResourceDetails'
                type: array
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Get a cost estimate for all universes
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/cost:
    get:
      deprecated: true
      description: 'Deprecated since YBA version 2.20.0.0.

        Use /universe_resources'
      operationId: getUniverseCost
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniverseResourceDetails'
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Get a cost estimate for a universe - deprecated
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/health_check:
    get:
      description: Available since YBA version 2.2.0.0. Checks the health of all tablet servers and masters in the universe, as well as certain conditions on the machines themselves, including disk utilization, presence of FATAL or core files, and more.
      operationId: healthCheckUniverse
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Details'
                type: array
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Return results for the last health check
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/leader:
    get:
      description: Available since YBA version 2.2.0.0.
      operationId: getMasterLeaderIP
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Get IP address of a universe's master leader
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/live_queries:
    get:
      description: Available since YBA version 2.4.0.0.
      operationId: getLiveQueries
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Get live queries for a universe
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/master_infos:
    get:
      description: YbaApi Internal.
      operationId: getMasterInfos
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/MasterInfo'
                type: array
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Get master information list
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/slow_queries:
    delete:
      description: Available since YBA version 2.6.0.0.
      operationId: resetSlowQueries
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: query
        name: request
        schema: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Reset slow queries for a universe
      tags:
      - Universe information
    get:
      description: Available since YBA version 2.6.0.0.
      operationId: getSlowQueries
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Get slow queries for a universe
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/status:
    get:
      description: Available since YBA version 2.2.0.0. This will return a Map of node name to its status in json format.
      operationId: universeStatus
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  properties: {}
                  type: object
                type: object
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Get a universe's status
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/trigger_health_check:
    get:
      description: YbaApi Internal. Trigger a universe health check and return the trigger time.
      operationId: triggerHealthCheck
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerHealthCheckResult'
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Trigger a universe health check
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/universe_resources:
    get:
      description: Available since YBA version 2.20.0.0. Expects UniverseDefinitionTaskParams in request body and calculates the resource estimate for NodeDetailsSet in that.
      operationId: getUniverseResources
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniverseResourceDetails'
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Get a resource usage estimate for a universe
      tags:
      - Universe information
    servers:
    - url: /
  /api/v1/customers/{cUUID}/universes/{uniUUID}/{nodeName}/download_logs:
    get:
      deprecated: true
      description: 'Deprecated since YBA version 2.20.0.0.

        User Support bundle. Downloads the log files from a given node.'
      operationId: downloadNodeLogs
      parameters:
      - in: path
        name: cUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: uniUUID
        required: true
        schema:
          format: uuid
          type: string
      - in: path
        name: nodeName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/x-compressed:
              schema:
                type: string
          description: successful operation
      security:
      - apiKeyAuth: []
      summary: Download a node's logs - deprecated
      tags:
      - Universe information
    servers:
    - url: /
components:
  schemas:
    TriggerHealthCheckResult:
      description: The response type for triggering a health check. Contains the timestamp of when the health check was triggered.
      example:
        timestamp: 2022-12-12 13:07:18+00:00
      properties:
        timestamp:
          description: The ISO-8601 timestamp when the health check was triggered.
          example: 2022-12-12 13:07:18+00:00
          format: date-time
          type: string
      type: object
    MetricLabel:
      example:
        name: name
        value: value
      properties:
        name:
          type: string
        value:
          type: string
      required:
      - name
      - value
      type: object
    UniverseResourceDetails:
      example:
        numCores: 5.637376656633329
        volumeSizeGB: 3
        gp3FreeThroughput: 1
        numNodes: 2
        memSizeGB: 5.962133916683182
        azList:
        - azList
        - azList
        pricePerHour: 7.061401241503109
        volumeCount: 9
        pricingKnown: true
        gp3FreePiops: 6
        ebsPricePerHour: 0.8008281904610115
      properties:
        azList:
          description: Azs
          items:
            type: string
          type: array
          uniqueItems: true
        ebsPricePerHour:
          description: EBS price per hour
          format: double
          type: number
        gp3FreePiops:
          description: gp3 free piops
          format: int32
          type: integer
        gp3FreeThroughput:
          description: gp3 free throughput
          format: int32
          type: integer
        memSizeGB:
          description: Memory GB
          format: double
          type: number
        numCores:
          description: Numbers of cores
          format: double
          type: number
        numNodes:
          description: Numbers of node
          format: int32
          type: integer
        pricePerHour:
          description: Price per hour
          format: double
          type: number
        pricingKnown:
          description: Known pricing info
          type: boolean
        volumeCount:
          description: Volume count
          format: int32
          type: integer
        volumeSizeGB:
          description: Volume in GB
          format: int32
          type: integer
      type: object
    MasterInfo:
      description: Information about master
      example:
        port: 0
        peerRole: FOLLOWER
        privateIp: privateIp
        instanceUUID: instanceUUID
        uptimeSeconds: 6
      properties:
        instanceUUID:
          type: string
        peerRole:
          enum:
          - FOLLOWER
          - LEADER
          - LEARNER
          - NON_PARTICIPANT
          - READ_REPLICA
          - UNKNOWN_ROLE
          type: string
        port:
          format: int32
          type: integer
        privateIp:
          type: string
        uptimeSeconds:
          format: int64
          type: integer
      required:
      - instanceUUID
      - peerRole
      - port
      - privateIp
      - uptimeSeconds
      type: object
    MetricValue:
      example:
        value: 0.8008281904610115
        labels:
        - name: name
          value: value
        - name: name
          value: value
      properties:
        labels:
          items:
            $ref: '#/components/schemas/MetricLabel'
          type: array
        value:
          format: double
          type: number
      required:
      - labels
      - value
      type: object
    Metric:
      example:
        help: help
        unit: unit
        values:
        - value: 0.8008281904610115
          labels:
          - name: name
            value: value
          - name: name
            value: value
        - value: 0.8008281904610115
          labels:
          - name: name
            value: value
          - name: name
            value: value
        name: name
      properties:
        help:
          type: string
        name:
          type: string
        unit:
          type: string
        values:
          items:
            $ref: '#/components/schemas/MetricValue'
          type: array
      required:
      - help
      - name
      - unit
      - values
      type: object
    Details:
      example:
        timestamp_iso: 2022-12-12 13:07:18+00:00
        data:
        - node: node
          process: process
          timestamp_iso: 2022-12-12 13:07:18+00:00
          metrics_only: true
          has_warning: true
          node_name: node_name
          details:
          - details
          - details
          metrics:
          - help: help
            unit: unit
            values:
            - value: 0.8008281904610115
              labels:
              - name: name
                value: value
              - name: name
                value: value
            - value: 0.8008281904610115
              labels:
              - name: name
                value: value
              - name: name
                value: value
            name: name
          - help: help
            unit: unit
            values:
            - value: 0.8008281904610115
              labels:
              - name: name
                value: value
              - name: name
                value: value
            - value: 0.8008281904610115
              labels:
              - name: name
                value: value
              - name: name
                value: value
            name: name
          node_identifier: node_identifier
          message: message
          has_error: true
        - node: node
          process: process
          timestamp_iso: 2022-12-12 13:07:18+00:00
          metrics_only: true
          has_warning: true
          node_name: node_name
          details:
          - details
          - details
          metrics:
          - help: help
            unit: unit
            values:
            - value: 0.8008281904610115
              labels:
              - name: name
                value: value
              - name: name
                value: value
            - value: 0.8008281904610115
              labels:
              - name: name
                value: value
              - name: name
                value: value
            name: name
          - help: help
            unit: unit
            values:
            - value: 0.8008281904610115
              labels:
              - name: name
                value: value
              - name: name
                value: value
            - value: 0.8008281904610115
              labels:
              - name: name
                value: value
              - name: name
                value: value
            name: name
          node_identifier: node_identifier
          message: message
          has_error: true
        has_warning: true
        has_error: true
        yb_version: yb_version
      properties:
        data:
          items:
            $ref: '#/components/schemas/NodeData'
          type: array
        has_error:
          type: boolean
        has_warning:
          type: boolean
        timestamp_iso:
          example: 2022-12-12 13:07:18+00:00
          format: date-time
          type: string
        yb_version:
          type: string
      required:
      - data
      - has_error
      - has_warning
      - yb_version
      type: object
    NodeData:
      example:
        node: node
        process: process
        timestamp_iso: 2022-12-12 13:07:18+00:00
        metrics_only: true
        has_warning: true
        node_name: node_name
        details:
        - details
        - details
        metrics:
        - help: help
          unit: unit
          values:
          - value: 0.8008281904610115
            labels:
            - name: name
              value: value
            - name: name
              value: value
          - value: 0.8008281904610115
            labels:
            - name: name
              value: value
            - name: name
              value: value
          name: name
        - help: help
          unit: unit
          values:
          - value: 0.8008281904610115
            labels:
            - name: name
              value: value
            - name: name
              value: value
          - value: 0.8008281904610115
            labels:
            - name: name
              value: value
            - name: name
              value: value
          name: name
        node_identifier: node_identifier
        message: message
        has_error: true
      properties:
        details:
          items:
            type: string
          type: array
        has_error:
          type: boolean
        has_warning:
          type: boolean
        message:
          type: string
        metrics:
          items:
            $ref: '#/components/schemas/Metric'
          type: array
        metrics_only:
          type: boolean
        node:
          type: string
        node_identifier:
          type: string
        node_name:
          type: string
        process:
          type: string
        timestamp_iso:
          example: 2022-12-12 13:07:18+00:00
          format: date-time
          type: string
      required:
      - details
      - has_error
      - has_warning
      - message
      - metrics
      - metrics_only
      - node
      - node_identifier
      - node_name
      - process
      type: object
    UniverseResourceDetails_2:
      properties:
        azList:
          description: Azs
          items:
            type: string
          type: array
          uniqueItems: true
        ebsPricePerHour:
          description: EBS price per hour
          format: double
          type: number
        gp3FreePiops:
          description: gp3 free piops
          format: int32
          type: integer
        gp3FreeThroughput:
          description: gp3 free throughput
          format: int32
          type: integer
        memSizeGB:
          description: Memory GB
          format: double
          type: number
        numCores:
          description: Numbers of cores
          format: double
          type: number
        numNodes:
          description: Numbers of node
          format: int32
          type: integer
        pricePerHour:
          description: Price per hour
          format: double
          type: number
        pricingKnown:
          description: Known pricing info
          type: boolean
        volumeCount:
          description: Volume count
          format: int32
          type: integer
        volumeSizeGB:
          description: Volume in GB
          format: int32
          type: integer
      type: object
    TriggerHealthCheckResult_2:
      description: The response type for triggering a health check. Contains the timestamp of when the health check was triggered.
      properties:
        timestamp:
          description: The ISO-8601 timestamp when the health check was triggered.
          format: date-time
          type: string
      type: object
  securitySchemes:
    apiKeyAuth:
      description: API token passed as header
      in: header
      name: X-AUTH-YW-API-TOKEN
      type: apiKey
externalDocs:
  description: About YugabyteDB Anywhere
  url: https://docs.yugabyte.com/latest/yugabyte-platform/
x-refined-from:
- openapi_2.yaml
- platform.swagger.json