openapi: 3.2.0
info:
description: "*TiDB Cloud API is in beta.*\n\n# Overview\n\nThe TiDB Cloud API is a [REST interface](https://en.wikipedia.org/wiki/Representational_state_transfer) that provides you with programmatic access to manage administrative objects within TiDB Cloud.\n\nThe API has the following features:\n\n- **JSON entities.** All entities are expressed in JSON.\n- **HTTPS-only.** You can only access the API via HTTPS, ensuring all the data sent over the network is encrypted with TLS.\n- **Key-based access and digest authentication.** Before you access TiDB Cloud API, you must generate an API key. All requests are authenticated through [HTTP Digest Authentication](https://en.wikipedia.org/wiki/Digest_access_authentication), ensuring the API key is never sent over the network.\n\n# Get Started\n\nThis guide helps you make your first API call to TiDB Cloud API. You'll learn how to authenticate a request, build a request, and interpret the response.\n\n## Prerequisites\n\nTo complete this guide, you need to perform the following tasks:\n\n- Create a [TiDB Cloud account](https://tidbcloud.com/free-trial)\n- Install [curl](https://curl.se/)\n\n## Step 1. Create an API key\n\nTo create an API key, log in to your TiDB Cloud console. Navigate to the [**API Keys**](https://tidbcloud.com/org-settings/api-keys) page of your organization, and create an API key.\n\nAn API key contains a public key and a private key. Copy and save them in a secure location. You will need to use the API key later in this guide.\n\nFor more details about creating API keys, refer to [API Key Management](#section/Authentication/API-Key-Management).\n\n## Step 2. Make your first API call\n\n### Build an API call\n\nTiDB Cloud API call consists of the following components:\n\n- **A host.** The host for TiDB Cloud API is <https://billing.tidbapi.com>.\n- **An API Key**. The public key and the private key are required for authentication.\n- **A request.** When submitting data to a resource via `POST`, `PATCH`, or `PUT`, you must submit your payload in JSON.\n\nIn this guide, you call the [List all accessible projects](#tag/Project/operation/ListProjects) endpoint. For the detailed description of the endpoint, see the [API reference](#tag/Project/operation/ListProjects).\n\n### Call an API endpoint\n\nTo get all projects in your organization, run the following command in your terminal. Remember to change `YOUR_PUBLIC_KEY` to your public key and `YOUR_PRIVATE_KEY` to your private key.\n\n```shell\ncurl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url https://billing.tidbapi.com/v1beta1/bills/2023-09\n```\n\n## Step 3. Check the response\n\nAfter making the API call, if the status code in response is `200` and you see details about all the projects in your organization, your request is successful. Here is an example of a successful response.\n\n```log\n{\n \"overview\": {\n \"billedMonth\": \"2023-09\",\n \"credits\": \"0.00\",\n \"discounts\": \"0.00\",\n \"runningTotal\": \"0.00\",\n \"totalCost\": \"0.00\"\n },\n \"summaryByProject\": {\n \"otherCharges\": [\n {\n \"credits\": \"0.00\",\n \"discounts\": \"0.00\",\n \"otherName\": \"Support Plan\",\n \"runningTotal\": \"0.00\",\n \"totalCost\": \"0.00\"\n }\n ],\n \"projects\": [\n {\n \"credits\": \"0.00\",\n \"discounts\": \"0.00\",\n \"projectName\": \"prod-project\",\n \"runningTotal\": \"0.00\",\n \"totalCost\": \"0.00\"\n }\n ]\n },\n \"summaryByService\": [\n {\n \"credits\": \"0.00\",\n \"discounts\": \"0.00\",\n \"runningTotal\": \"0.00\",\n \"serviceCosts\": [\n {}\n ],\n \"serviceName\": \"TiDB Dedicated\",\n \"totalCost\": \"0.00\"\n }\n ]\n}\n``` \n# Authentication\n\nThe TiDB Cloud API uses [HTTP Digest Authentication](https://en.wikipedia.org/wiki/Digest_access_authentication). It protects your private key from being sent over the network. For more details about HTTP Digest Authentication, refer to the [IETF RFC](https://datatracker.ietf.org/doc/html/rfc7616).\n\n## API key overview\n\n- The API key contains a public key and a private key, which act as the username and password required in the HTTP Digest Authentication. The private key only displays upon the key creation.\n- The API key belongs to your organization and acts as the `Organization Owner` role. You can check [permissions of owner](https://docs.pingcap.com/tidbcloud/manage-user-access#configure-member-roles).\n- You must provide the correct API key in every request. Otherwise, TiDB Cloud responds with a `401` error.\n\n## API key management\n\n### Create an API key\n\nOnly the **owner** of an organization can create an API key.\n\nTo create an API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **Create API Key**.\n4. Enter a description for your API key.\n5. Configure the role and scope for the API key. For more information about the permissions of a role, see [User roles](https://docs.pingcap.com/tidbcloud/manage-user-access/#user-roles).\n6. Click **Generate API Key**. Copy and save the public key and the private key.\n7. Make sure that you have copied and saved the private key in a secure location. The private key only displays upon the creation. After leaving this page, you will not be able to get the full private key again.\n8. Click **Done**.\n\n### View details of an API key\n\nTo view details of an API key, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. You can view the details of the API keys on the page.\n\n### Edit an API key\n\nOnly the **owner** of an organization can modify an API key.\n\nTo edit an API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to change, and then click **Update Role**.\n4. You can update the description and role of the API key.\n5. Click **Update**.\n\n### Delete an API key\n\nOnly the **owner** of an organization can delete an API key.\n\nTo delete an API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to delete, and then click **Delete**.\n4. Click **I understand, delete it.**\n\n# Rate Limiting\n\nThe TiDB Cloud API allows up to 100 requests per minute per API key. If you exceed the rate limit, the API returns a `429` error. For more quota, you can [submit a request](https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519) to contact our support team.\n\nEach API request returns the following headers about the limit.\n\n- `X-Ratelimit-Limit-Minute`: The number of requests allowed per minute. It is 100 currently.\n- `X-Ratelimit-Remaining-Minute`: The number of remaining requests in the current minute. When it reaches `0`, the API returns a `429` error and indicates that you exceed the rate limit.\n- `X-Ratelimit-Reset`: The time in seconds at which the current rate limit resets.\n\nIf you exceed the rate limit, an error response returns like this.\n\n```\n> HTTP/2 429\n> date: Fri, 22 Jul 2022 05:28:37 GMT\n> content-type: application/json\n> content-length: 66\n> x-ratelimit-reset: 23\n> x-ratelimit-remaining-minute: 0\n> x-ratelimit-limit-minute: 100\n> x-kong-response-latency: 2\n> server: kong/2.8.1\n\n> {\"details\":[],\"code\":49900007,\"message\":\"The request exceeded the limit of 100 times per apikey per minute. For more quota, please contact us: https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519\"}\n```\n\n# API Changelog\n\nThis changelog lists all changes to the TiDB Cloud API.\n\n<!-- In reverse chronological order -->\n\n## 20250812\n\n- \"TiDB Cloud Serverless\" is renamed to \"TiDB Cloud Starter\".\n\n## 2024-05-23\n\n- Add the [Return the monthly bill with daily usage details](#tag/Billing/paths/~1billsDetails~1%7BbilledMonth%7D/get) endpoint.\n- Add the [Return the usage details according to a cost explorer query](#tag/Billing/paths/~1billsCostExplorer/post) endpoint.\n- Add the [Return basic info of a specific organization](#tag/Billing/paths/~1billsCostExplorer~1args/get) endpoint.\n## 2023-09-28\n\n- Add the [Return monthly bill](#tag/bills/paths/~1bills~1%7BYYYY-MM%7D/get) endpoint.\n"
title: System OPEN Billing API
contact: {}
version: v1beta1
servers:
- url: https://billing.tidbapi.com/v1beta1
tags:
- name: Billing
paths:
/bills/{billedMonth}:
get:
x-code-samples:
- lang: curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://billing.tidbapi.com/v1beta1/bills/{billedMonth}'"
description: This endpoint retrieves the bill for the given month of a specific organization. You can query a bill up to 6 months prior to the current month. The bill is returned in JSON format.To use this resource, the requesting API Key must have the Organization Billing Admin or Organization Owner role.
tags:
- Billing
summary: Return organization monthly bills
parameters:
- description: The month of this bill happens for the specified organization, format is YYYY-MM, for example '2023-08'.
name: billedMonth
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/forms.BillsExplorer'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/billing_errors.BaseError'
/billsCostExplorer:
post:
x-code-samples:
- lang: curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request POST \\\n --url 'https://billing.tidbapi.com/v1beta1/billsCostExplorer'"
description: 'This endpoint executes a cost explorer query and returns the usage details. Cost Explorer query:'
tags:
- Billing
summary: Return the usage details according to a cost explorer query
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/forms.BillsCostExplorer'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/billing_errors.BaseError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/forms.TrendsInput'
description: args
required: true
/billsCostExplorer/args:
get:
x-code-samples:
- lang: curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://billing.tidbapi.com/v1beta1/billsCostExplorer/args'"
description: This endpoint retrieves the basic info for a specific organization, including service info, cloud provider info, project info, and cluster info.
tags:
- Billing
summary: Return basic info of a specific organization, which contains the key info to execute a cost explorer query
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/forms.TrendsArgs'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/billing_errors.BaseError'
/billsDetails/{billedMonth}:
get:
x-code-samples:
- lang: curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://billing.tidbapi.com/v1beta1/billsDetails/{billedMonth}'"
description: This endpoint retrieves the bill for the given month of a specific organization with daily usage details. You can query a bill up to 6 months prior to the current month. The bill is returned in JSON format. To use this resource, the requesting API Key must have the Organization Billing Admin or Organization Owner role.
tags:
- Billing
summary: Return the monthly bill of the organization with daily usage details
parameters:
- description: The month of this bill happens for the specified organization. The format is `YYYY-MM`, for example '2024-05'.
name: billedMonth
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/forms.BillsDetails'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/billing_errors.BaseError'
components:
schemas:
forms.TimeRange:
type: object
properties:
endDate:
description: End date of the time range.
type: string
startDate:
description: Start date of the time range.
type: string
forms.BillsCostExplorerElements:
type: object
properties:
billedDate:
type: string
breakdown:
type: array
items:
$ref: '#/components/schemas/forms.BillsCostExplorerBreakdown'
credits:
description: The total credits held by the organization in this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
discounts:
description: The total amount of discounts applied to this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
runningTotal:
description: The sum of services that the specified organization has consumed during this bill period. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
totalCost:
description: 'The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
`total_cost` = `running_total` - `discounts` - `credits`.'
type: string
example: '0.00'
forms.CostExplorerProvider:
type: object
properties:
name:
description: Name of Cloud provider.
type: string
regions:
description: Name of region.
type: array
items:
type: string
forms.TrendsInput:
type: object
properties:
filter:
$ref: '#/components/schemas/forms.TrendsFilter'
groups:
$ref: '#/components/schemas/forms.Groups'
forms.BillsCostExplorer:
type: object
properties:
credits:
description: The total credits held by the organization in this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
discounts:
description: The total amount of discounts applied to this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
elements:
type: array
items:
$ref: '#/components/schemas/forms.BillsCostExplorerElements'
runningTotal:
description: The sum of services that the specified organization has consumed during this bill period. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
totalCost:
description: 'The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
`total_cost` = `running_total` - `discounts` - `credits`.'
type: string
example: '0.00'
forms.CostExplorerService:
type: object
properties:
category:
description: 2nd level of service.
type: string
component:
description: 3rd level of service.
type: string
product:
description: 1st level of service.
type: string
service:
type: string
forms.BillsExplorer:
type: object
properties:
overview:
description: The overall information for a bill in the specified organization.
allOf:
- $ref: '#/components/schemas/forms.BillsOverview'
summaryByProject:
description: A breakdown of the bill by project.
allOf:
- $ref: '#/components/schemas/forms.SummaryByProject'
summaryByService:
description: A breakdown of the bill by service.
type: array
items:
$ref: '#/components/schemas/forms.BillsServiceCosts'
forms.BillsOtherName:
type: object
properties:
chargeName:
type: string
example: Support Plan
credits:
description: The total credits held by the organization in this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
discounts:
description: The total amount of discounts applied to this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
runningTotal:
description: The sum of services that the specified organization has consumed during this bill period. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
totalCost:
description: 'The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
`total_cost` = `running_total` - `discounts` - `credits`.'
type: string
example: '0.00'
forms.BillsCostExplorerBreakdown:
type: object
properties:
billedDate:
type: string
credits:
description: The total credits held by the organization in this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
detailKey:
type: string
detailName:
type: string
discounts:
description: The total amount of discounts applied to this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
runningTotal:
description: The sum of services that the specified organization has consumed during this bill period. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
totalCost:
description: 'The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
`total_cost` = `running_total` - `discounts` - `credits`.'
type: string
example: '0.00'
forms.CostExplorerTrendsBreakdownKey:
type: string
enum:
- service
- product
- project
- cluster
- provider
- region
x-enum-varnames:
- CostExploreTrendsBreakdownKeyService
- CostExploreTrendsBreakdownKeyProduct
- CostExploreTrendsBreakdownKeyProject
- CostExploreTrendsBreakdownKeyCluster
- CostExploreTrendsBreakdownKeyProvider
- CostExploreTrendsBreakdownKeyRegion
forms.ClusterOpenAPI:
type: object
properties:
ProjectID:
type: string
example: '0'
id:
type: string
example: '0'
name:
type: string
regionName:
type: string
status:
type: string
forms.CostExplorerTrendsTimeGroup:
type: string
enum:
- day
- month
- total
x-enum-varnames:
- CostExploreTrendsTimeGroupDay
- CostExploreTrendsTimeGroupMonth
- CostExploreTrendsTimeGroupTotal
forms.BillsDetail:
type: object
properties:
billedDate:
description: The date when this bill happens.
type: string
clusterName:
description: Name of the cluster.
type: string
credits:
description: The total credits held by the organization in this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
discounts:
description: The total amount of discounts applied to this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
projectName:
description: Name of the project.
type: string
runningTotal:
description: The sum of services that the specified organization has consumed during this bill period. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
servicePathName:
description: Name of the service.
type: string
totalCost:
description: 'The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
`total_cost` = `running_total` - `discounts` - `credits`.'
type: string
example: '0.00'
forms.SummaryByProject:
type: object
properties:
otherCharges:
description: These charges occur not only within a project but also across the entire organization.
type: array
items:
$ref: '#/components/schemas/forms.BillsOtherName'
projects:
description: The projects in the specified organization.
type: array
items:
$ref: '#/components/schemas/forms.BillsProjects'
forms.Groups:
type: object
properties:
groupBy:
description: "Group cost explorer query results by category. The category includes:\n 1. \"service\": Group query results by service type\n 2. \"product\": Group query results by product type (TiDB Dedicated, TiDB Cloud Starter, or TiDB Cloud Essential)\n 3. \"project\": Group query results by Project IDs\n 4. \"cluster\": Group query results by Cluster IDs\n 5. \"provider\": Group query results by Cloud Provider\n 6. \"region\": Group query results by cloud provider region"
type: array
items:
$ref: '#/components/schemas/forms.CostExplorerTrendsBreakdownKey'
timeGranularity:
description: "Time Granularity determines how the cost explorer query results are organized daily, monthly, or in total.\n 1. \"day\": Query results are organized daily\n 2. \"month\": Query results are organized monthly\n 3. \"total\": Query results are organized in total"
allOf:
- $ref: '#/components/schemas/forms.CostExplorerTrendsTimeGroup'
forms.BillsDetails:
type: object
properties:
details:
type: array
items:
$ref: '#/components/schemas/forms.BillsDetail'
forms.TrendsArgs:
type: object
properties:
clusters:
type: array
items:
$ref: '#/components/schemas/forms.ClusterOpenAPI'
projects:
type: array
items:
$ref: '#/components/schemas/forms.ProjectOpenAPI'
providers:
type: array
items:
$ref: '#/components/schemas/forms.Provider'
services:
description: 'The Identifier of TiDB Cloud services consists of 3 levels. For example, "service": "TiDB Dedicated - Node Compute - TiFlash" consists of the following 3 levels.'
type: array
items:
$ref: '#/components/schemas/forms.CostExplorerService'
forms.BillsProjects:
type: object
properties:
credits:
description: The total credits held by the organization in this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
discounts:
description: The total amount of discounts applied to this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
projectName:
description: The name of a project in the specified organization.
type: string
example: prod-project
runningTotal:
description: The sum of services that the specified organization has consumed during this bill period. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
totalCost:
description: 'The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
`total_cost` = `running_total` - `discounts` - `credits`.'
type: string
example: '0.00'
forms.Provider:
type: object
properties:
name:
description: Name of the cloud provider
type: string
regions:
description: Name of the region
type: array
items:
type: string
forms.TrendsFilter:
type: object
properties:
clusters:
type: array
items:
type: string
projects:
type: array
items:
type: string
providers:
type: array
items:
$ref: '#/components/schemas/forms.CostExplorerProvider'
services:
type: array
items:
$ref: '#/components/schemas/forms.CostExplorerService'
timeRange:
$ref: '#/components/schemas/forms.TimeRange'
forms.ProjectOpenAPI:
type: object
properties:
id:
type: string
example: '0'
name:
type: string
status:
type: string
forms.BillsOverview:
type: object
properties:
billedMonth:
description: The month in which this bill is generated for the specified organization.
type: string
example: 2023-09
credits:
description: The total credits held by the organization in this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
discounts:
description: The total amount of discounts applied to this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
runningTotal:
description: The sum of services that the specified organization has consumed during this bill period. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
totalCost:
description: 'The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
`total_cost` = `running_total` - `discounts` - `credits`.'
type: string
example: '0.00'
billing_errors.BaseError:
type: object
properties:
code:
type: string
error: {}
msgPrefix:
type: string
status:
type: integer
forms.BillsServiceCosts:
type: object
properties:
credits:
description: The total credits held by the organization in this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
discounts:
description: The total amount of discounts applied to this bill. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
runningTotal:
description: The sum of services that the specified organization has consumed during this bill period. The value of this field is expressed in cents (100ths of one US Dollar).
type: string
example: '0.00'
serviceCosts:
type: array
items:
$ref: '#/components/schemas/forms.BillsServiceCosts'
serviceName:
description: The name of services provided by TiDB Cloud.
type: string
example: TiDB Dedicated
totalCost:
description: 'The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
`total_cost` = `running_total` - `discounts` - `credits`.'
type: string
example: '0.00'
x-tagGroups:
- name: Endpoints
tags:
- Billing