content/docs/platform-management-api/reference.mdx

@@ -57,6 +57,8 @@ sunset-headed.
 | `/api/v1/admin/tenants/:slug/{redeploy,reboot,diagnostics,console-output,boot-events,scrub-artifacts}` | Tenant fleet ops | CP admin bearer |
 | `POST /api/v1/admin/tenants/redeploy-fleet` | Fleet rollout | CP admin bearer |
 | `POST /api/v1/admin/workspaces/:id/env` | Force-set workspace env (SSM + restart) | CP admin bearer |
+| `POST /api/v1/admin/workspaces/:id/migrate-provider` | Start cross-cloud workspace compute-provider migration | CP admin bearer |
+| `GET /api/v1/admin/workspaces/:id/migration-status` | Poll migration status | CP admin bearer |
 | `/api/v1/admin/tenants/:slug/migrate-data-volume` | Data-volume migration | CP admin bearer |
 | `/api/v1/admin/{thin-ami,runtime-image}/{promote,list,rollback}` | Image/AMI pins | CP admin bearer |
 | `POST /api/v1/workspaces/provision` (`422 RUNTIME_PIN_MISSING`) | Provision workspace | provision-secret |
@@ -90,12 +92,17 @@ For deeper tenant route tables see
 
 - **CLI** — the `molecule` CLI (Go/cobra). Today it is primarily a
   runtime-bridge; management verbs are being extended and its `runHTTP` path
-  does not yet attach `Authorization` (verify against source). See per-task
-  CLI lines in the [task guides](/docs/platform-management-api/tasks).
+  does not yet attach `Authorization` (verify against source). The
+  `molecule workspace migrate-provider` and `migration-status` commands are
+  **planned but not yet implemented** in current `molecule-cli` main; use the
+  MCP tools or raw HTTP calls until the CLI PR lands. See per-task CLI lines in
+  the [task guides](/docs/platform-management-api/tasks).
 - **MCP** — [MCP Server Setup](/docs/guides/mcp-server-setup). Today's MCP
   server is single-tenant **workspace-ops**; a dedicated org-key-authed
   **management MCP** (org/secret/template/token tools) is planned and will be
-  generated from this same OpenAPI contract.
+  generated from this same OpenAPI contract. The management MCP adds
+  `migrate_workspace_provider` and `get_workspace_migration_status` tools for
+  CP-admin migrations.
 - **Dashboard** — the canonical management surface (AuthKit session +
   `X-Molecule-Org-Slug`), org ops via the `/cp/*` proxy, tenant ops direct.
 

content/docs/platform-management-api/tasks.mdx

@@ -282,6 +282,75 @@ back-compat. Sending neither `budget_limits` nor `budget_limit` is a **400**.
 
 ---
 
+## Migrate a workspace compute provider
+
+Cross-cloud migration moves a workspace's compute from one provider to another
+(AWS ↔ Hetzner ↔ GCP). It is a **CP-admin** operation: the Org API Key cannot
+start a migration. The call is asynchronous; poll `migration-status` until
+`terminal` is `true`.
+
+### Start a migration
+
+```http
+POST https://api.moleculesai.app/api/v1/admin/workspaces/$WORKSPACE_ID/migrate-provider
+Authorization: Bearer $CP_ADMIN_TOKEN
+Content-Type: application/json
+
+{
+  "from": "aws",
+  "to": "hetzner",
+  "from_instance_id": "i-0123456789abcdef0",
+  "confirm": true
+}
+```
+
+Field notes:
+
+- `from` and `to` must differ and be one of `aws`, `hetzner`, `gcp`.
+- `from_instance_id` is required for non-AWS sources; for AWS it can be omitted
+  and resolved from tags.
+- `org_id` and `runtime` are optional hints for non-AWS source resolution.
+- `confirm: true` is **required**; without it the request is rejected.
+
+A `202` response means the migration started:
+
+```json
+{
+  "status": "migration_started",
+  "workspace_id": "...",
+  "from": "aws",
+  "to": "hetzner",
+  "note": "..."
+}
+```
+
+Other notable statuses: `400` (bad/same provider or missing `from_instance_id`),
+`409` (migration already in progress), `503` (migrator not wired in this
+environment).
+
+### Poll migration status
+
+```http
+GET https://api.moleculesai.app/api/v1/admin/workspaces/$WORKSPACE_ID/migration-status
+Authorization: Bearer $CP_ADMIN_TOKEN
+```
+
+Returns:
+
+```json
+{
+  "migration": { "state": "provisioning_target", ... },
+  "terminal": false
+}
+```
+
+Terminal states are `completed`, `failed`, and `rolled_back`.
+
+- **CLI:** planned — `molecule workspace migrate-provider` / `migration-status` are not yet implemented in current `molecule-cli` main. Use the MCP tools or raw HTTP calls until the CLI PR lands.
+- **MCP:** `migrate_workspace_provider` / `get_workspace_migration_status`.
+
+---
+
 ## Other common tasks (quick reference)
 
 | Task | Host | Method · Path | Tier |