Drive a cPanel migration
Add a cPanel source, plan a migration in waves, start it, follow each account and cut it over or roll it back through the API.
This guide shows how to run a cPanel/WHM migration with the API: connect a source, create a migration, start it, follow it and switch each account over. It covers the same steps as Migration Center in the panel. Migrations are available to administrators and resellers; a reseller sees and migrates only their own accounts.
What you need
Section titled “What you need”- An API key with the scope
migrations:readto read andmigrations:writeto change anything (scopes). - The destination server id (
GET /api/v1/servers), a server whose agent has the migration engine. - Access to the source: a WHM API token, root SSH (password or key) or a cpmove archive. The credentials are stored encrypted, never returned by the API, and destroyed when the migrations that use the source end.
- A plan id for the accounts you create (
GET /api/v1/plans). Without one, the organization’s default plan is used.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export SERVER_ID="3a3a3a3a-1111-4222-8333-444455556666"
1. Add and confirm the source
Section titled “1. Add and confirm the source”POST /api/v1/migration-sources adds a source. For a WHM source give the host, the API token and the server
whose agent probes it (probe_server_id, usually the destination). kind is whm, ssh or archive; the
port defaults to 2087 for WHM and 22 for SSH, and the user to root.
curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-sources" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"kind": "whm", "name": "old-cpanel", "host": "whm.old-host.example", "token": "'"$WHM_TOKEN"'", "probe_server_id": "'"$SERVER_ID"'"}'
The first probe only observes the source’s identity, so the answer has "status": "awaiting_confirmation"
and a fingerprint (of the SSH host key or the WHM certificate). Keep the source’s id as SOURCE_ID. Compare it with the real one yourself, then
confirm exactly that value:
curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-sources/$SOURCE_ID/confirm" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
-d '{"fingerprint": "SHA256:…"}'
The full probe starts. Read GET /api/v1/migration-sources/{id} until status is ready; accounts then lists
the cPanel accounts (user, domain, disk_bytes, suspended). A status of error comes with an
error_code; POST …/probe tries again.
For an archive source, give archive_url (an HTTPS link) or upload the file first: POST /api/v1/migration-sources/upload
with {"filename": "…", "size": …} answers a temporary upload URL (valid for one hour); send the file to it
with PUT, carrying the headers of the answer, then create the source with kind: "archive" and the returned object as archive_object.
2. Create the migration
Section titled “2. Create the migration”POST /api/v1/migrations creates a draft: a source, a destination server and the accounts, in ordered waves.
curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migrations" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Autumn move",
"source_id": "'"$SOURCE_ID"'",
"server_id": "'"$SERVER_ID"'",
"waves": [
{"name": "Pilot", "items": [{"source_username": "shopuser"}]},
{"name": "The rest", "items": [{"source_username": "blog"}, {"source_username": "docs"}]}
],
"settings": {"parallelism": 2, "rollback_days": 14, "dns_mode_default": "external"}
}'
name,source_id,server_idand at least one wave are required. Each item needssource_username;plan_id,owner_user_idandoptions(dns_modesper zone,mail_passwords,ftp) are optional.settingsis optional too. The ones worth knowing:parallelism(1–10),auto_pause(stop at the first failed account),auto_cutover,windows(when the heavy steps may run),dns_mode_default(pluspanel_ns,externalorsource_dns),rollback_days(1–30, default 14) andclient_visible.- The answer is the migration with its waves and items. Keep the
idof the migration asMIGRATION_IDand note theidof each item (ITEM_IDbelow).
PATCH /api/v1/migrations/{id} changes the settings and the waves, also while the migration runs (only items that have not started can still move); a completed or cancelled migration refuses it. A draft can also be deleted.
To see what would move before anything is copied, analyze an item with POST /api/v1/migration-items/{id}/analyze and read
GET /api/v1/migration-items/{id}/preflight (format is md, pdf or json).
3. Start and follow it
Section titled “3. Start and follow it”curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migrations/$MIGRATION_ID/start" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Idempotency-Key: $(uuidgen)"
PlusPanel then analyzes, provisions, copies and verifies the accounts wave by wave. Follow it with
GET /api/v1/migrations/{id}:
curl -fsS "$PLUSPANEL_URL/api/v1/migrations/$MIGRATION_ID" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" \
| jq '{status, current_wave, pause_reason, items: [.waves[].items[] | {id, source_username, state, step, gate}]}'
- Migration
status:draft,running,paused,completedorcancelled.pause_reasonsays why a migration paused (for example after a failed account). - Item
stateruns frompendingthroughanalyzing,analyzed,provisioning,presync,verifyingandreadytocutover,post_verify,completedandfinalized; the others arefailed,paused,skipped,cancelledandrolled_back.stepandprogressshow the current step. gatesays what an item may do now:can_cutover(withcutover_blockerwhen it cannot),can_rollback,runningandambers_acked.
GET /api/v1/migration-items/{id} adds the pre-flight plan, what provisioning created, the DNS state per domain
and the preview host names; …/checks lists the verification checks and …/steps the timeline.
pause, resume and cancel on /api/v1/migrations/{id} control the whole migration. GET /api/v1/migrations/{id}/report
gives the aggregate report (format is md, pdf or json).
4. Cut an account over, or roll it back
Section titled “4. Cut an account over, or roll it back”When an item is ready and its gate.can_cutover is true, switch it over:
curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-items/$ITEM_ID/cutover" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Idempotency-Key: $(uuidgen)"
The cutover makes a last sync, moves the DNS of each domain as the item’s DNS mode says, then verifies the
result. A red check blocks the cutover. Amber checks need POST …/ack-ambers first (an optional reason is
kept in the audit log). Read GET …/dns for the instructions you must apply yourself in external mode, and
POST …/dns/check to check propagation now.
Within the rollback window, POST /api/v1/migration-items/{id}/rollback returns the DNS to the source; the
destination account stays. Other item actions: presync (a new delta sync), verify, retry (after a
failure) and skip.
Errors
Section titled “Errors”| Status | Code | Meaning |
|---|---|---|
401 |
invalid_api_key |
The key is missing, expired or revoked. |
403 |
The key has no migrations scope, or the user may not migrate this. |
|
404 |
The source, migration or item does not exist or is not visible to you. | |
409 |
migration_unsupported_agent |
The server’s agent has no migration engine. |
409 |
migration_source_not_ready |
The source is not ready yet. |
409 |
migration_state |
The action does not fit the current state (for example starting twice). |
409 |
migration_running |
An item or migration in progress blocks the change or deletion. |
409 |
migration_red_checks, migration_ambers_unacknowledged |
A cutover is blocked by red checks or by amber checks nobody acknowledged. |
409 |
migration_verify_stale |
The verification is out of date; verify again before the cutover. |
409 |
migration_rollback_expired |
The rollback window of the item is over. |
422 |
migration_invalid_source, migration_fingerprint_mismatch |
The source’s host or credentials are not accepted, or the fingerprint differs from the one observed. |
503 |
migration_vault_unavailable, migration_uploads_unavailable |
Credentials or archive uploads are not available on this installation. |
Errors are problem details: branch on code.
Events
Section titled “Events”No webhook event is sent for migration progress: poll the migration as in step 3. The event list shows what is sent.
Related
Section titled “Related”- Migrate from cPanel/WHM: the rules, the access modes and how an account moves.
- API reference: every
migrationoperation, with its fields. - API conventions: errors, idempotency and ETags.
- Authentication & API keys: scopes and key handling.