Data transfer
Export, review, and import installation or project data.
Team-mode migration
Move a single-user instance into team mode along one of three paths, or reverse it. All four routes require
org admin/owner and refuse (409) unless teamMode === "single_user". See the
cloud connect / migration guide.
Preflight and start (Path A — your own server) share a body:
POST /api/system/migration/startProp
Type
POST /api/system/migration/start-cloud— Path B, migrate to Openship Cloud. Body:{ allowNonEmptyTarget?: boolean }.POST /api/system/migration/start-tunnel— Path C, expose via an edge tunnel. Body:{ slug: string }(required).POST /api/system/migration/switch-back— reverse any of them. Body:{ abandonRemote?: boolean }.
Switch-back cuts teammates off
Reversing to single-user mode revokes teammate access. The remote keeps a copy for a 30-day grace period so you can recover if you change your mind.
Instance and project data transfer
Export the entire instance or a dependency-complete selection of projects and environments. These
routes require instance administrator access (requireInstanceAdmin() plus a handler-level check).
A workspace owner role alone does not grant access to instance credentials.
POST /api/system/data-transfer/exportProp
Type
POST /api/system/data-transfer/importProp
Type
Project imports remap ownership to the active request workspace. They omit instance accounts/settings,
reuse matching server connections, and skip existing projects by default. Overwrite updates matching
project records while preserving destination-only records; shared dependencies are kept unless
overwriteDependencies is explicitly enabled. Source local hosts require an explicit serverMappings
entry (local for a project without a server row). Cloud projects require the same connected cloud
account. A project archive cannot be used with wipe.
Use the chunk-upload endpoints for large files. After uploading, POST { selection } to the session's
preview endpoint. It returns projects, servers, availableServers, row counts, warnings, and
blockers without consuming the upload. POST { mode, passphrase, selection } to
/api/system/data-transfer/import/session/:sessionId/finalize/stream to apply. Validation is repeated
inside the import transaction. A failed review or password attempt retains the uploaded chunks.
Exports use envelope version 2; imports also accept version 1 instance files. Credentials, deployment snapshots, and inline Compose configuration are encrypted under the transfer password and re-encrypted for the destination. Volume data, source folders, and host TLS files remain on their server.
Loopback server connections require explicit mapping. Backup policies that point at source-local storage or a changed backup host are disabled until the operator verifies the destination storage. Direct transfer supports whole-instance exports; project selections use the file review and import endpoints.
Import limits & errors
The import body is capped at 500 MB (413 PAYLOAD_TOO_LARGE above it). A wrong or missing passphrase
or a malformed file returns 400. Project dependency/mapping conflicts return 409
PROJECT_IMPORT_REQUIRES_REVIEW; whole-instance merge collisions return 409 PK_COLLISION. Select
project scope and explicit overwrite options to resolve project conflicts. A concurrent migration/import
returns 503 BUSY.
Operations
| Operation | REST API |
|---|---|
| Receive one chunk of an authorized direct transfer. | PUT /api/system/data-transfer/direct/chunk/:sessionId/:indexHandler authentication · Self-hosted |
| Finalize a received direct transfer and stream progress. | POST /api/system/data-transfer/direct/chunk/:sessionId/finalize/streamHandler authentication · Self-hosted |
| Keep a direct chunk-transfer session alive. | POST /api/system/data-transfer/direct/chunk/:sessionId/heartbeatHandler authentication · Self-hosted |
| Open a direct chunk-transfer upload. | POST /api/system/data-transfer/direct/chunk/initHandler authentication · Self-hosted |
| Receive a direct instance transfer. | POST /api/system/data-transfer/direct/receiveHandler authentication · Self-hosted |
| Send an instance to an authorized destination. | POST /api/system/data-transfer/direct/sendsettings:admin · Self-hosted |
| Send an instance and stream transfer progress. | POST /api/system/data-transfer/direct/send/streamsettings:admin · Self-hosted |
| Create a direct-transfer session. | POST /api/system/data-transfer/direct/sessionsettings:admin · Self-hosted |
| Export the instance or selected projects (instance administrator). | POST /api/system/data-transfer/exportsettings:admin · Self-hosted |
| Import an export file, ≤500 MB, with scope and conflict options (instance administrator). | POST /api/system/data-transfer/importsettings:admin · Self-hosted |
| Open a chunked file-import session. | POST /api/system/data-transfer/import/sessionsettings:admin · Self-hosted |
| Upload one file-import chunk. | PUT /api/system/data-transfer/import/session/:sessionId/chunk/:indexsettings:admin · Self-hosted |
| Apply a reviewed file import and stream progress. | POST /api/system/data-transfer/import/session/:sessionId/finalize/streamsettings:admin · Self-hosted |
| Preview an uploaded file's selection, conflicts, and server mappings. | POST /api/system/data-transfer/import/session/:sessionId/previewsettings:admin · Self-hosted |
| List exportable projects and instance row counts (instance administrator). | GET /api/system/data-transfer/previewsettings:admin · Self-hosted |
| Preview a project selection and its dependencies (instance administrator). | POST /api/system/data-transfer/previewsettings:admin · Self-hosted |
| Team-migration readiness check (read-only). | POST /api/system/migration/preflightsettings:admin · Self-hosted |
| Migrate single-user → your own remote server. | POST /api/system/migration/startsettings:admin · Self-hosted |
| Migrate → Openship Cloud. | POST /api/system/migration/start-cloudsettings:admin · Self-hosted |
| Expose this instance via an edge tunnel. | POST /api/system/migration/start-tunnelsettings:admin · Self-hosted |
| Reverse a migration back to single-user. | POST /api/system/migration/switch-backsettings:admin · Self-hosted |