Migration API
Scan a server's existing Docker deployment and adopt the discovered services as an Openship project.
The Migration API brings workloads you deployed to a server by hand — Compose stacks and stray containers —
under Openship management. It inspects a server's Docker over SSH, returns the stacks it can adopt, and then
creates an Openship services project from the ones you pick. In the dashboard this is the migration
wizard; there is no CLI equivalent.
Base path & auth
All paths are relative to your instance, under /api — e.g. https://your-host/api/migration/scan.
Send a personal access token as a bearer header (Authorization: Bearer <token>), created with
openship token create. The dashboard uses your session cookie instead. See the
API overview for the full auth model.
Self-hosted only
This module is mounted only when your instance runs in self-hosted mode — adopting a deployment requires SSH
into a server you manage, which Openship Cloud has no notion of. On a cloud instance these routes are not
mounted and return 404.
Endpoints
| Method & path | Permission | What it does |
|---|---|---|
POST /api/migration/scan | server:write | Inspect a server's Docker and return the adoptable stack — read-only, changes nothing. |
POST /api/migration/adopt | server:write | Create an Openship project from the selected discovered services. |
Both routes take the target serverId in the request body (not the URL). Openship checks that the server
belongs to your organization and that you have server:write on it before doing anything.
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/scanProp
Type
curl -X POST https://your-host/api/migration/scan \
-H "Authorization: Bearer $OPENSHIP_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 Openship 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/adoptProp
Type
curl -X POST https://your-host/api/migration/adopt \
-H "Authorization: Bearer $OPENSHIP_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.
Errors you might see
400 — missing or empty field
serverId is required on both routes; adopt additionally requires a non-empty projectName and at least
one entry in serviceNames. The response body names the missing field.
404 — server not found
The serverId doesn't belong to your organization (or doesn't exist). List your servers with
openship server list to get valid IDs. On a cloud instance the module isn't mounted
at all, so every path here returns 404.
502 — scan or adopt failed
Openship couldn't reach or inspect the server's Docker (SSH unreachable, Docker not running, permission denied), or the adoption failed. The message includes the underlying reason. Confirm the server is online and its Docker is accessible, then retry.
Health API
Public liveness and deployment-info probes for load balancers, Docker health checks, and clients discovering how an instance is configured.
Mail API
Install and adopt an iRedMail stack over SSH, run the mail admin panel (domains, mailboxes, stats, backups, DNS, components), and deploy webmail.