Project API Migration Guide for TiDB Cloud Starter and Essential

Starting from April 15, 2026, TiDB Cloud introduces separate project types for different resource types. For TiDB Cloud Starter and Essential instances, you can now manage them either in TiDB X projects or at the organization level. For more information, see Project Migration FAQ for TiDB X Instances.

This guide is intended for API callers who want to keep most existing v1beta calls working and make only the minimum changes to project lookup and cluster creation for TiDB Cloud Starter and Essential instances.

Because of these project model changes, note the following API changes:

• project_id values for TiDB Cloud Starter and Essential instances can change because these instances can be moved between projects in the TiDB Cloud console. Do not hardcode project_id values.
• Project responses now include a type field. For possible values, see Project type values.

Project API changes

GET /api/v1beta/projects

GET /api/v1beta/projects now returns a type field for each project.

Project type values

If your application only reads the id and name fields from project responses, no changes are required.

If your application needs to distinguish between project types (for example, to filter dedicated projects, TiDB X projects, or the TiDB X virtual project), start reading the type field.

POST /api/v1beta/projects

If you create projects using POST /api/v1beta/projects, note the following:

• Only dedicated and tidbx are valid type values when creating a project.
• If type is omitted, the API creates a dedicated project by default.

How to get a project ID for an existing instance

If you already have a TiDB Cloud Starter or Essential instance and only need its current project_id, use the following approach instead of hardcoding the value.

1. Call the cluster details endpoint:

   GET https://serverless.tidbapi.com/v1beta1/clusters/{clusterId}
   

2. Read labels["tidb.cloud/project"] from the response:

   {
     "clusterId": "1048576",
     "labels": {
       "tidb.cloud/project": "2293484"
     }
   }
   

3. Use the retrieved project_id with your existing v1beta endpoints. For example:

   • GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}
   • DELETE /api/v1beta/projects/{project_id}/clusters/{cluster_id}
   • GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports
   • POST /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports

Summary of required changes