# Premium OpenAPI v1beta2 Operation Map

Core TiDB swagger source:
`tidb-management-service/api/spec/tidb_cloud_open_api/nextgen/v1beta2/public.swagger.json`

Dataflow swagger sources:

- `api/import_into.swagger.json`
- `dataflow-service-ng/api/dataflow.swagger.json`
- `dataflow-service-ng/api/premium_dm.swagger.json`

## Base URL Modes

Set `TC_OPENAPI_BASE_URL` to the prefix immediately before the path in the table you are using.

| Source | Table path shape | Typical `TC_OPENAPI_BASE_URL` |
| --- | --- | --- |
| Core TiDB OpenAPI | `/tidbs...` | `https://cloud.tidbapi.com/v1beta2` or cp9-local equivalent ending in `/v1beta2` |
| Dataflow / CDC | `/api/v1beta2/...` | `https://cloud.tidbapi.com` or cp9-local gateway origin |
| Premium Migration / DM | `/v1beta2/...` | `https://cloud.tidbapi.com` or cp9-local gateway origin |
| Import Into | `/v1beta2/...` | `https://cloud.tidbapi.com` or cp9-local gateway origin |

Do not mix these modes blindly. If one workflow combines core TiDB and dataflow calls, resolve every
full URL before execution and check that the path is not doubled, for example
`/v1beta2/api/v1beta2/...`.

## Core TiDB Operations

| Operation ID | Method | Path appended to core base URL | Notes |
| --- | --- | --- | --- |
| `RegionService_ListCloudProviders` | GET | `/cloudProviders` | Hosted TiDB Cloud only; cp9-local does not route this control-plane discovery API. |
| `RegionService_ListRegions` | GET | `/regions` | Hosted TiDB Cloud only; cp9-local reads the target region from its resolved session contract. |
| `TidbService_ListTidbs` | GET | `/tidbs` | Read-only instance list. |
| `TidbService_CreateTidb` | POST | `/tidbs` | Body is `nextgenv1beta2Tidb`; supports `validateOnly`. |
| `TidbService_GetTidb` | GET | `/tidbs/{tidbId}` | Read-only instance lookup. |
| `TidbService_UpdateTidb` | PATCH | `/tidbs/{tidbId}` | Update `displayName`, `maxRcu`, or reserved capacity template; supports `validateOnly`. |
| `TidbService_DeleteTidb` | DELETE | `/tidbs/{tidbId}` | Destructive; require pre/post verification. |
| `TidbService_ResetRootPassword` | POST | `/tidbs/{tidbId}:resetRootPassword` | Body requires `rootPassword`; never log the value. |
| `PublicConnectionSettingService_GetPublicConnectionSetting` | GET | `/tidbs/{tidbId}/publicConnectionSetting` | Read-only public endpoint setting lookup. |
| `PublicConnectionSettingService_UpdatePublicConnectionSetting` | PATCH | `/tidbs/{tidbId}/publicConnectionSetting` | Mutating public endpoint enable/disable and CIDR allowlist update. |
| `PrivateEndpointConnectionService_GetPrivateLinkService` | GET | `/tidbs/{tidbId}/privateLinkService` | Read-only PrivateLink service status; poll until `ACTIVE` before AWS endpoint work. |
| `PrivateEndpointConnectionService_ListPrivateEndpointConnections` | GET | `/tidbs/{tidbId}/privateEndpointConnections` | Read-only private endpoint connection list. |
| `PrivateEndpointConnectionService_CreatePrivateEndpointConnection` | POST | `/tidbs/{tidbId}/privateEndpointConnections` | Mutating registration of a cloud VPC endpoint id. |
| `PrivateEndpointConnectionService_GetPrivateEndpointConnection` | GET | `/tidbs/{tidbId}/privateEndpointConnections/{connectionId}` | Read-only private endpoint connection status. |
| `PrivateEndpointConnectionService_DeletePrivateEndpointConnection` | DELETE | `/tidbs/{tidbId}/privateEndpointConnections/{connectionId}` | Destructive private endpoint connection cleanup; require pre/post verification. |
| `TidbService_GetCloudProviderInfo` | GET | `/tidbs/{tidbId}/cloudProviderInfo` | Read-only provider details. |
| `TidbService_ListTidbBackups` | GET | `/tidbs/{tidbId}/backups` | Read-only backup list. |
| `TidbService_CreateTidbBackup` | POST | `/tidbs/{tidbId}/backups` | Mutating manual backup creation when supported by target environment. |
| `TidbService_DeleteTidbBackup` | DELETE | `/tidbs/{tidbId}/backups/{backupId}` | Destructive; require pre/post verification. |
| `TidbService_RestoreTidb` | POST | `/tidbs:restore` | Body is `v1beta2RestoreTidbRequest`; supports `validateOnly`. |
| `TidbService_GetRestoreStatus` | GET | `/tidbs/{tidbId}:getRestoreStatus` | Read-only restore progress. |
| `TidbService_GetCaCertificateDownloadUrl` | GET | `/tidbs/{tidbId}/caCertificateUrl` | Read-only CA certificate URL. |
| `BackupService_ListBackups` | GET | `/backups` | Read-only org/project backup list; use filters when available. |
| `BackupService_DeleteBackup` | DELETE | `/backups/{backupId}` | Destructive; many backups are data-safety protected and return 400 until expiration. |
| `BackupService_ListDeletedTidbs` | GET | `/backups:listDeletedTidbs` | Read-only recycle-bin/deleted TiDB list for restore source discovery. |
| `ExportService_ListExports` | GET | `/tidbs/{tidbId}/exports` | Read-only export task list. |
| `ExportService_CreateExport` | POST | `/tidbs/{tidbId}/exports` | Mutating export creation; body carries object storage credentials or role references. |
| `ExportService_GetExport` | GET | `/tidbs/{tidbId}/exports/{exportId}` | Read-only export status lookup. |
| `ExportService_CancelExport` | POST | `/tidbs/{tidbId}/exports/{exportId}:cancel` | Mutating cancellation; check current state first. |
| `ExportService_DeleteExport` | DELETE | `/tidbs/{tidbId}/exports/{exportId}` | Destructive export-task cleanup; require pre/post verification. |
| `DatabaseAuditLogService_GetAuditLogSetting` | GET | `/tidbs/{tidbId}/auditLogSetting` | Read-only audit-log setting lookup. |
| `DatabaseAuditLogService_UpdateAuditLogSetting` | PATCH | `/tidbs/{tidbId}/auditLogSetting` | Mutating audit-log enablement/config update. |
| `DatabaseAuditLogService_ListAuditLogFilterRules` | GET | `/tidbs/{tidbId}/auditLogFilterRules` | Read-only audit-log filter rule list. |
| `DatabaseAuditLogService_CreateAuditLogFilterRule` | POST | `/tidbs/{tidbId}/auditLogFilterRules` | Mutating filter rule creation. |
| `DatabaseAuditLogService_GetAuditLogFilterRule` | GET | `/tidbs/{tidbId}/auditLogFilterRules/{auditLogFilterRuleId}` | Read-only filter rule lookup. |
| `DatabaseAuditLogService_UpdateAuditLogFilterRule` | PATCH | `/tidbs/{tidbId}/auditLogFilterRules/{auditLogFilterRuleId}` | Mutating filter rule update. |
| `DatabaseAuditLogService_DeleteAuditLogFilterRule` | DELETE | `/tidbs/{tidbId}/auditLogFilterRules/{auditLogFilterRuleId}` | Destructive filter rule cleanup; require pre/post verification. |
| `LogRedactionPolicyService_GetLogRedactionPolicy` | GET | `/tidbs/{tidbId}/logRedactionPolicy` | Read-only log redaction policy lookup. |
| `LogRedactionPolicyService_UpdateLogRedactionPolicy` | PATCH | `/tidbs/{tidbId}/logRedactionPolicy` | Mutating log redaction policy update. |
| `CustomerManagedEncryptionKeyService_GetCmekAccessIamPrincipal` | GET | `/cmeks:principal` | Read-only cloud principal discovery for CMEK setup. |
| `CustomerManagedEncryptionKeyService_VerifyCmekAccessIamPrincipal` | POST | `/cmeks:verifyPrincipal` | Validation request for a customer-managed key principal; body includes KMS ARN or equivalent provider key identifier. |
| `CustomerManagedEncryptionKeyService_ListCustomerManagedEncryptionKeys` | GET | `/cmeks` | Read-only CMEK list. |
| `CustomerManagedEncryptionKeyService_GetCustomerManagedEncryptionKey` | GET | `/cmeks/{customerManagedEncryptionKeyId}` | Read-only CMEK lookup. |

## Console API Key Operations

These operations come from the Premium/Essential_V2 console/account HTTP surface rather than the
core TiDB OpenAPI swagger bundle above. Use that surface's environment-specific base URL, not
`TC_OPENAPI_BASE_URL` for core TiDB. They are sensitive because create
responses can return credentials.

| Operation ID | Method | Path appended to console/account base URL | Notes |
| --- | --- | --- | --- |
| `CreateConsoleApiKey` | POST | `/api/v1/orgs/{orgId}/console-apikey/create` | Mutating API key creation; response secret must be captured only in local artifacts. |
| `ListConsoleApiKeys` | GET | `/api/v1/orgs/{orgId}/console-apikeys?cluster_id={tidbId}` | Read-only API key list for one cluster. |
| `UpdateConsoleApiKey` | PUT | `/api/v1/orgs/{orgId}/console-apikey/update` | Mutating role/scope update for an API key. |
| `DeleteConsoleApiKey` | DELETE | `/api/v1/orgs/{orgId}/api_keys/{apiKeyId}` | Destructive API key cleanup; require list-before and list-after verification. |

## Dataflow / CDC Operations

Paths below are already versioned by `dataflow.swagger.json`; append them to the gateway origin, not
to a `/v1beta2` base URL.

| Operation ID | Method | Path | Notes |
| --- | --- | --- | --- |
| `NgGetAdminProfile` | GET | `/api/v1beta2/tidbs/{cluster_id}/adminProfile` | Read-only admin profile needed by dataflow actions. |
| `NgCalChangefeedFee` | POST | `/api/v1beta2/tidbs/{cluster_id}/calChangefeedFee` | Mutating-looking calculation request; body is `ChangefeedServiceCalChangefeedFeeBody`. |
| `ListChangefeedSpecsX` | GET | `/api/v1beta2/tidbs/{cluster_id}/changefeedSpecifications` | Read-only changefeed SKU/spec discovery. |
| `NgListChangefeeds` | GET | `/api/v1beta2/tidbs/{cluster_id}/changefeeds` | Read-only changefeed list. |
| `NgCreateChangefeed` | POST | `/api/v1beta2/tidbs/{cluster_id}/changefeeds` | Mutating; body is `ChangefeedServiceCreateChangefeedBody`. |
| `NgTestChangefeed` | POST | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/test` | Connectivity/test request; can touch external sink credentials. |
| `NgGetChangefeed` | GET | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/{changefeed_id}` | Read-only changefeed lookup. |
| `NgDeleteChangefeed` | DELETE | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/{changefeed_id}` | Destructive; require pre/post verification. |
| `NgGetChangefeedDetail` | GET | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/{changefeed_id}/detail` | Read-only detailed status. |
| `NgGetTiCDCCluster` | GET | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/{changefeed_id}/ticdc_cluster` | Read-only TiCDC backing cluster for a changefeed. |
| `NgEditChangefeed` | POST | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/{changefeed_id}:edit` | Mutating; body is `ChangefeedServiceEditChangefeedBody`. |
| `NgPauseChangefeed` | POST | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/{changefeed_id}:pause` | Mutating state transition; require current-state check first. |
| `NgResumeChangefeed` | POST | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/{changefeed_id}:resume` | Mutating state transition; require current-state check first. |
| `NgScaleChangefeed` | POST | `/api/v1beta2/tidbs/{cluster_id}/changefeeds/{changefeed_id}:scale` | Mutating capacity change; body contains `changefeed_spec`. |
| `NgDescribeSchemaTable` | POST | `/api/v1beta2/tidbs/{cluster_id}/describeSchemaTable` | Metadata read through POST; body is `ChangefeedServiceDescribeSchemaTableBody`. |
| `NgGetEnabledDPFeaturesForCluster` | GET | `/api/v1beta2/tidbs/{cluster_id}/enabledDPFeatures` | Read-only feature discovery. |
| `NgListSinkEndpoints` | GET | `/api/v1beta2/tidbs/{cluster_id}/sinkEndpoints` | Read-only sink endpoint list. |
| `NgCreateSinkEndpoint` | POST | `/api/v1beta2/tidbs/{cluster_id}/sinkEndpoints` | Mutating network resource creation; body is `SinkEndpointServiceCreateSinkEndpointBody`. |
| `NgGetSinkEndpointAuthInfo` | GET | `/api/v1beta2/tidbs/{cluster_id}/sinkEndpoints/authInfo` | Sensitive read; can expose auth material. |
| `NgListSinkAvailabilityZones` | GET | `/api/v1beta2/tidbs/{cluster_id}/sinkEndpoints/availabilityZones` | Read-only AZ discovery. |
| `NgGenerateSinkAdvertisedListener` | POST | `/api/v1beta2/tidbs/{cluster_id}/sinkEndpoints/generateAdvertisedListener` | Helper generation request; body is `SinkEndpointServiceGenerateSinkAdvertisedListenerBody`. |
| `NgValidateSinkAdvertisedListenerDomain` | POST | `/api/v1beta2/tidbs/{cluster_id}/sinkEndpoints/validateAdvertisedListenerDomain` | Validation request; body is `SinkEndpointServiceValidateSinkAdvertisedListenerDomainBody`. |
| `NgGetSinkEndpoint` | GET | `/api/v1beta2/tidbs/{cluster_id}/sinkEndpoints/{sink_endpoint_id}` | Read-only sink endpoint lookup. |
| `NgDeleteSinkEndpoint` | DELETE | `/api/v1beta2/tidbs/{cluster_id}/sinkEndpoints/{sink_endpoint_id}` | Destructive network resource deletion; require pre/post verification. |
| `NgListTiCDCClusters` | GET | `/api/v1beta2/tidbs/{cluster_id}/ticdc_clusters` | Read-only TiCDC cluster list. |

## Dataflow Ops Operations

These `/dataflow/ops/...` operations are operational/internal. Do not execute them from the skill
unless the human explicitly approves the exact cluster/changefeed/TiCDC target and rollback.

| Operation ID | Method | Path | Notes |
| --- | --- | --- | --- |
| `NgPauseClusterChangefeeds` | POST | `/api/v1beta2/dataflow/ops/cluster/{cluster_id}:pauseChangefeeds` | Bulk pause; mutating. |
| `NgResumeClusterChangefeeds` | POST | `/api/v1beta2/dataflow/ops/cluster/{cluster_id}:resumeChangefeeds` | Bulk resume; mutating. |
| `NgUpdateTableFilters` | POST | `/api/v1beta2/dataflow/ops/cluster/{cluster_id}:updateTableFilters` | Bulk table-filter mutation. |
| `NgApplyConfigChanges` | POST | `/api/v1beta2/dataflow/ops/config/apply` | Operational config mutation. |
| `NgListInternalChangefeeds` | GET | `/api/v1beta2/dataflow/ops/internalChangefeeds` | Internal read. |
| `NgGetInternalChangefeed` | GET | `/api/v1beta2/dataflow/ops/internalChangefeeds/{changefeed_id}` | Internal read. |
| `NgOpsPauseChangefeed` | POST | `/api/v1beta2/dataflow/ops/internalChangefeeds/{changefeed_id}:pause` | Internal mutating pause. |
| `NgRestartChangefeed` | POST | `/api/v1beta2/dataflow/ops/internalChangefeeds/{changefeed_id}:restart` | Internal restart. |
| `NgOpsResumeChangefeed` | POST | `/api/v1beta2/dataflow/ops/internalChangefeeds/{changefeed_id}:resume` | Internal mutating resume. |
| `NgGetInternalTiCDCCluster` | GET | `/api/v1beta2/dataflow/ops/internalTiCDCClusters/{ticdc_cluster_id}` | Internal read. |
| `NgRestartTiCDCCluster` | POST | `/api/v1beta2/dataflow/ops/internalTiCDCClusters/{ticdc_cluster_id}:restart` | Internal TiCDC restart. |
| `NgUpdateTiCDCClusterStorage` | POST | `/api/v1beta2/dataflow/ops/storage/apply` | Operational storage mutation. |

## Premium Migration / DM Operations

Paths below are already versioned by `premium_dm.swagger.json`; append them to the gateway origin,
not to a `/v1beta2` base URL.

| Operation ID | Method | Path | Notes |
| --- | --- | --- | --- |
| `CreatePremiumMigrationPrecheck` | POST | `/v1beta2/tidbs/{tidb_id}/premiumMigrationPrechecks` | Mutating precheck creation; body is `PremiumMigrationServiceCreatePremiumMigrationPrecheckBody`. |
| `PremiumMigrationGetPrecheck` | GET | `/v1beta2/tidbs/{tidb_id}/premiumMigrationPrechecks/{precheck_id}` | Read-only precheck lookup. |
| `PremiumMigrationCancelPrecheck` | DELETE | `/v1beta2/tidbs/{tidb_id}/premiumMigrationPrechecks/{precheck_id}` | Mutating cancellation; confirm current status first. |
| `ListPremiumMigrations` | GET | `/v1beta2/tidbs/{tidb_id}/premiumMigrations` | Read-only migration list. |
| `CreatePremiumMigration` | POST | `/v1beta2/tidbs/{tidb_id}/premiumMigrations` | Mutating migration creation; body is `PremiumMigrationServiceCreatePremiumMigrationBody`. |
| `GetPremiumDMSupportedSources` | GET | `/v1beta2/tidbs/{tidb_id}/premiumMigrations/supportedSources` | Read-only supported source discovery. |
| `GetPremiumMigration` | GET | `/v1beta2/tidbs/{tidb_id}/premiumMigrations/{migration_id}` | Read-only migration lookup. |
| `DeletePremiumMigration` | DELETE | `/v1beta2/tidbs/{tidb_id}/premiumMigrations/{migration_id}` | Destructive; require pre/post verification. |
| `PausePremiumMigration` | POST | `/v1beta2/tidbs/{tidb_id}/premiumMigrations/{migration_id}:pause` | Mutating state transition. |
| `ResumePremiumMigration` | POST | `/v1beta2/tidbs/{tidb_id}/premiumMigrations/{migration_id}:resume` | Mutating state transition. |
| `GetPremiumMigrationSourceTables` | POST | `/v1beta2/tidbs/{tidb_id}/premiumMigrations:getSourceTables` | Metadata read through POST; body contains source connection profile. |
| `ValidatePremiumMigrationSourceConn` | POST | `/v1beta2/tidbs/{tidb_id}/premiumMigrations:validateSourceConnection` | Connectivity validation; body contains sensitive source credentials. |
| `ValidatePremiumMigrationMigrationTargetConn` | POST | `/v1beta2/tidbs/{tidb_id}/premiumMigrations:validateTargetConnection` | Connectivity validation; body contains sensitive target credentials. |

## Import Into Operations

Paths below are already versioned by `import_into.swagger.json`; append them to the gateway origin,
not to a `/v1beta2` base URL.

| Operation ID | Method | Path | Notes |
| --- | --- | --- | --- |
| `ListImportIntoTasks` | GET | `/v1beta2/tidbs/{tidbId}/imports` | Read-only import task list. |
| `CreateImportIntoTask` | POST | `/v1beta2/tidbs/{tidbId}/imports` | Mutating import creation; body is `v1beta2ImportIntoTask`. |
| `GetCheckImportSourceTask` | GET | `/v1beta2/tidbs/{tidbId}/imports/checkSourceAsync/{taskId}` | Read-only async source-check status. |
| `GetImportIntoTask` | GET | `/v1beta2/tidbs/{tidbId}/imports/{importId}` | Read-only import task lookup. |
| `CancelImportIntoTask` | POST | `/v1beta2/tidbs/{tidbId}/imports/{importId}:cancel` | Mutating cancellation; confirm current state first. |
| `CheckDatabaseConnectivity` | POST | `/v1beta2/tidbs/{tidbId}/imports:checkDatabaseConnectivity` | Connectivity validation; body contains target database username/password. |
| `CheckImportSourceConnection` | POST | `/v1beta2/tidbs/{tidbId}/imports:checkImportSourceConnection` | Source connection validation; body contains import source credentials. |
| `CheckImportSource` | POST | `/v1beta2/tidbs/{tidbId}/imports:checkSource` | Source metadata validation; body contains import source and optional table metadata. |
| `CreateCheckImportSourceTask` | POST | `/v1beta2/tidbs/{tidbId}/imports:checkSourceAsync` | Async source validation; body contains import source and optional table metadata. |

## Common Bodies

Illustrative `TidbService_CreateTidb` body shape; re-read the current swagger for authoritative fields:

```json
{
  "cloudProvider": "aws",
  "displayName": "example-premium",
  "regionId": "aws-us-west-2",
  "servicePlan": "Premium",
  "minRcu": "10000",
  "maxRcu": "20000"
}
```

Reset root password body:

```json
{
  "rootPassword": "<from secret manager or approved temporary value>"
}
```

Create `TidbService_CreateTidbBackup` body:

```json
{
  "name": "manual-backup-name"
}
```

Restore body shape:

```json
{
  "tidb": {
    "displayName": "restore-target",
    "regionId": "aws-us-west-2",
    "maxRcu": "20000",
    "servicePlan": "Premium"
  },
  "sourceTidbId": "<source-tidb-id>",
  "restoreMode": "SNAPSHOT",
  "backupId": "<backup-id>",
  "validateOnly": true
}
```

Create `NgCreateChangefeed` body minimum shape from `ChangefeedServiceCreateChangefeedBody`:

```json
{
  "changefeed_type": "MYSQL",
  "name": "example-changefeed",
  "mysql_info": {
    "connection": {
      "endpoint": "<sink-host>:3306",
      "username": "<sink-user>",
      "password": "<from secret manager or approved temporary value>"
    }
  }
}
```

Create `NgCreateSinkEndpoint` body minimum shape:

```json
{
  "sink_endpoint": {
    "endpoint_name": "example-sink-endpoint",
    "endpoint_service_name": "<provider-service-name>",
    "provider": "AWS",
    "region": "us-west-2"
  }
}
```

Create `CreatePremiumMigration` or `CreatePremiumMigrationPrecheck` body minimum shape:

```json
{
  "display_name": "example-premium-migration",
  "sources": [
    {
      "source_type": "MYSQL",
      "conn_profile": {
        "conn_type": "PUBLIC",
        "host": "<source-host>",
        "port": 3306,
        "user": "<source-user>",
        "password": "<from secret manager or approved temporary value>"
      }
    }
  ],
  "target": {
    "user": "<target-user>",
    "password": "<from secret manager or approved temporary value>"
  },
  "mode": "ALL",
  "import_mode": "IMPORTMODE_LOGICAL"
}
```

Create `CreateImportIntoTask` body minimum shape. The create schema exposes `username`,
`password`, `name`, and read-only task fields directly; source details are validated through
the source-check operations before create.

```json
{
  "name": "example-import",
  "username": "<target-user>",
  "password": "<from secret manager or approved temporary value>"
}
```

Check S3 import source connection body:

```json
{
  "source": {
    "type": "ENUM_S3",
    "s3": {
      "uri": "s3://example-bucket/path/",
      "authType": "ENUM_ROLE_ARN",
      "roleArn": "<role-arn-if-used>"
    }
  }
}
```

Check OSS import source connection body:

```json
{
  "source": {
    "type": "ENUM_OSS",
    "oss": {
      "uri": "oss://example-bucket/path/",
      "endpoint": "<oss-endpoint>",
      "authType": "ENUM_ACCESS_KEY"
    }
  }
}
```

Do not commit body files containing passwords, TLS cert material, connection strings, or sink endpoint
provider data, object storage source URIs, access keys, SAS tokens, or role ARNs. Prefer placeholders
in reviewed plans and write real secrets only into local run artifacts immediately before execution.

Do not assume examples are sufficient for production. Re-read the current swagger and the target environment contract before a destructive or mutating run.