diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md
index 8cf01a75cfebf..33d663eddd180 100644
--- a/TOC-tidb-cloud-essential.md
+++ b/TOC-tidb-cloud-essential.md
@@ -553,6 +553,7 @@
- [URI Formats of External Storage Services](/external-storage-uri.md)
- [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md)
- [Notifications](/tidb-cloud/notifications.md)
+ - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md)
- Support Plan
- [Connected Care Overview](/tidb-cloud/connected-care-overview.md)
- [Connected Care Details](/tidb-cloud/connected-care-detail.md)
@@ -572,4 +573,5 @@
- [Get Support](/tidb-cloud/tidb-cloud-support.md)
- FAQs
- [TiDB Cloud FAQs](/tidb-cloud/tidb-cloud-faq.md)
+ - [Project Migration FAQ for TiDB X Instances](/tidb-cloud/tidbx-instance-move-faq.md)
- [Glossary](/tidb-cloud/tidb-cloud-glossary.md)
diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md
index 67172ccf892f3..997ca6188baeb 100644
--- a/TOC-tidb-cloud-starter.md
+++ b/TOC-tidb-cloud-starter.md
@@ -544,6 +544,7 @@
- [URI Formats of External Storage Services](/external-storage-uri.md)
- [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md)
- [Notifications](/tidb-cloud/notifications.md)
+ - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md)
- Support Plan
- [Connected Care Overview](/tidb-cloud/connected-care-overview.md)
- [Connected Care Details](/tidb-cloud/connected-care-detail.md)
@@ -559,4 +560,5 @@
- FAQs
- [TiDB Cloud FAQs](/tidb-cloud/tidb-cloud-faq.md)
- [{{{ .starter }}} FAQs](/tidb-cloud/serverless-faqs.md)
+ - [Project Migration FAQ for TiDB X Instances](/tidb-cloud/tidbx-instance-move-faq.md)
- [Glossary](/tidb-cloud/tidb-cloud-glossary.md)
diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md
new file mode 100644
index 0000000000000..413db21552ead
--- /dev/null
+++ b/tidb-cloud/tidbx-instance-move-faq.md
@@ -0,0 +1,143 @@
+---
+title: Project Migration FAQ for TiDB X Instances
+summary: Learn why TiDB Cloud prompts you to move or convert your {{{ .starter }}} and Essential resources, what changes during project migration, and what follow-up actions might be required.
+---
+
+# Project Migration FAQ for TiDB X Instances
+
+TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X architecture](/tidb-cloud/tidb-x-architecture.md), including {{{ .starter }}} and {{{ .essential }}} instances.
+
+This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to move your {{{ .starter }}} and Essential instances to TiDB X projects, what changes occur during the migration process, and what follow-up actions you need to take.
+
+## Why does the TiDB Cloud console prompt me to move my {{{ .starter }}} and Essential instances?
+
+Before April 15, 2026, TiDB Cloud used a single **TiDB dedicated project** type to manage all TiDB Cloud resources. Such a project could contain a mix of {{{ .dedicated }}} clusters and TiDB X instances. However, mixing different resource types in one project increased management complexity because:
+
+- TiDB dedicated projects were originally designed for {{{ .dedicated }}} clusters.
+- TiDB X instances and {{{ .dedicated }}} clusters have different behaviors and management models.
+
+Starting from April 15, 2026, TiDB Cloud introduces separate project types to provide clear separation between different resource types. Each project type now exclusively hosts its own resource type:
+
+- **TiDB dedicated project**: for {{{ .dedicated }}} clusters
+- **TiDB X project**: for TiDB X instances
+- **TiDB X virtual project**: for TiDB X instances not grouped in any TiDB X project
+
+TiDB X projects are lightweight and optional for TiDB X instances, while dedicated projects are mandatory for {{{ .dedicated }}} clusters. Separating these resources ensures a more consistent user experience and eliminates confusion over which project capabilities apply.
+
+As a result of this separation, dedicated projects can no longer contain TiDB X instances. If your organization has existing {{{ .starter }}} or Essential resources in dedicated projects, TiDB Cloud prompts you to move them to TiDB X projects to align with the new resource model.
+
+## What project types are available in TiDB Cloud?
+
+TiDB Cloud provides three project types for different resource types and use cases.
+
+- **TiDB dedicated project**: this project type is used only for {{{ .dedicated }}} clusters.
+
+ - It helps you manage settings for {{{ .dedicated }}} clusters separately by project, such as RBAC, networks, maintenance, alert subscriptions, and encryption access.
+ - Each {{{ .dedicated }}} cluster must belong to a dedicated project.
+ - {{{ .dedicated }}} clusters cannot be moved between projects because of their infrastructure bindings.
+
+- **TiDB X project**: this project type is used only for TiDB X instances.
+
+ - It helps you manage RBAC for TiDB X instances by project.
+ - TiDB X projects are lightweight and optional, so you can create TiDB X instances without assigning them to a project.
+ - Projects are useful when you want to organize and group TiDB X instances, but they are not required.
+ - You can move TiDB X instances between TiDB X projects or back to the organization level.
+
+- **TiDB X virtual project**: this project is virtual and does not provide any management capabilities.
+
+ - It acts as a logical container for TiDB X instances that do not belong to any project, so these instances can be accessed through the TiDB Cloud API by using a project ID.
+ - Each organization has a unique virtual project ID.
+ - You can get this ID from the project view on the **[My TiDB](https://tidbcloud.com/tidbs)** page.
+
+The following table lists the differences between these project types:
+
+| Feature | TiDB dedicated project | TiDB X project | TiDB X virtual project |
+|---|---|---|---|
+| Project icon in the TiDB Cloud console | | | N/A |
+| Resource type | {{{ .dedicated}}} clusters only | TiDB X instances only | TiDB X instances only |
+| Project is optional | ❌ (Each {{{ .dedicated }}} cluster must belong to a dedicated project) | ✅ (You can either group a TiDB X instance in a TiDB X project or keep it at the organization level) | N/A (TiDB X instances not grouped in any TiDB X project are automatically grouped in the TiDB X virtual project) |
+| Project settings | ✅ | ❌ | ❌ |
+| Infrastructure binding | ✅ (Strong binding) | ❌ | ❌ |
+| RBAC model | Organization -> Project | Organization -> Project -> Instance | Organization -> Project -> Instance |
+| Project-level RBAC | ✅ | ✅ | ❌ |
+| Project-level billing | ✅ | ✅ | ❌ |
+| Instance movement between projects | ❌ | ✅ (You can move a TiDB X instance to a specific TiDB X project or out of any project) | ✅ (You can move a TiDB X instance out of any TiDB X project to a specific TiDB X project) |
+
+## Do I need to move my {{{ .starter }}} and Essential instances?
+
+It depends on how your current project is structured:
+
+- If your project contains only {{{ .starter }}} and Essential instances, TiDB Cloud converts the project to a TiDB X project automatically on April 15, 2026. No further action is required.
+- If your project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, the TiDB Cloud console prompts you to move the {{{ .starter }}} and Essential instances to a new TiDB X project by clicking **Move & Unlock** in the top banner.
+
+## Who can perform the migration?
+
+Only users with the `Organization Owner` role can start and complete the migration.
+
+## What happens if my project contains only {{{ .starter }}} and Essential instances?
+
+Projects that contain only {{{ .starter }}} and Essential instances are converted to a TiDB X project automatically on April 15, 2026.
+
+What changes after the migration:
+
+- The project becomes a TiDB X project.
+- The new TiDB X project does not include dedicated project settings, such as network settings, CMEK settings, and maintenance configurations.
+
+What does not change after the migration:
+
+- Your existing instances and their data, availability, and performance.
+- Your billing and usage.
+- The project name and project ID.
+
+## What happens if my project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances?
+
+With the introduction of separate project types for different TiDB Cloud resources, a dedicated project can no longer host TiDB X instances.
+
+If a project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, TiDB Cloud prompts you in the top banner to move the {{{ .starter }}} and Essential instances in the project to a new **TiDB X project**.
+
+> **Note:**
+>
+> {{{ .dedicated }}} clusters remain in the original project after the migration. Therefore, the migration does not affect {{{ .dedicated }}} clusters.
+
+If you are the `Organization Owner`, you can click **Move & Unlock** in the top banner and follow the migration wizard to complete the migration.
+
+The migration wizard displays a list of {{{ .starter }}} and Essential instances to be moved and lets you specify a new name for the new TiDB X project.
+
+What changes after the migration:
+
+- The {{{ .starter }}} and Essential instances are moved to a newly created TiDB X project.
+- The moved instances belong to a new project ID after the migration.
+- Project-level RBAC permissions are copied to the new project.
+
+What does not change after the migration:
+
+- Your instance data.
+- Your instance availability.
+- Your instance performance.
+- Your billing and usage.
+- The underlying infrastructure of your instances.
+- {{{ .dedicated }}} clusters remain in their current projects and are not moved.
+
+There is no additional cost for this migration.
+
+After the migration, you can manage your TiDB X instances through TiDB X projects (or at the organization level), and continue to manage your {{{ .dedicated }}} clusters through dedicated projects.
+
+## What actions are required after migration?
+
+If your {{{ .starter }}} or Essential instances are moved to a new TiDB X project, review anything that depends on the original project ID or original project-level setup, such as the following:
+
+- Automation or scripts
+- Integrations
+- Project-based operational workflows
+- User access and RBAC assignments
+- Data Service setup
+- Data Apps
+- Data Service API keys
+
+Project-level RBAC permissions are copied to the new project, but you must still review access after migration to make sure users and workflows still work as expected.
+
+If you use the TiDB Cloud API to manage your instances, see [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md) to update your API calls.
+
+## Where can I get help?
+
+If you are unsure whether your automation, integrations, or Data Service setup depends on the original project ID, contact TiDB Cloud support at [support@pingcap.com](mailto:support@pingcap.com) before you start the migration.
\ No newline at end of file
diff --git a/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md b/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md
new file mode 100644
index 0000000000000..149ea61c4ce8e
--- /dev/null
+++ b/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md
@@ -0,0 +1,87 @@
+---
+title: Project API Migration Guide for {{{ .starter }}} and Essential
+summary: Learn the minimum changes needed to keep your existing v1beta API calls working after TiDB Cloud introduces separate project types for TiDB X instances.
+---
+
+# Project API Migration Guide for {{{ .starter }}} and Essential
+
+Starting from April 15, 2026, TiDB Cloud introduces separate project types for different resource types. For {{{ .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](/tidb-cloud/tidbx-instance-move-faq.md).
+
+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 {{{ .starter }}} and Essential instances.
+
+Because of these project model changes, note the following API changes:
+
+- `project_id` values for {{{ .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-type-values).
+
+## Project API changes
+
+### GET /api/v1beta/projects
+
+`GET /api/v1beta/projects` now returns a `type` field for each project.
+
+#### Project type values
+
+| Value | Description |
+|---|---|
+| `dedicated` | A project that contains only TiDB Cloud Dedicated clusters. |
+| `tidbx` | A project that contains only TiDB X instances (such as {{{ .starter }}} and Essential). |
+| `tidbx_virtual` | The default organization-level project for TiDB X instances that are not assigned to any project. For each organization, there is only a single `tidbx_virtual` project. |
+
+> **Note:**
+>
+> {{{ .starter }}} and Essential instances both use the `tidbx` project type.
+
+**If you only read `id` and `name` from project responses**, you likely do not need to make any changes.
+
+**If you need 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 {{{ .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:
+
+ ```http
+ GET https://serverless.tidbapi.com/v1beta1/clusters/{clusterId}
+ ```
+
+2. Read `labels["tidb.cloud/project"]` from the response:
+
+ ```json
+ {
+ "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`
+
+> **Note:**
+>
+> - This approach does not apply to cluster creation using `POST /api/v1beta/projects/{project_id}/clusters`.
+> - `v1beta` supports creating only {{{ .starter }}} instances and TiDB Cloud Dedicated clusters. To create a {{{ .essential }}} instance, use the `v1beta1` API instead. For more information, see [TiDB Cloud API documentation](https://docs.pingcap.com/api/).
+> - When creating new {{{ .starter }}} or Essential instances, check your cluster creation workflow to ensure that it targets a `tidbx` project.
+
+## Summary of required changes
+
+| Scenario | Action required |
+|---|---|
+| You read only `id` and `name` from project responses | No changes needed. |
+| You hardcode `project_id` for {{{ .starter }}} or Essential instances | Replace hardcoded values with a dynamic lookup using `labels["tidb.cloud/project"]`. |
+| You create projects and need to target TiDB X instances | Pass `"type": "tidbx"` in the request body of `POST /api/v1beta/projects`. |
+| You filter projects by type | Start reading the `type` field from `GET /api/v1beta/projects` responses. |
\ No newline at end of file