Migration

The Migration API brings workloads you deployed to a server by hand — Compose stacks and stray containers — under Synq management. It inspects a server's Docker over SSH, returns the stacks it can adopt, and then creates an Synq services project from the ones you pick. In the dashboard this is the migration wizard; there is no CLI equivalent.

Scan a server

Read-only. Enumerates the server's Docker — Compose stacks plus hand-run containers — reconciles them with any Compose files found on disk, and returns the discovered stack for the wizard to preview. Nothing on the server changes.

POST /api/migration/scan

curl -X POST "$SYNQ_URL/api/migration/scan" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123"}'

On success the response is { "success": true, "stack": … }, where stack describes the discovered Compose stacks and containers that can be adopted.

Adopt discovered services

Creates an Synq services project from the services you selected. The server is re-discovered server-side (the server is the source of truth, not client-sent config), and existing named volumes are reused in place — this records the project only; deploy and cutover are separate steps.

POST /api/migration/adopt

curl -X POST "$SYNQ_URL/api/migration/adopt" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123","projectName":"legacy-stack","serviceNames":["web","worker"]}'

On success the response is { "success": true, … } with the created project's details.

Run a reviewed migration

POST /api/migration/migrate starts the complete migration. Per-service options use the discovered container IDs as keys; legacy service-name keys remain accepted. routesByServiceName accepts an array of routes per service, preserving aliases, listen ports, path prefixes and exact matches. Environment values are saved in the service's production environment scope.

When routes are selected, migration prepares the target edge before changing source containers. If another proxy must be replaced, the run waits for consent. Read pendingPrompt from GET /api/migration/migrations/:id (also included in the stream snapshot), then answer it with:

POST /api/migration/migrations/:id/respond
Content-Type: application/json

{"promptId":"<pendingPrompt.promptId>","action":"migrate"}

Use an action ID from the current prompt. An expired, already answered or invalid prompt returns 409. Answering requires write access to both migration servers. Cancelling keeps the original proxy and source containers intact. After attachment or deployment, Synq applies the owned routes and retries pending domain verification; unresolved routing failures remain visible on the run.

Errors

Operations