openapi: 3.2.0 info: contact: email: support@cockroachlabs.com name: Cockroach Labs Support url: https://support.cockroachlabs.com description: An API for managing CockroachDB Cloud resources title: CockroachDB Cloud Migration Assistant API version: '2026-09-15' servers: - url: https://cockroachlabs.cloud security: - Bearer: [] tags: - name: Migration Assistant paths: /api/v1/clusters/{cluster_id}/migration-assistant: delete: operationId: CockroachCloud_DeleteMigrationAssistant summary: Delete the Migration Assistant for a cluster description: 'Tears down the deployment and returns the assistant in its DELETING status. Can be used by the following roles assigned at the organization, folder or cluster scope: - ORG_ADMIN - CLUSTER_ADMIN' parameters: - name: cluster_id in: path description: The ID of the cluster whose assistant to delete. required: true schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/MigrationAssistant' '400': description: Returned when a request field is invalid. content: application/json: schema: {} '401': description: Returned when the token bearer cannot be authenticated. content: application/json: schema: {} '403': description: Returned when the user does not have permission to access the resource. content: application/json: schema: {} '404': description: Returned when the resource does not exist. content: application/json: schema: {} '500': description: Server error content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Status' tags: - Migration Assistant x-badges: - color: blue label: PREVIEW x-codeSamples: - lang: Shell + Curl source: "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" get: operationId: CockroachCloud_GetMigrationAssistant summary: Get the Migration Assistant for a cluster description: 'Includes the lifecycle status and, while RUNNING, the URL and sign-in credentials for the assistant; treat the response as sensitive. Can be used by the following roles assigned at the organization, folder or cluster scope: - ORG_ADMIN - CLUSTER_ADMIN - CLUSTER_OPERATOR_WRITER' parameters: - name: cluster_id in: path description: The ID of the cluster whose assistant to fetch. required: true schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/MigrationAssistant' '400': description: Returned when a request field is invalid. content: application/json: schema: {} '401': description: Returned when the token bearer cannot be authenticated. content: application/json: schema: {} '403': description: Returned when the user does not have permission to access the resource. content: application/json: schema: {} '404': description: Returned when the resource does not exist. content: application/json: schema: {} '500': description: Server error content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Status' tags: - Migration Assistant x-badges: - color: blue label: PREVIEW x-codeSamples: - lang: Shell + Curl source: "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" post: operationId: CockroachCloud_CreateMigrationAssistant summary: Provision a Migration Assistant for a cluster description: 'The assistant is a per-cluster, dedicated-cluster-only migration tool. Poll GetMigrationAssistant until its status is RUNNING to retrieve the URL and credentials used to sign in, or FAILED to inspect last_error. Can be used by the following roles assigned at the organization, folder or cluster scope: - ORG_ADMIN - CLUSTER_ADMIN' parameters: - name: cluster_id in: path description: The ID of the cluster to deploy the assistant on. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMigrationAssistantBody' responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/MigrationAssistant' '400': description: Returned when a request field is invalid. content: application/json: schema: {} '401': description: Returned when the token bearer cannot be authenticated. content: application/json: schema: {} '403': description: Returned when the user does not have permission to access the resource. content: application/json: schema: {} '404': description: Returned when the resource does not exist. content: application/json: schema: {} '500': description: Server error content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Status' tags: - Migration Assistant x-badges: - color: blue label: PREVIEW x-codeSamples: - lang: Shell + Curl source: "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"cluster_id\":\"9f8e7d6c-5b4a-3210-fedc-ba9876543210\",\"region\":\"us-east1\"}'" /api/v1/clusters/{cluster_id}/migration-assistant/source-ca-cert: delete: operationId: CockroachCloud_DeleteMigrationAssistantSourceCACert summary: Delete the source-database CA certificate for a cluster's Migration Assistant description: 'Reverts the assistant to the system trust roots and returns the deleted certificate bundle. Can be used by the following roles assigned at the organization, folder or cluster scope: - ORG_ADMIN - CLUSTER_ADMIN' parameters: - name: cluster_id in: path description: The ID of the cluster whose source-database CA certificate to delete. required: true schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/MigrationAssistantSourceCACert' '400': description: Returned when a request field is invalid. content: application/json: schema: {} '401': description: Returned when the token bearer cannot be authenticated. content: application/json: schema: {} '403': description: Returned when the user does not have permission to access the resource. content: application/json: schema: {} '404': description: Returned when the resource does not exist. content: application/json: schema: {} '500': description: Server error content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Status' tags: - Migration Assistant x-badges: - color: blue label: PREVIEW x-codeSamples: - lang: Shell + Curl source: "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant/source-ca-cert \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" get: operationId: CockroachCloud_GetMigrationAssistantSourceCACert summary: Get the source-database CA certificate for a cluster's Migration Assistant description: 'Returns the custom CA certificate bundle the assistant trusts when connecting to its source database. Returns an empty bundle when the assistant uses the system trust roots. Can be used by the following roles assigned at the organization, folder or cluster scope: - ORG_ADMIN - CLUSTER_ADMIN - CLUSTER_OPERATOR_WRITER' parameters: - name: cluster_id in: path description: The ID of the cluster whose source-database CA certificate to fetch. required: true schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/MigrationAssistantSourceCACert' '400': description: Returned when a request field is invalid. content: application/json: schema: {} '401': description: Returned when the token bearer cannot be authenticated. content: application/json: schema: {} '403': description: Returned when the user does not have permission to access the resource. content: application/json: schema: {} '404': description: Returned when the resource does not exist. content: application/json: schema: {} '500': description: Server error content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Status' tags: - Migration Assistant x-badges: - color: blue label: PREVIEW x-codeSamples: - lang: Shell + Curl source: "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant/source-ca-cert \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" patch: operationId: CockroachCloud_UpdateMigrationAssistantSourceCACert summary: Update the source-database CA certificate for a cluster's Migration Assistant description: 'Replaces the custom CA certificate bundle the assistant trusts when connecting to its source database. Returns the updated certificate bundle. Can be used by the following roles assigned at the organization, folder or cluster scope: - ORG_ADMIN - CLUSTER_ADMIN' parameters: - name: cluster_id in: path description: The ID of the cluster whose source-database CA certificate to update. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMigrationAssistantSourceCACertBody' responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/MigrationAssistantSourceCACert' '400': description: Returned when a request field is invalid. content: application/json: schema: {} '401': description: Returned when the token bearer cannot be authenticated. content: application/json: schema: {} '403': description: Returned when the user does not have permission to access the resource. content: application/json: schema: {} '404': description: Returned when the resource does not exist. content: application/json: schema: {} '500': description: Server error content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Status' tags: - Migration Assistant x-badges: - color: blue label: PREVIEW x-codeSamples: - lang: Shell + Curl source: "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant/source-ca-cert \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"cluster_id\":\"9f8e7d6c-5b4a-3210-fedc-ba9876543210\",\"x509_pem_cert\":\"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\"}'" components: schemas: Any: description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nIn its binary encoding, an `Any` is an ordinary message; but in other wire\nforms like JSON, it has a special encoding. The format of the type URL is\ndescribed on the `type_url` field.\n\nProtobuf APIs provide utilities to interact with `Any` values:\n\n- A 'pack' operation accepts a message and constructs a generic `Any` wrapper\n around it.\n- An 'unpack' operation reads the content of an `Any` message, either into an\n existing message or a new one. Unpack operations must check the type of the\n value they unpack against the declared `type_url`.\n- An 'is' operation decides whether an `Any` contains a message of the given\n type, i.e. whether it can 'unpack' that type.\n\nThe JSON format representation of an `Any` follows one of these cases:\n\n- For types without special-cased JSON encodings, the JSON format\n representation of the `Any` is the same as that of the message, with an\n additional `@type` field which contains the type URL.\n- For types with special-cased JSON encodings (typically called 'well-known'\n types, listed in https://protobuf.dev/programming-guides/json/#any), the\n JSON format representation has a key `@type` which contains the type URL\n and a key `value` which contains the JSON-serialized value.\n\nThe text format representation of an `Any` is like a message with one field\nwhose name is the type URL in brackets. For example, an `Any` containing a\n`foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`." type: object properties: '@type': description: 'Identifies the type of the serialized Protobuf message with a URI reference consisting of a prefix ending in a slash and the fully-qualified type name. Example: type.googleapis.com/google.protobuf.StringValue This string must contain at least one `/` character, and the content after the last `/` must be the fully-qualified name of the type in canonical form, without a leading dot. Do not write a scheme on these URI references so that clients do not attempt to contact them. The prefix is arbitrary and Protobuf implementations are expected to simply strip off everything up to and including the last `/` to identify the type. `type.googleapis.com/` is a common default prefix that some legacy implementations require. This prefix does not indicate the origin of the type, and URIs containing it are not expected to respond to any requests. All type URL strings must be legal URI references with the additional restriction (for the text format) that the content of the reference must consist only of alphanumeric characters, percent-encoded escapes, and characters in the following set (not including the outer backticks): `/-.~_!$&()*+,;=`. Despite our allowing percent encodings, implementations should not unescape them to prevent confusion with existing parsers. For example, `type.googleapis.com%2FFoo` should be rejected. In the original design of `Any`, the possibility of launching a type resolution service at these type URLs was considered but Protobuf never implemented one and considers contacting these URLs to be problematic and a potential security issue. Do not attempt to contact type URLs.' type: string additionalProperties: {} Status: type: object properties: code: type: integer format: int32 details: type: array items: $ref: '#/components/schemas/Any' message: type: string MigrationAssistantHealth.Type: description: " - NOT_COMPUTED: Health is not computed; the assistant is not RUNNING.\n - HEALTHY: The assistant is ready and serving.\n - UNAVAILABLE: The assistant is RUNNING but not currently serving. This is usually\ntransient (for example, its pod is restarting); retry shortly.\n - UNKNOWN: The live health probe could not be reached, so serving health is not\nknown. This is usually transient; retry shortly." type: string enum: - NOT_COMPUTED - HEALTHY - UNAVAILABLE - UNKNOWN UpdateMigrationAssistantSourceCACertBody: description: 'UpdateMigrationAssistantSourceCACertRequest replaces the source-database CA certificate bundle for a cluster''s Migration Assistant.' type: object properties: x509_pem_cert: description: The PEM-encoded X.509 CA certificate bundle to apply. type: string example: cluster_id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210 x509_pem_cert: '-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----' required: - x509_pem_cert title: UpdateMigrationAssistantSourceCACertRequest CreateMigrationAssistantBody: description: CreateMigrationAssistantRequest provisions a Migration Assistant on a cluster. type: object properties: region: description: 'The cluster region to deploy into. Optional; empty selects a default region (the cluster''s first region ordered by locality, which is not necessarily its original primary region). Must be one of the cluster''s existing regions. The chosen region is reported as the assistant''s deployed_region.' type: string example: cluster_id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210 region: us-east1 title: CreateMigrationAssistantRequest MigrationAssistantStatus.Type: description: " - PENDING: The assistant has been requested and is being provisioned.\n - RUNNING: The assistant is ready; its URL and credentials are available.\n - DELETING: Deletion has been requested and is in progress.\n - FAILED: A provisioning or deletion operation failed; see last_error." type: string enum: - PENDING - RUNNING - DELETING - FAILED MigrationAssistantSourceCACert: description: 'MigrationAssistantSourceCACert is the CA certificate bundle a Migration Assistant trusts when connecting to its source database.' type: object properties: x509_pem_cert: description: The PEM-encoded X.509 CA certificate bundle. type: string example: x509_pem_cert: '-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----' title: MigrationAssistantSourceCACert MigrationAssistant: description: 'MigrationAssistant is a per-cluster migration assistant deployment. The url, username, password, and bucket_grantee are populated only while the status is RUNNING. The last_error is populated only when the status is FAILED.' type: object properties: bucket_grantee: description: 'The cloud-native identity the customer must grant bucket access to; populated when the status is RUNNING. Format depends on the cluster''s cloud (AWS IAM role ARN, GCP service account email, or Azure object ID).' type: string cluster_id: description: The ID of the cluster this assistant is deployed for. type: string created_at: description: Timestamp when the assistant was created. type: string format: date-time deployed_region: description: The cluster region the assistant is deployed in. type: string health: $ref: '#/components/schemas/MigrationAssistantHealth.Type' id: description: The unique ID of the migration assistant. type: string last_error: description: The failure detail; populated when the status is FAILED. type: string password: description: 'The password used to sign in to the assistant; populated when the status is RUNNING.' type: string status: $ref: '#/components/schemas/MigrationAssistantStatus.Type' updated_at: description: Timestamp when the assistant was last updated. type: string format: date-time url: description: The URL used to reach the assistant; populated when the status is RUNNING. type: string username: description: 'The username used to sign in to the assistant; populated when the status is RUNNING.' type: string example: bucket_grantee: arn:aws:iam::123456789012:role/example-role cluster_id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210 created_at: '2026-07-30T18:00:00Z' deployed_region: us-east1 health: HEALTHY id: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d last_error: '' password: example_password status: RUNNING updated_at: '2026-07-30T18:05:00Z' url: https://molt-ai.example.crdb.io username: example_username required: - id - cluster_id - deployed_region - status - created_at - updated_at - health title: MigrationAssistant securitySchemes: Bearer: type: http scheme: bearer externalDocs: description: Use the CockroachDB Cloud API url: https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api.html