openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Deployments API
  description: The TiDB Cloud API is a REST interface that provides programmatic access to manage administrative objects within TiDB Cloud. It supports managing projects, clusters, backups, restores, data imports, billing, and private endpoint connections across both TiDB Cloud Serverless and TiDB Cloud Dedicated tiers. The API uses HTTP Digest Authentication with public and private API keys and returns JSON-formatted responses. Available as both v1beta and the newer v1beta1 versions, it enables automation of database infrastructure lifecycle management at scale.
  version: v1beta1
  contact:
    name: TiDB Cloud Support
    url: https://docs.pingcap.com/tidbcloud/api-overview/
  termsOfService: https://www.pingcap.com/legal/privacy-policy/
servers:
- url: https://dedicated.tidbapi.com/v1beta1
  description: Dedicated Cluster API Server
- url: https://iam.tidbapi.com/v1beta1
  description: IAM API Server
- url: https://billing.tidbapi.com/v1beta1
  description: Billing API Server
security:
- digestAuth: []
tags:
- name: Deployments
  description: Operations for deploying and managing versions of a Data App.
paths:
  /dataApps/{dataAppId}/deployments:
    get:
      operationId: listDeployments
      summary: List deployments
      description: Returns a paginated list of deployment records for a Data App. Each deployment captures a versioned snapshot of the Data App's endpoints at the time of deployment, enabling rollback and audit of configuration changes.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/dataAppId'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: A paginated list of deployments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDeploymentsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createDeployment
      summary: Create a deployment
      description: Deploys the current configuration of a Data App, making all defined endpoints live. Creates an immutable deployment record that can be referenced for rollback. Endpoints are not publicly accessible until a successful deployment is created.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/dataAppId'
      responses:
        '200':
          description: Data App deployed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    pageSize:
      name: pageSize
      in: query
      description: Maximum number of results to return per page. Default is 100, maximum is 100.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
    pageToken:
      name: pageToken
      in: query
      description: Pagination token returned from a previous list request to retrieve the next page.
      required: false
      schema:
        type: string
    dataAppId:
      name: dataAppId
      in: path
      description: The unique identifier of the Data App.
      required: true
      schema:
        type: string
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed. Check your API key credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response returned when an API request fails.
      properties:
        code:
          type: integer
          description: The HTTP status code of the error.
        status:
          type: string
          description: The error status string.
        error:
          type: string
          description: A machine-readable error code identifier.
        message:
          type: string
          description: A human-readable error message describing the failure.
    ListDeploymentsResponse:
      type: object
      description: Paginated list of deployments for a Data App.
      properties:
        deployments:
          type: array
          description: The list of deployment objects on this page.
          items:
            $ref: '#/components/schemas/Deployment'
        nextPageToken:
          type: string
          description: Token to retrieve the next page of results.
    Deployment:
      type: object
      description: A versioned deployment of a Data App.
      properties:
        deploymentId:
          type: string
          description: The unique identifier of this deployment.
        dataAppId:
          type: string
          description: The ID of the Data App that was deployed.
        status:
          type: string
          description: The status of the deployment.
          enum:
          - PENDING
          - RUNNING
          - SUCCEEDED
          - FAILED
        createTime:
          type: string
          format: date-time
          description: The timestamp when the deployment was created.
  securitySchemes:
    digestAuth:
      type: http
      scheme: digest
      description: HTTP Digest Authentication using a TiDB Cloud API public key as the username and private key as the password. Keys are generated in the TiDB Cloud console under Organization Settings > API Keys.
externalDocs:
  description: TiDB Cloud API Overview
  url: https://docs.pingcap.com/tidbcloud/api-overview/