Skip to content

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.

  • An API key with the scope migrations:read to read and migrations:write to 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"

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.

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_id and at least one wave are required. Each item needs source_username; plan_id, owner_user_id and options (dns_modes per zone, mail_passwords, ftp) are optional.
  • settings is 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, external or source_dns), rollback_days (1–30, default 14) and client_visible.
  • The answer is the migration with its waves and items. Keep the id of the migration as MIGRATION_ID and note the id of each item (ITEM_ID below).

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).

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, completed or cancelled. pause_reason says why a migration paused (for example after a failed account).
  • Item state runs from pending through analyzing, analyzed, provisioning, presync, verifying and ready to cutover, post_verify, completed and finalized; the others are failed, paused, skipped, cancelled and rolled_back. step and progress show the current step.
  • gate says what an item may do now: can_cutover (with cutover_blocker when it cannot), can_rollback, running and ambers_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).

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.

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.

No webhook event is sent for migration progress: poll the migration as in step 3. The event list shows what is sent.