openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Endpoints 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: Endpoints
  description: Operations for creating, listing, updating, testing, and deleting custom SQL-backed API endpoints.
paths:
  /dataApps/{dataAppId}/endpoints:
    get:
      operationId: listEndpoints
      summary: List endpoints
      description: Returns a paginated list of all custom SQL-backed endpoints defined within a Data App. Each endpoint entry includes its HTTP method, path, SQL template, parameters, and configuration settings such as caching and pagination.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/dataAppId'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: A paginated list of endpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEndpointsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createEndpoint
      summary: Create an endpoint
      description: Defines a new custom SQL-backed API endpoint within a Data App. Specify the HTTP method, URL path, target cluster, SQL template, and any path or query parameters. The endpoint will become available after the Data App is deployed.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/dataAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEndpointRequest'
      responses:
        '200':
          description: Endpoint created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Endpoint:
      type: object
      description: A custom SQL-backed API endpoint within a Data App.
      properties:
        name:
          type: string
          description: The resource name of the endpoint.
        displayName:
          type: string
          description: The human-readable display name for the endpoint.
        description:
          type: string
          description: A description of what the endpoint does.
        path:
          type: string
          description: The URL path for the endpoint (e.g., /users/{id}).
        method:
          type: string
          description: The HTTP method for the endpoint.
          enum:
          - GET
          - POST
          - PUT
          - DELETE
        clusterId:
          type: string
          description: The ID of the cluster this endpoint runs queries against.
        sqlTemplate:
          type: string
          description: The SQL template executed when the endpoint is called. Supports parameter substitution.
        tag:
          type: string
          description: A label for grouping related endpoints.
        settings:
          $ref: '#/components/schemas/EndpointSettings'
        params:
          type: array
          description: The list of parameters accepted by this endpoint.
          items:
            $ref: '#/components/schemas/EndpointParameter'
    EndpointSettings:
      type: object
      description: Configuration settings for an endpoint's behavior.
      properties:
        timeout:
          type: integer
          description: The maximum execution time in milliseconds before the endpoint returns a timeout error.
        rowLimit:
          type: integer
          description: The maximum number of rows returned by a single endpoint call.
        cacheEnabled:
          type: boolean
          description: Whether response caching is enabled for this endpoint.
        cacheTtl:
          type: integer
          description: The time-to-live for cached responses in seconds.
        paginationEnabled:
          type: boolean
          description: Whether cursor-based pagination is enabled for this endpoint.
    ListEndpointsResponse:
      type: object
      description: Paginated list of endpoints in a Data App.
      properties:
        endpoints:
          type: array
          description: The list of endpoint objects on this page.
          items:
            $ref: '#/components/schemas/Endpoint'
        nextPageToken:
          type: string
          description: Token to retrieve the next page of results.
    CreateEndpointRequest:
      type: object
      description: Request body for creating a new endpoint within a Data App.
      required:
      - displayName
      - path
      - method
      - clusterId
      - sqlTemplate
      properties:
        displayName:
          type: string
          description: The display name for the new endpoint.
        description:
          type: string
          description: An optional description of the endpoint.
        path:
          type: string
          description: The URL path for the endpoint.
        method:
          type: string
          description: The HTTP method for the endpoint.
          enum:
          - GET
          - POST
          - PUT
          - DELETE
        clusterId:
          type: string
          description: The ID of the cluster this endpoint queries.
        sqlTemplate:
          type: string
          description: The SQL template to execute when the endpoint is called.
        tag:
          type: string
          description: An optional label for grouping the endpoint.
        settings:
          $ref: '#/components/schemas/EndpointSettings'
        params:
          type: array
          description: Parameter definitions for this endpoint.
          items:
            $ref: '#/components/schemas/EndpointParameter'
    EndpointParameter:
      type: object
      description: A parameter definition for a Data App endpoint.
      properties:
        name:
          type: string
          description: The parameter name as referenced in the SQL template.
        type:
          type: string
          description: The data type of the parameter.
          enum:
          - STRING
          - INTEGER
          - NUMBER
          - BOOLEAN
          - ARRAY
        required:
          type: boolean
          description: Whether this parameter must be provided when calling the endpoint.
        defaultValue:
          type: string
          description: The default value used when the parameter is not provided.
    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.
  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'
  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/