# Starter/Essential v1 OpenAPI Operation Map

Authoritative swagger sources:

- `tidbcloud/tidb-management-service`
- `tidbcloud/serverless-service`

## Base URL Modes

Starter/Essential v1 has two OpenAPI host surfaces in cp9. Do not assume every `/v1beta1` path is served by the same local service.

| Surface | Source | Hosted by in cp9 | Base URL variable | Path shape |
| --- | --- | --- | --- | --- |
| Management portal serverless OpenAPI | `tidb-management-service/api/spec/tidb_cloud_open_api/serverless/v1beta1/services.swagger.json` | `tidb-mgmt-portal` | `TC_STARTER_OPENAPI_BASE_URL` | base already includes `/v1beta1`; append `/clusters`, `/regions`, `/shadowPools`, etc. |
| Serverless service OpenAPI | `serverless-service/apidocs/v1beta1/*.swagger.json` | `serverless-service` | `TC_STARTER_SERVERLESS_BASE_URL` | append full `/v1beta1/clusters/...` paths from the swagger files. |

`TC_STARTER_BRANCH_BASE_URL` is a compatibility alias for `TC_STARTER_SERVERLESS_BASE_URL`; prefer the latter for new work.

## Management Portal Operations

These operations come from `services.swagger.json` and are routed through `tidb-mgmt-portal`.

| Operation ID | Method | Path appended to `TC_STARTER_OPENAPI_BASE_URL` | Notes |
| --- | --- | --- | --- |
| `ClusterService_ListClusters` | GET | `/clusters` | Read-only cluster list. |
| `ClusterService_CreateCluster` | POST | `/clusters` | Mutating cluster create. |
| `ClusterService_GetCluster` | GET | `/clusters/{clusterId}` | Read-only cluster lookup and lifecycle polling. |
| `ClusterService_DeleteCluster` | DELETE | `/clusters/{clusterId}` | Destructive cluster delete; require post-delete verification. |
| `ClusterService_BindTags` | POST | `/clusters/{clusterId}:bindTags` | Mutating tag update. |
| `ClusterService_UnbindTags` | POST | `/clusters/{clusterId}:unbindTags` | Mutating tag update. |
| `ClusterService_PartialUpdateCluster` | PATCH | `/clusters/{cluster.clusterId}` | Mutating partial update. |
| `ClusterService_ChangeRootPassword` | PUT | `/clusters/{clusterId}/password` | Mutating password change; never log password values. |
| `ClusterService_ListRegions` | GET | `/regions` | Read-only region discovery. |
| `ClusterService_ListCloudProviders` | GET | `/regions:listCloudProviders` | Read-only cloud provider discovery. |
| `ClusterService_BatchCreateClusters` | POST | `/clusters:batchCreate` | Mutating batch create; use only with explicit review. |
| `ClusterService_BatchGetClusters` | GET | `/clusters:batchGet` | Read-only batch lookup. |
| `ClusterService_BatchDeleteClusters` | POST | `/clusters:batchDelete` | Destructive batch delete; require exact target review. |
| `ClusterService_ClaimClusterFromZero` | POST | `/clusters:claimFromZero` | Pool/zero-state mutation; use only for explicit pool workflows. |
| `ClusterService_TakeoverClusterFromPool` | POST | `/clusters:takeoverFromPool` | Pool takeover mutation; use only for explicit pool workflows. |
| `ShadowPoolService_ListShadowPools` | GET | `/shadowPools` | Read-only shadow pool list. |
| `ShadowPoolService_CreateShadowPool` | POST | `/shadowPools` | Mutating shadow pool create. |
| `ShadowPoolService_GetShadowPool` | GET | `/shadowPools/{shadowPoolId}` | Read-only shadow pool lookup. |
| `ShadowPoolService_DeleteShadowPool` | DELETE | `/shadowPools/{shadowPoolId}` | Destructive shadow pool delete. |
| `ShadowPoolService_UpdateShadowPool` | PATCH | `/shadowPools/{shadowPool.shadowPoolId}` | Mutating shadow pool update. |
| `ShadowPoolService_ReplaceShadowPoolInitSqls` | POST | `/shadowPools/{shadowPoolId}:replaceInitSqls` | Mutating init SQL replacement. |
| `ShadowPoolService_ReplaceShadowPoolInstanceDemand` | POST | `/shadowPools/{shadowPoolId}:replaceInstanceDemand` | Mutating demand replacement. |

## Serverless Service Swagger Files

These operations come from `serverless-service/apidocs/v1beta1` and are routed through `serverless-service`.

| File | Operation families | Notes |
| --- | --- | --- |
| `branch.swagger.json` | `BranchService_ListBranches`, `BranchService_CreateBranch`, `BranchService_GetBranch`, `BranchService_DeleteBranch`, `BranchService_ResetBranch`, `BranchService_UpdateSqlUser` | Branch lifecycle and SQL-user password operations. Current Essential v1 may return empty HTTP 200 or HTTP 403 for list-branches; treat that result separately and use `ClusterService_GetCluster` for cluster endpoint data when authorized. |
| `cdc.swagger.json` | `ChangefeedService_ListChangefeeds`, `ChangefeedService_CreateChangefeed`, `ChangefeedService_GetChangefeed`, `ChangefeedService_DeleteChangefeed`, `ChangefeedService_EditChangefeed`, start/stop/scale/test/describe/list-specifications | CDC/changefeed operations. Bodies can contain sink credentials. |
| `dm.swagger.json` | `MigrationService_ListMigrations`, `MigrationService_CreateMigration`, `MigrationService_GetMigration`, `MigrationService_DeleteMigration`, pause/resume/precheck/get-precheck/cancel-precheck | Migration from MySQL-compatible sources. Bodies can contain source/target credentials. |
| `import.swagger.json` | `ImportService_StartUpload`, `ImportService_CompleteUpload`, `ImportService_ListImports`, `ImportService_CreateImport`, `ImportService_GetImport`, `ImportService_CancelImport` | Import from SQL/CSV/Parquet/Aurora Snapshot. Upload and source bodies can contain object storage credentials. |
| `export.swagger.json` | `ExportService_ListExports`, `ExportService_CreateExport`, `ExportService_GetExport`, `ExportService_DeleteExport`, `ExportService_CancelExport`, download/list-files/download-files | Export tasks and exported file access. Download responses are sensitive. |
| `auditlog.swagger.json` | `DatabaseAuditLogService_*` file list/download, filter rule CRUD, config get/update | Database audit log v2-style paths under `/auditLog`. |
| `auditlogv1.swagger.json` | `AuditLogService_*` log list/download and filter rule CRUD | Database audit log v1-style paths under `/auditlogs`. |
| `privatelink.swagger.json` | `PrivateLinkConnectionService_GetPrivateLinkConnection`, `PrivateLinkConnectionService_ListPrivateLinkConnections`, `PrivateLinkConnectionService_CreatePrivateLinkConnection`, `PrivateLinkConnectionService_DeletePrivateLinkConnection`, availability zones, attach/detach domains | PrivateLink connection workflows. Mutating operations require cloud-side cleanup proof. |

## Path Guardrails

- Management portal paths are appended to `TC_STARTER_OPENAPI_BASE_URL`, which should already end in `/v1beta1`.
- Serverless service paths are already fully versioned in the swagger files; append them to `TC_STARTER_SERVERLESS_BASE_URL`, not to a base ending in `/v1beta1`.
- When one workflow mixes both surfaces, resolve and review every full URL before execution.
- Treat POST requests that look like validation or download helpers as sensitive; their bodies or responses can include database, sink, source, object storage, or endpoint credentials.