{
  "swagger": "2.0",
  "info": {
    "title": "TiDB Cloud Starter and Essential API",
    "description": "TiDB Cloud Starter and Essential API",
    "version": "v1beta1"
  },
  "tags": [
    {
      "name": "ImportService"
    }
  ],
  "host": "serverless.tidbapi.com",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/v1beta1/clusters/{clusterId}/imports:startUpload": {
      "post": {
        "summary": "Generate Upload url for importing data",
        "operationId": "ImportService_StartUpload",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/StartUploadResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to import into",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "fileName",
            "description": "The name of the file to import",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "partNumber",
            "description": "The number of parts to split the file into",
            "in": "query",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "targetDatabase",
            "description": "The name of the database to import into",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "targetTable",
            "description": "The name of the table to import into",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "ImportService"
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/imports:completeUpload": {
      "post": {
        "summary": "Complete the upload",
        "operationId": "ImportService_CompleteUpload",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "type": "object",
              "properties": {}
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to import into",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "parts",
            "description": "The parts have been uploaded, only needed when upload is multipart.",
            "in": "body",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "object",
                "$ref": "#/definitions/CompletePart"
              }
            }
          },
          {
            "name": "uploadId",
            "description": "The ID of the upload",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "ImportService"
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/imports:cancelUpload": {
      "post": {
        "summary": "Cancel the upload",
        "operationId": "ImportService_CancelUpload",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "type": "object",
              "properties": {}
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to import into",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "uploadId",
            "description": "The ID of the upload",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "ImportService"
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/imports": {
      "get": {
        "summary": "List import tasks for a cluster",
        "operationId": "ImportService_ListImports",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ListImportsResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster to list import tasks for.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "pageToken",
            "description": "The pagination token received from a previous [List import tasks](#tag/Import/operation/ImportService_ListImports) request. Use this token to retrieve the next page of results.\n\n**Note**: When paginating, all other parameters must match the original request.",
            "in": "query",
            "required": false,
            "type": "string"
          },
          {
            "name": "pageSize",
            "description": "The maximum number of import tasks to return. If not specified, at most 10 import tasks will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.",
            "in": "query",
            "required": false,
            "type": "integer",
            "format": "int32",
            "default": 10
          },
          {
            "name": "orderBy",
            "description": "Specifies the sorting order of results. Use a comma-separated list of field names, optionally appending `desc` for descending order. For example, `createTime desc`. By default, fields are sorted in ascending order.\n\nSupported field: `createTime`.",
            "in": "query",
            "required": false,
            "type": "string"
          }
        ],
        "tags": [
          "Import"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/imports' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
          }
        ]
      },
      "post": {
        "summary": "Create an import task",
        "operationId": "ImportService_CreateImport",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Import"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the target cluster where data will be imported.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ImportService.CreateImportBody"
            }
          }
        ],
        "tags": [
          "Import"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/imports' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n  \"importOptions\": {\n    \"fileType\": \"SQL\"\n  },\n  \"source\": {\n    \"type\": \"S3\",\n    \"s3\": {\n      \"uri\": \"s3://tidbcloud-sample-data/data-ingestion/\",\n      \"authType\": \"ROLE_ARN\",\n      \"roleArn\": \"arn:aws:iam::801626783489:role/import-sample-access\"\n    }\n  }\n}'"
          }
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/imports/{id}": {
      "get": {
        "summary": "Get details of an import task",
        "operationId": "ImportService_GetImport",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Import"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "id",
            "description": "The ID of the import task.",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "Import"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/imports/{import_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
          }
        ]
      }
    },
    "/v1beta1/clusters/{clusterId}/imports/{id}:cancel": {
      "post": {
        "summary": "Cancel an import task",
        "operationId": "ImportService_CancelImport",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "type": "object",
              "properties": {}
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/Status"
            }
          }
        },
        "parameters": [
          {
            "name": "clusterId",
            "description": "The ID of the cluster.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "id",
            "description": "The ID of the import task.",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "Import"
        ],
        "x-codeSamples": [
          {
            "label": "curl",
            "lang": "cURL",
            "source": "curl --location --request POST 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/imports/{import_id}:cancel' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
          }
        ]
      }
    }
  },
  "definitions": {
    "Any": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "AzureBlobSource": {
      "type": "object",
      "properties": {
        "authType": {
          "description": "The authentication method for accessing the Azure Blob Storage source.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportAzureBlobAuthType.Enum"
            }
          ]
        },
        "sasToken": {
          "type": "string",
          "description": "The Shared Access Signature (SAS) token for accessing the Azure Blob Storage source."
        },
        "uri": {
          "type": "string",
          "description": "The Azure Blob Storage URI of the import source, in the format of `azure://<account>.blob.core.windows.net/<container>/<path>` or `https://<account>.blob.core.windows.net/<container>/<path>`."
        }
      },
      "required": [
        "authType",
        "uri"
      ]
    },
    "CSVFormat": {
      "type": "object",
      "properties": {
        "separator": {
          "type": "string",
          "description": "The character used to separate values in the CSV file. Default value is `,`."
        },
        "delimiter": {
          "type": "string",
          "x-nullable": true,
          "description": "The character used to enclose string values in the CSV file. Default value is `\"`."
        },
        "header": {
          "type": "boolean",
          "x-nullable": true,
          "description": "Indicates whether to include a header row in the CSV file. Default value is `true`."
        },
        "notNull": {
          "type": "boolean",
          "x-nullable": true,
          "description": "Indicates whether the columns in the CSV file can contain NULL values. Default value is `false`."
        },
        "null": {
          "type": "string",
          "x-nullable": true,
          "description": "The string representation of NULL values in the CSV file. Default value is `\\N`."
        },
        "backslashEscape": {
          "type": "boolean",
          "x-nullable": true,
          "description": "Indicates whether to escape backslashes in the CSV file. Default value is `true`."
        },
        "trimLastSeparator": {
          "type": "boolean",
          "x-nullable": true,
          "description": "Indicates whether to remove the last separator in the CSV file. Default value is `false`."
        }
      }
    },
    "CompletePart": {
      "type": "object",
      "properties": {
        "partNumber": {
          "type": "integer",
          "format": "int32",
          "title": "The part number"
        },
        "etag": {
          "type": "string",
          "title": "The ETag of the part"
        }
      },
      "required": [
        "partNumber",
        "etag"
      ]
    },
    "CreationDetails": {
      "type": "object",
      "properties": {
        "importOptions": {
          "description": "The configuration options for the import task.",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/ImportOptions"
            }
          ]
        },
        "source": {
          "description": "The data source for the import task.",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/ImportSource"
            }
          ]
        }
      }
    },
    "GCSSource": {
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "description": "The Google Cloud Storage URI of the import source."
        },
        "authType": {
          "description": "The authentication method for accessing the Google Cloud Storage source.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportGcsAuthType.Enum"
            }
          ]
        },
        "serviceAccountKey": {
          "type": "string",
          "description": "The service account key for accessing the Google Cloud Storage source."
        }
      },
      "required": [
        "uri",
        "authType"
      ]
    },
    "Import": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "**Deprecated.** Use `importId` instead. The ID of the import task.",
          "readOnly": true
        },
        "name": {
          "type": "string",
          "description": "The name of the import task.",
          "readOnly": true
        },
        "clusterId": {
          "type": "string",
          "description": "The ID of the target cluster for the import.",
          "readOnly": true
        },
        "totalSize": {
          "type": "string",
          "format": "uint64",
          "description": "The total size of the data to be imported, in bytes.",
          "readOnly": true
        },
        "createTime": {
          "type": "string",
          "format": "date-time",
          "description": "The timestamp when the import task was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.",
          "readOnly": true
        },
        "completeTime": {
          "type": "string",
          "format": "date-time",
          "x-nullable": true,
          "description": "The timestamp when the import task was completed, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.",
          "readOnly": true
        },
        "state": {
          "description": "The state of the import task.",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/ImportState.Enum"
            }
          ]
        },
        "completePercent": {
          "type": "integer",
          "format": "int64",
          "description": "The percentage of import progress, excluding post-processing.",
          "readOnly": true
        },
        "message": {
          "type": "string",
          "description": "An error message if the import task failed. Otherwise, empty.",
          "readOnly": true
        },
        "createdBy": {
          "type": "string",
          "description": "The email address of the user who create the import task.",
          "readOnly": true
        },
        "creationDetails": {
          "description": "The additional details about how the import task is created.",
          "readOnly": true,
          "allOf": [
            {
              "$ref": "#/definitions/CreationDetails"
            }
          ]
        },
        "importId": {
          "type": "string",
          "description": "The ID of the import task.",
          "readOnly": true
        }
      }
    },
    "ImportAzureBlobAuthType.Enum": {
      "type": "string",
      "enum": [
        "SAS_TOKEN"
      ],
      "description": " - SAS_TOKEN: The access method is sas token."
    },
    "ImportFileType.Enum": {
      "type": "string",
      "enum": [
        "CSV",
        "SQL",
        "AURORA_SNAPSHOT",
        "PARQUET"
      ],
      "description": " - CSV: CSV type.\n - SQL: SQL type.\n - AURORA_SNAPSHOT: Aurora snapshot type.\n - PARQUET: Parquet type."
    },
    "ImportGcsAuthType.Enum": {
      "type": "string",
      "enum": [
        "SERVICE_ACCOUNT_KEY"
      ],
      "description": " - SERVICE_ACCOUNT_KEY: The access method is service account key."
    },
    "ImportOSSAuthType.Enum": {
      "type": "string",
      "enum": [
        "ACCESS_KEY"
      ],
      "description": " - ACCESS_KEY: The access method is access key."
    },
    "ImportOptions": {
      "type": "object",
      "properties": {
        "fileType": {
          "description": "The format of the file to import.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportFileType.Enum"
            }
          ]
        },
        "csvFormat": {
          "description": "The format specification for CSV files.",
          "allOf": [
            {
              "$ref": "#/definitions/CSVFormat"
            }
          ]
        }
      },
      "required": [
        "fileType"
      ]
    },
    "ImportS3AuthType.Enum": {
      "type": "string",
      "enum": [
        "ROLE_ARN",
        "ACCESS_KEY"
      ],
      "description": " - ROLE_ARN: The access method is role arn.\n - ACCESS_KEY: The access method is access key."
    },
    "ImportS3CompatibleAuthType.Enum": {
      "type": "string",
      "enum": [
        "ACCESS_KEY"
      ],
      "description": " - ACCESS_KEY: The access method is access key."
    },
    "ImportService.CreateImportBody": {
      "type": "object",
      "properties": {
        "importOptions": {
          "description": "The configuration options for the import task.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportOptions"
            }
          ]
        },
        "source": {
          "description": "The data source for the import task.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportSource"
            }
          ]
        }
      },
      "required": [
        "importOptions",
        "source"
      ]
    },
    "ImportSource": {
      "type": "object",
      "properties": {
        "type": {
          "description": "The source from which data is imported.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportSourceType.Enum"
            }
          ]
        },
        "local": {
          "$ref": "#/definitions/LocalSource"
        },
        "s3": {
          "description": "The configuration details for importing from Amazon S3.",
          "allOf": [
            {
              "$ref": "#/definitions/S3Source"
            }
          ]
        },
        "gcs": {
          "description": "The configuration details for importing from Google Cloud Storage.",
          "allOf": [
            {
              "$ref": "#/definitions/GCSSource"
            }
          ]
        },
        "azureBlob": {
          "description": "The configuration details for importing from Azure Blob Storage.",
          "allOf": [
            {
              "$ref": "#/definitions/AzureBlobSource"
            }
          ]
        },
        "s3Compatible": {
          "description": "The configuration details for importing from S3-compatible storage.",
          "allOf": [
            {
              "$ref": "#/definitions/S3CompatibleSource"
            }
          ]
        },
        "oss": {
          "description": "The configuration details for importing from Alibaba Cloud OSS.",
          "allOf": [
            {
              "$ref": "#/definitions/OSSSource"
            }
          ]
        }
      },
      "required": [
        "type"
      ]
    },
    "ImportSourceType.Enum": {
      "type": "string",
      "enum": [
        "LOCAL",
        "S3",
        "GCS",
        "AZURE_BLOB",
        "S3_COMPATIBLE",
        "OSS"
      ],
      "description": " - LOCAL: Local source.\n - S3: S3 source.\n - GCS: gcs source.\n - AZURE_BLOB: azure blob source.\n - S3_COMPATIBLE: S3 compatible source.\n - OSS: OSS source."
    },
    "ImportState.Enum": {
      "type": "string",
      "enum": [
        "PREPARING",
        "IMPORTING",
        "COMPLETED",
        "FAILED",
        "CANCELING",
        "CANCELED"
      ],
      "description": " - PREPARING: The import is preparing.\n - IMPORTING: The import is importing.\n - COMPLETED: The import is completed.\n - FAILED: The import is failed.\n - CANCELING: The import is canceling.\n - CANCELED: The import is canceled."
    },
    "ListImportsResponse": {
      "type": "object",
      "properties": {
        "imports": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/Import"
          },
          "description": "A list of import tasks that match the query.",
          "readOnly": true
        },
        "totalSize": {
          "type": "integer",
          "format": "int64",
          "description": "The total number of imports that match the query.",
          "readOnly": true
        },
        "nextPageToken": {
          "type": "string",
          "description": "The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages.",
          "readOnly": true
        }
      }
    },
    "LocalSource": {
      "type": "object",
      "properties": {
        "uploadId": {
          "type": "string",
          "description": "The upload id of import source file."
        },
        "targetDatabase": {
          "type": "string",
          "description": "The target database of import."
        },
        "targetTable": {
          "type": "string",
          "description": "The target table of import."
        },
        "fileName": {
          "type": "string",
          "description": "The file name of import source file.",
          "readOnly": true
        }
      },
      "required": [
        "uploadId",
        "targetDatabase",
        "targetTable"
      ]
    },
    "OSSSource": {
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "description": "The Alibaba Cloud OSS URI of the import source."
        },
        "authType": {
          "description": "The authentication method for accessing Alibaba Cloud OSS.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportOSSAuthType.Enum"
            }
          ]
        },
        "accessKey": {
          "description": "The access key credentials used for accessing the Alibaba Cloud OSS source.",
          "allOf": [
            {
              "$ref": "#/definitions/OSSSource.AccessKey"
            }
          ]
        }
      },
      "required": [
        "uri",
        "authType"
      ]
    },
    "OSSSource.AccessKey": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The AccessKey ID for accessing Alibaba Cloud OSS."
        },
        "secret": {
          "type": "string",
          "description": "The AccessKey secret for accessing Alibaba Cloud OSS."
        }
      },
      "required": [
        "id",
        "secret"
      ]
    },
    "S3CompatibleSource": {
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "description": "The S3-compatible storage URI of the import source."
        },
        "authType": {
          "description": "The authentication method for accessing the S3-compatible storage.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportS3CompatibleAuthType.Enum"
            }
          ]
        },
        "accessKey": {
          "description": "The access key credentials used for accessing the S3-compatible storage.",
          "allOf": [
            {
              "$ref": "#/definitions/S3CompatibleSource.AccessKey"
            }
          ]
        },
        "endpoint": {
          "type": "string",
          "x-nullable": true,
          "description": "The custom HTTPS endpoint for S3-compatible storage, which is used to connect to non-AWS storage providers, such as Cloudflare.\nMust be a valid HTTPS URL, such as `https://custom-s3.example.com`."
        }
      },
      "required": [
        "uri",
        "authType"
      ]
    },
    "S3CompatibleSource.AccessKey": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The access key ID for accessing the S3-compatible storage."
        },
        "secret": {
          "type": "string",
          "description": "The secret access key for accessing the S3-compatible storage."
        }
      },
      "required": [
        "id",
        "secret"
      ]
    },
    "S3Source": {
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "description": "The S3 URI of the import source."
        },
        "authType": {
          "description": "The authentication method for accessing the S3 bucket.",
          "allOf": [
            {
              "$ref": "#/definitions/ImportS3AuthType.Enum"
            }
          ]
        },
        "roleArn": {
          "type": "string",
          "description": "The AWS IAM role ARN used for access."
        },
        "accessKey": {
          "description": "The AWS access key credentials used for access.",
          "allOf": [
            {
              "$ref": "#/definitions/S3Source.AccessKey"
            }
          ]
        }
      },
      "required": [
        "uri",
        "authType"
      ]
    },
    "S3Source.AccessKey": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The access key ID for accessing the S3 source."
        },
        "secret": {
          "type": "string",
          "description": "The secret access key for accessing the S3 source."
        }
      },
      "required": [
        "id",
        "secret"
      ]
    },
    "StartUploadResponse": {
      "type": "object",
      "properties": {
        "uploadUrl": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "The URL to upload the file to",
          "readOnly": true
        },
        "uploadId": {
          "type": "string",
          "title": "The ID of the upload",
          "readOnly": true
        }
      }
    },
    "Status": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/Any"
          }
        }
      }
    }
  }
}