tidb Imports API

openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Imports 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: Imports
  description: Operations for creating and managing data import tasks into TiDB Cloud clusters.
paths:
  /clusters/{clusterId}/imports:
    get:
      operationId: listImports
      summary: List import tasks
      description: Returns a paginated list of data import tasks for a specific TiDB Cloud Dedicated cluster. Each import task includes status, source configuration, progress information, and timestamps.
      tags:
      - Imports
      parameters:
      - $ref: '#/components/parameters/clusterId'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: A paginated list of import tasks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListImportsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createImport
      summary: Create an import task
      description: Creates a new data import task for a specific TiDB Cloud Dedicated cluster. Supports importing data from AWS S3, Google Cloud Storage, and local file uploads in CSV, SQL, Parquet, and Aurora Snapshot formats. Specify the source type, file format, target database, and any necessary access credentials.
      tags:
      - Imports
      parameters:
      - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImportRequest'
      responses:
        '200':
          description: Import task created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /clusters/{clusterId}/imports/{importId}:
    get:
      operationId: getImport
      summary: Get an import task
      description: Returns the current status and configuration details of a specific data import task. Includes progress percentage, estimated completion time, error messages if any, and source file information.
      tags:
      - Imports
      parameters:
      - $ref: '#/components/parameters/clusterId'
      - $ref: '#/components/parameters/importId'
      responses:
        '200':
          description: Import task details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /clusters/{clusterId}/imports/{importId}:cancel:
    post:
      operationId: cancelImport
      summary: Cancel an import task
      description: Cancels an in-progress data import task for a specific cluster. Only import tasks in a RUNNING or PENDING state can be cancelled. Cancelled tasks cannot be resumed; a new import task must be created.
      tags:
      - Imports
      parameters:
      - $ref: '#/components/parameters/clusterId'
      - $ref: '#/components/parameters/importId'
      responses:
        '200':
          description: Import task cancelled successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    clusterId:
      name: clusterId
      in: path
      description: The unique identifier of the TiDB Cloud Dedicated cluster.
      required: true
      schema:
        type: string
    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
    importId:
      name: importId
      in: path
      description: The unique identifier of the import task.
      required: true
      schema:
        type: string
  schemas:
    S3Source:
      type: object
      description: S3 source configuration for a data import task.
      properties:
        bucketUri:
          type: string
          description: The S3 bucket URI containing the import files (e.g., s3://bucket/path/).
        roleArn:
          type: string
          description: The AWS IAM Role ARN granting TiDB Cloud access to the S3 bucket.
    ListImportsResponse:
      type: object
      description: Paginated list of import tasks for a cluster.
      properties:
        imports:
          type: array
          description: The list of import task objects.
          items:
            $ref: '#/components/schemas/Import'
        nextPageToken:
          type: string
          description: Token to retrieve the next page of results.
    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.
        msgPrefix:
          type: string
          description: A human-readable error message describing the failure.
    CreateImportRequest:
      type: object
      description: Request body for creating a new data import task.
      required:
      - sourceType
      - fileFormat
      properties:
        sourceType:
          type: string
          description: The source of the import data.
          enum:
          - S3
          - GCS
          - LOCAL
        fileFormat:
          type: string
          description: The format of the files to import.
          enum:
          - CSV
          - SQL
          - PARQUET
          - AURORA_SNAPSHOT
        targetDatabase:
          type: string
          description: The target database in the cluster to import data into.
        s3Source:
          $ref: '#/components/schemas/S3Source'
    Import:
      type: object
      description: A data import task for a TiDB Cloud cluster.
      properties:
        importId:
          type: string
          description: The unique identifier of the import task.
        clusterId:
          type: string
          description: The ID of the cluster receiving the imported data.
        state:
          type: string
          description: The current state of the import task.
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          - CANCELLED
        sourceType:
          type: string
          description: The source type for the import (S3, GCS, LOCAL).
        fileFormat:
          type: string
          description: The file format of the import data (CSV, SQL, PARQUET, AURORA_SNAPSHOT).
        progress:
          type: number
          description: The completion percentage of the import task, from 0 to 100.
        createTime:
          type: string
          format: date-time
          description: The timestamp when the import task was created.
        errorMessage:
          type: string
          description: Error message if the import task failed.
  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/