openapi: 3.0.0
info:
  title: Yugabyte Cloud
  description: YugabyteDB as a Service
  termsOfService: https://www.yugabyte.com/yugabyte-cloud-terms-of-service
  version: v1
  contact:
    name: Yugabyte Cloud Support
    url: https://support.yugabyte.com/
    email: support@yugabyte.com
  license:
    name: Properietary (TBD)
    url: https://www.yugabyte.com/yugabyte-cloud-terms-of-service
servers:
  - url: '{protocol}://{host_port}/api'
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      host_port:
        default: localhost:1323
    description: Endpoint of the API server
tags:
  - name: cluster
    description: APIs for cluster CRUD
  - name: cluster-info
    description: APIs for getting information about an existing cluster
paths:
  /cluster:
    get:
      summary: Get a cluster
      description: Get a Yugabyte Cluster
      operationId: getCluster
      tags:
        - cluster
      responses:
        '200':
          $ref: '#/components/responses/ClusterResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
    delete:
      summary: Submit task to delete a cluster
      description: Submit task to delete a Yugabyte Cluster
      tags:
        - cluster
      responses:
        '200':
          description: Successfully submitted delete cluster request
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
      operationId: deleteCluster
    put:
      summary: Submit task to edit a cluster
      description: Submit task to edit a Yugabyte Cluster
      operationId: editCluster
      tags:
        - cluster
      requestBody:
        $ref: '#/components/requestBodies/ClusterSpec'
      responses:
        '200':
          $ref: '#/components/responses/ClusterResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
  /live_queries:
    get:
      summary: Get the live queries in a cluster
      description: Get the Live Queries in a Yugabyte Cluster
      operationId: getLiveQueries
      tags:
        - cluster-info
      parameters:
        - name: api
          in: query
          description: type of queries for which to retrieve Live Queries (YSQL or YCQL)
          required: false
          style: form
          explode: false
          schema:
            type: string
            enum:
              - YSQL
              - YCQL
      responses:
        '200':
          $ref: '#/components/responses/LiveQueryResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
  /slow_queries:
    get:
      summary: Get the slow queries in a cluster
      description: Get the Slow Queries in a Yugabyte Cluster
      operationId: getSlowQueries
      tags:
        - cluster-info
      responses:
        '200':
          $ref: '#/components/responses/SlowQueryResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
  /nodes:
    get:
      summary: Get the nodes for a cluster
      description: Get nodes for a Yugabyte cluster
      operationId: getClusterNodes
      tags:
        - cluster-info
      responses:
        '200':
          $ref: '#/components/responses/ClusterNodeListResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
  /metrics:
    parameters:
      - name: metrics
        in: query
        description: Which metrics to retrieve results for
        required: true
        style: form
        explode: false
        schema:
          type: string
      - name: node_name
        in: query
        description: Node name within the cluster
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: region
        in: query
        description: Region name to filter for the given cluster
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: start_time
        in: query
        description: Start of range of time series data (in epoch seconds)
        required: false
        style: form
        explode: false
        schema:
          type: integer
          format: int64
          minimum: 0
      - name: end_time
        in: query
        description: End of range of time series data (in epoch seconds)
        required: false
        style: form
        explode: false
        schema:
          type: integer
          format: int64
          minimum: 0
    get:
      summary: Get a metric for a cluster
      description: Get metrics for a Yugabyte cluster
      operationId: getClusterMetric
      tags:
        - cluster-info
      responses:
        '200':
          $ref: '#/components/responses/MetricResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
  /tables:
    get:
      description: Get list of tables per YB API (YCQL/YSQL)
      operationId: getClusterTables
      summary: Get list of DB tables per YB API (YCQL/YSQL)
      tags:
        - cluster-info
      parameters:
        - name: api
          in: query
          description: Which DB API to get tables for (YCQL/YSQL)
          required: false
          style: form
          explode: false
          schema:
            type: string
            enum:
              - YCQL
              - YSQL
      responses:
        '200':
          $ref: '#/components/responses/ClusterTableListResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
  /health-check:
    get:
      description: Get health information about the cluster
      operationId: getClusterHealthCheck
      summary: Get health information about the cluster
      tags:
        - cluster-info
      responses:
        '200':
          $ref: '#/components/responses/HealthCheckResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
  /tablets:
    get:
      description: Get list of tablets
      operationId: getClusterTablets
      summary: Get list of tablets
      tags:
        - cluster-info
      responses:
        '200':
          $ref: '#/components/responses/ClusterTabletListResponse'
        '400':
          $ref: '#/components/responses/ApiError'
        '500':
          $ref: '#/components/responses/ApiError'
components:
  schemas:
    CloudEnum:
      title: Cloud Enum
      description: Which cloud the cluster is deployed in
      type: string
      default: MANUAL
      enum:
        - AWS
        - GCP
        - MANUAL
    CloudInfo:
      title: Cloud Info
      description: Cloud deployment information
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CloudEnum'
        region:
          type: string
          minLength: 1
          default: us-west2
      required:
        - code
        - region
    ClusterFaultTolerance:
      title: Cluster Fault Tolerance
      description: The level of fault tolerance for the cluster
      type: string
      enum:
        - NONE
        - NODE
        - ZONE
        - REGION
      default: ZONE
    ClusterNodeInfo:
      title: Cluster Node Info
      description: Node level information
      type: object
      properties:
        memory_mb:
          description: The total amount of RAM (MB) used by all nodes
          type: number
          format: double
          default: 0
        disk_size_gb:
          description: The total size of disk (GB)
          type: number
          format: double
          default: 0
        disk_size_used_gb:
          description: The total size of used disk space (GB)
          type: number
          format: double
          default: 0
        cpu_usage:
          description: The average CPU usage over all nodes
          type: number
          format: double
          default: 0
        num_cores:
          description: The number of CPU cores per node
          type: integer
          default: 0
      required:
        - num_cores
        - memory_mb
        - disk_size_gb
    ClusterInfo:
      title: Cluster Info
      description: Cluster level information
      type: object
      properties:
        num_nodes:
          description: How many nodes are in the cluster
          type: integer
          minimum: 1
          maximum: 24
          default: 3
        fault_tolerance:
          $ref: '#/components/schemas/ClusterFaultTolerance'
        node_info:
          $ref: '#/components/schemas/ClusterNodeInfo'
        is_production:
          description: Describes if the cluster is a production cluster
          type: boolean
          default: false
        version:
          description: cluster data version
          type: integer
          nullable: true
      required:
        - num_nodes
        - fault_tolerance
        - node_info
        - cluster_tier
        - is_production
    PlacementInfo:
      type: object
      properties:
        cloud_info:
          $ref: '#/components/schemas/CloudInfo'
        num_nodes:
          description: How many nodes are in the region
          type: integer
          minimum: 1
          maximum: 24
          default: 3
      required:
        - cloud_info
        - num_nodes
    ClusterRegionInfo:
      title: Cluster Region Info
      description: Cluster region info list
      type: object
      properties:
        placement_info:
          $ref: '#/components/schemas/PlacementInfo'
      required:
        - placement_info
    EncryptionInfo:
      title: Encryption Info
      description: Cluster encryption info
      type: object
      properties:
        encryption_at_rest:
          type: boolean
          default: false
        encryption_in_transit:
          type: boolean
          default: false
    ClusterSpec:
      title: Cluster Specification
      description: Cluster spec
      type: object
      properties:
        name:
          description: The name of the cluster
          type: string
          minLength: 3
          maxLength: 63
          pattern: ^(?:[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?)$
        cloud_info:
          $ref: '#/components/schemas/CloudInfo'
        cluster_info:
          $ref: '#/components/schemas/ClusterInfo'
        cluster_region_info:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ClusterRegionInfo'
          nullable: true
        encryption_info:
          $ref: '#/components/schemas/EncryptionInfo'
      required:
        - name
        - cloud_info
        - cluster_info
        - network_info
        - software_info
        - encryption_info
    EntityMetadata:
      title: Entity Metadata
      description: Common metadata for entities
      type: object
      properties:
        created_on:
          description: Timestamp when the entity was created (UTC)
          type: string
          nullable: true
        updated_on:
          description: Timestamp when the entity was last updated (UTC)
          type: string
          nullable: true
    ClusterDataInfo:
      type: object
      properties:
        id:
          description: The UUID of the cluster
          type: string
          format: uuid
        state:
          description: The current state of the cluster
          type: string
        software_version:
          description: The current version of YugabyteDB installed on the cluster
          type: string
        metadata:
          $ref: '#/components/schemas/EntityMetadata'
      required:
        - id
        - state
        - project_id
        - metadata
    ClusterData:
      title: Cluster Data
      description: Cluster data
      type: object
      required:
        - spec
        - info
      properties:
        spec:
          $ref: '#/components/schemas/ClusterSpec'
        info:
          $ref: '#/components/schemas/ClusterDataInfo'
    ApiError:
      title: API Error
      type: object
      properties:
        error:
          type: object
          properties:
            detail:
              description: Error message
              type: string
            status:
              description: Error code
              type: integer
    LiveQueryResponseYSQLQueryItem:
      title: Live Query Response YSQL Query Item
      description: Schema for Live Query Response YSQL Query Item
      type: object
      properties:
        id:
          type: string
          format: uuid
        node_name:
          type: string
        db_name:
          type: string
        session_status:
          type: string
        query:
          type: string
        elapsed_millis:
          type: integer
          format: int64
        query_start_time:
          type: string
        app_name:
          type: string
        client_host:
          type: string
        client_port:
          type: string
    LiveQueryResponseYSQLData:
      title: Live Query Response YSQL Data
      description: Schema for Live Query Response YSQL Data
      type: object
      properties:
        error_count:
          description: Count of Errors
          type: integer
        queries:
          type: array
          items:
            $ref: '#/components/schemas/LiveQueryResponseYSQLQueryItem'
    LiveQueryResponseYCQLQueryItem:
      title: Live Query Response YCQL Query Item
      description: Schema for Live Query Response YCQL Query Item
      type: object
      properties:
        id:
          type: string
          format: uuid
        node_name:
          type: string
        keyspace:
          type: string
        query:
          type: string
        type:
          type: string
        elapsed_millis:
          type: integer
          format: int64
        client_host:
          type: string
        client_port:
          type: string
    LiveQueryResponseYCQLData:
      title: Live Query Response YCQL Data
      description: Schema for Live Query Response YCQL Data
      type: object
      properties:
        error_count:
          description: Count of Errors
          type: integer
        queries:
          type: array
          items:
            $ref: '#/components/schemas/LiveQueryResponseYCQLQueryItem'
    LiveQueryResponseData:
      title: Live Query Response Data
      description: Live Query Response Data
      type: object
      properties:
        ysql:
          $ref: '#/components/schemas/LiveQueryResponseYSQLData'
        ycql:
          $ref: '#/components/schemas/LiveQueryResponseYCQLData'
    LiveQueryResponseSchema:
      title: Live Query Response Schema
      description: Live Query Response Schema
      type: object
      properties:
        data:
          $ref: '#/components/schemas/LiveQueryResponseData'
    SlowQueryResponseYSQLQueryItem:
      title: Slow Query Response YSQL Query Item
      description: Schema for Slow Query Response YSQL Query Item
      type: object
      properties:
        queryid:
          type: integer
          format: int64
        query:
          type: string
        rolname:
          type: string
        datname:
          type: string
        calls:
          type: integer
        local_blks_hit:
          type: integer
        local_blks_written:
          type: integer
        max_time:
          type: number
        mean_time:
          type: number
        min_time:
          type: number
        rows:
          type: integer
        stddev_time:
          type: number
        total_time:
          type: number
    SlowQueryResponseYSQLData:
      title: Slow Query Response YSQL Data
      description: Schema for Slow Query Response YSQL Data
      type: object
      properties:
        error_count:
          description: Count of Errors
          type: integer
        queries:
          type: array
          items:
            $ref: '#/components/schemas/SlowQueryResponseYSQLQueryItem'
    SlowQueryResponseData:
      title: Slow Query Response Data
      description: Slow Query Response Data
      type: object
      properties:
        ysql:
          $ref: '#/components/schemas/SlowQueryResponseYSQLData'
    SlowQueryResponseSchema:
      title: Slow Query Response Schema
      description: Slow Query Response Schema
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SlowQueryResponseData'
    NodeData:
      type: object
      description: Node data
      properties:
        name:
          type: string
          nullable: false
        is_node_up:
          type: boolean
        is_master:
          type: boolean
        is_tserver:
          type: boolean
        metrics:
          type: object
          properties:
            memory_used_bytes:
              type: integer
              format: int64
              default: 0
            total_sst_file_size_bytes:
              type: integer
              format: int64
              default: 0
              nullable: true
            uncompressed_sst_file_size_bytes:
              type: integer
              format: int64
              default: 0
              nullable: true
            read_ops_per_sec:
              type: number
              format: double
              default: 0
            write_ops_per_sec:
              type: number
              format: double
              default: 0
          required:
            - memory_used_bytes
            - total_sst_file_size_bytes
            - uncompressed_sst_file_size_bytes
            - read_ops_per_sec
            - write_ops_per_sec
        cloud_info:
          type: object
          properties:
            cloud:
              type: string
            region:
              type: string
            zone:
              type: string
          required:
            - region
            - zone
        software_version:
          type: string
      required:
        - name
        - is_node_up
        - is_master
        - is_tserver
        - cloud_info
        - metrics
        - software_version
    MetricData:
      title: Metric Data
      description: Metric data
      type: object
      properties:
        name:
          description: The name of the metric
          type: string
        values:
          description: Array of (timestamp, value) tuples
          type: array
          items:
            type: array
            items:
              type: number
              format: double
            minItems: 2
            maxItems: 2
      required:
        - name
        - values
    YbApiEnum:
      title: Yb Api Enum
      description: Type of DB API (YSQL/YCQL)
      type: string
      enum:
        - YSQL
        - YCQL
    ClusterTable:
      title: Cluster Table Object
      description: Model representing a DB table
      type: object
      properties:
        name:
          type: string
          minLength: 1
          nullable: false
        keyspace:
          type: string
          minLength: 1
          nullable: false
        type:
          $ref: '#/components/schemas/YbApiEnum'
        size_bytes:
          type: integer
          format: int64
          minimum: 0
      required:
        - name
        - keyspace
        - type
        - size_bytes
    ClusterTableData:
      title: Cluster Table Data
      description: List of cluster tables
      type: array
      uniqueItems: true
      nullable: false
      items:
        $ref: '#/components/schemas/ClusterTable'
    HealthCheckInfo:
      title: Health Check Info
      type: object
      properties:
        dead_nodes:
          type: array
          description: UUIDs of dead nodes
          items:
            type: string
            format: uuid
        most_recent_uptime:
          type: integer
          format: int64
          minimum: 0
        under_replicated_tablets:
          type: array
          description: UUIDs of under-replicated tablets
          items:
            type: string
            format: uuid
        leaderless_tablets:
          type: array
          description: UUIDs of leaderless tablets
          items:
            type: string
            format: uuid
      required:
        - dead_nodes
        - most_recent_uptime
        - under_replicated_tablets
        - leaderless_tablets
    ClusterTablet:
      title: Cluster Tablet Object
      description: Model representing a tablet
      type: object
      properties:
        namespace:
          type: string
        table_name:
          type: string
        table_uuid:
          type: string
          format: uuid
        tablet_id:
          type: string
          format: uuid
        has_leader:
          type: boolean
      required:
        - namespace
        - table_name
        - table_uuid
        - table_id
        - has_leader
    ClusterTabletData:
      title: Cluster Tablet Data
      description: List of cluster tablets
      type: array
      additionalProperties:
        $ref: '#/components/schemas/ClusterTablet'
  requestBodies:
    ClusterSpec:
      description: DB Cluster to be updated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClusterSpec'
  responses:
    ClusterResponse:
      description: Cluster response
      content:
        application/json:
          schema:
            title: Cluster Response
            type: object
            properties:
              data:
                $ref: '#/components/schemas/ClusterData'
    ApiError:
      description: API Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    LiveQueryResponse:
      description: Live Queries of a Cluster
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LiveQueryResponseSchema'
    SlowQueryResponse:
      description: Slow Queries of a Cluster
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SlowQueryResponseSchema'
    ClusterNodeListResponse:
      description: Cluster nodes response
      content:
        application/json:
          schema:
            title: Cluster Nodes Response
            type: object
            properties:
              data:
                type: array
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/NodeData'
            required:
              - data
    MetricResponse:
      description: Metric response
      content:
        application/json:
          schema:
            title: Metric Response
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/MetricData'
              start_timestamp:
                description: Start of range of results
                type: integer
                format: int64
              end_timestamp:
                description: End of range of results
                type: integer
                format: int64
            required:
              - data
              - start_timestamp
              - end_timestamp
    ClusterTableListResponse:
      description: List of cluster tables
      content:
        application/json:
          schema:
            title: Cluster table list response
            type: object
            properties:
              data:
                $ref: '#/components/schemas/ClusterTableData'
            required:
              - data
    HealthCheckResponse:
      description: Successful health check response
      content:
        application/json:
          schema:
            title: Health Check Response
            type: object
            properties:
              data:
                $ref: '#/components/schemas/HealthCheckInfo'
    ClusterTabletListResponse:
      description: List of cluster tablets
      content:
        application/json:
          schema:
            title: Cluster tablet list response
            type: object
            properties:
              data:
                $ref: '#/components/schemas/ClusterTabletData'
            required:
              - data
  securitySchemes:
    BearerAuthToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuthToken: []