cloud: update api doc description about v1beta2 by qqqdan · Pull Request #24369 · pingcap/docs

qqqdan · 2026-10-09T12:11:31Z

First-time contributors' checklist

I've signed the Contributor License Agreement, which is required for the repository owners to accept my contribution.

What is changed, added, or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

What is the related PR or file link(s)?

Related code change PR links (if applicable):
This PR is translated from:
Other reference link(s):

AI agent involvement

The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

Delete files
Change aliases
Need modification after applied to another branch
Might cause conflicts after applied to another branch

Summary by CodeRabbit

Documentation
- Clarified which TiDB Cloud tiers and resources are covered by the v1beta and v1beta2 APIs.
- Added version guidance for Essential clusters: use v1beta2 for CLOUD.202603.x or later, and v1beta1 for version 8.5 or earlier.

ti-chi-bot · 2026-10-09T12:11:44Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign lance6716 for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

coderabbitai · 2026-10-09T12:12:10Z

📝 Walkthrough

Walkthrough

The API documentation clarifies the scope of v1beta and v1beta2. It also specifies which API version applies to Essential instances based on their software version.

Changes

API version guidance

Layer / File(s)	Summary
API scope and version routing `api/tidb-cloud-api-overview.md`, `api/tidb-cloud-api-v1beta1.md`, `api/tidb-cloud-api-v1beta2.md`	The overview limits v1beta’s listed scope to Dedicated clusters and includes Essential instances in v1beta2. The version-specific pages direct Essential instances on `CLOUD.202603.x` or later to v1beta2, and instances on v8.5 or earlier to v1beta1.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Suggested reviewers: zhangpeijin-milo

Merge Risk: 🔵 Low · up to 7fad7

The docs contain a spelling error and wording that could confuse Premium users about v1beta2 eligibility. These are bounded documentation risks, with no runtime routing impact evidenced here, so merging is reasonable with the wording fixes tracked.

Architecture Summary

Architecture risk: 🔵 Low · up to 7fad7

The change affects 1 system.

Changed systems: api

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

observed — api (service) was modified; 3 changed files map to changed impact.

Before / after behavior

observed — Modified behavior in api/tidb-cloud-api-overview.md: The v1beta2 description now includes Essential instances alongside Premium instances. The v1beta description now limits its listed management scope to Dedicated clusters; the v1beta1 description is unchanged.
observed — Modified behavior in api/tidb-cloud-api-v1beta1.md: The Starter or Essential Cluster entry is limited to version 8.5 or earlier. A new note directs Essential clusters on CLOUD.202603.x or higher to API v1beta2.
observed — Modified behavior in api/tidb-cloud-api-v1beta2.md: The overview expands v1beta2’s stated scope from Premium-only to Premium and Essential, updates the API and resource descriptions to include both tiers, and adds an availability note directing Essential instances on v8.5 or earlier to v1beta1 while limiting v1beta2 to Essential instances running CLOUD.202603.x or later.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check		The description retains the template but does not provide the required change summary, affected TiDB version, or reference links. It is largely incomplete.	Describe the v1beta2 API documentation changes and their purpose. Select the applicable TiDB version, including the release branch or master as appropriate. Add related PR or file links when available, and complete any applicable checklist …

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly identifies an update to the v1beta2 API documentation. It is concise and related to the main changes.

Full details: Description check

Resolution

Describe the v1beta2 API documentation changes and their purpose. Select the applicable TiDB version, including the release branch or master as appropriate. Add related PR or file links when available, and complete any applicable checklist items.

Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

zhangpeijin-milo

lgtm

ti-chi-bot · 2026-10-09T12:12:33Z

@zhangpeijin-milo: adding LGTM is restricted to approvers and reviewers in OWNERS files.

Details

In response to this:

lgtm

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

coderabbitai

Actionable comments posted: 2

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: pingcap/docs/.coderabbit.yaml
Review profile: ASSERTIVE
Plan: Advanced
Run ID: eeaaa70c-e649-4f47-88aa-d64cd434a9f1

📥 Commits

Reviewing files that changed from the base of the PR and between e5b8ce2 and 7fad74b.

📒 Files selected for processing (3)

api/tidb-cloud-api-overview.md
api/tidb-cloud-api-v1beta1.md
api/tidb-cloud-api-v1beta2.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

coderabbitai · 2026-10-09T12:17:14Z


 - Cluster-level resources:
-    - [TiDB Cloud Starter or Essential Cluster](https://docs.pingcap.com/tidbcloud/api/v1beta1/serverless): manage clusters, branches, data export tasks, and data import tasks for TiDB Cloud Starter or Essential clusters.
+    - [TiDB Cloud Starter or Essential Cluster](https://docs.pingcap.com/tidbcloud/api/v1beta1/serverless): manage clusters, branches, data export tasks, and data import tasks for TiDB Cloud Starter or Essential clusers （v8.5 or earlier）.


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Correct the misspelling clusers.

Replace it with clusters.

- [TiDB Cloud Starter or Essential Cluster](https://docs.pingcap.com/tidbcloud/api/v1beta1/serverless): manage clusters, branches, data export tasks, and data import tasks for TiDB Cloud Starter or Essential clusters （v8.5 or earlier）.

As per path instructions, provide a GitHub committable suggestion when the replacement is exact.

Source: Path instructions

coderabbitai · 2026-10-09T12:17:14Z

+
+> **Note:**
+>
+> TiDB Cloud API v1beta2 is only available for Essential instances running version CLOUD.202603.x or later. For Essential instances on version v8.5 or earlier, please use the TiDB Cloud API [v1beta1](/api/tidb-cloud-api-v1beta1.md)


🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Scope the version rule to Essential instances.

The page lists Premium and Essential support on Lines 8–16. This note says v1beta2 is available only for qualifying Essential instances, which makes the Premium API scope unclear. State the version routing specifically for Essential instances.

> For Essential instances running version CLOUD.202603.x or later, use TiDB Cloud API v1beta2. For Essential instances running version v8.5 or earlier, use TiDB Cloud API [v1beta1](/api/tidb-cloud-api-v1beta1.md).

As per path instructions, provide a GitHub committable suggestion when the replacement is exact.

Source: Path instructions

change

7fad74b

ti-chi-bot Bot added missing-translation-status This PR does not have translation status info. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Oct 9, 2026

zhangpeijin-milo approved these changes Oct 9, 2026

View reviewed changes

coderabbitai Bot reviewed Oct 9, 2026

View reviewed changes

qiancai self-assigned this Oct 10, 2026

qiancai changed the title ~~change~~ cloud: update api doc description about v1beta2 Oct 10, 2026

qiancai added translation/no-need No need to translate this PR. area/tidb-cloud This PR relates to the area of TiDB Cloud. labels Oct 10, 2026

ti-chi-bot Bot removed the missing-translation-status This PR does not have translation status info. label Oct 10, 2026

Navigation Menu

Repository navigation

cloud: update api doc description about v1beta2 - #24369

cloud: update api doc description about v1beta2#24369
qqqdan wants to merge 1 commit into
release-8.5from
essential-API-change

qqqdan commented Oct 9, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

ti-chi-bot Bot commented Oct 9, 2026

Uh oh!

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

zhangpeijin-milo left a comment

Uh oh!

ti-chi-bot Bot commented Oct 9, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Oct 9, 2026

Uh oh!

coderabbitai Bot Oct 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

qqqdan commented Oct 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

First-time contributors' checklist

What is changed, added, or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

What is the related PR or file link(s)?

AI agent involvement

Do your changes match any of the following descriptions?

Summary by CodeRabbit

Uh oh!

ti-chi-bot Bot commented Oct 9, 2026

Uh oh!

coderabbitai Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Architecture Summary

❌ Failed checks (1 warning)

Uh oh!

zhangpeijin-milo left a comment

Choose a reason for hiding this comment

Uh oh!

ti-chi-bot Bot commented Oct 9, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

qqqdan commented Oct 9, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading