Migration Workflow And Run APIs
Exodus has three distinct execution surfaces. They work together, but they are not aliases for one another.
| Need | Execution surface | Scope |
|---|---|---|
| Follow Eden's guided Redis-compatible migration sequence | Guided Redis workflow run | /migration-workflows/redis |
| Plan, validate, execute, observe, cut over, or roll back an Exodus migration | Migration record and migration runs | /migrations/{migration} |
| Orchestrate durable application or operator work around a migration | Generic workflow definition and run | /workflows and /workflow-runs |
The guided workflow endpoint is currently Redis-compatible only. Other endpoint families use the broader Exodus migration lifecycle; do not infer unimplemented routes such as /migration-workflows/postgres or /migration-workflows/mongo.
Execution Model
Cross-Engine Exodus Migration Runs
The migration record is the cross-engine lifecycle resource. It is the path for heterogeneous planning, validation runs, data movement, LogAndReplay readiness, cutover preflight, completion, cancellation, and interlay rollback.
| Stage | Read routes | Mutation routes |
|---|---|---|
| Create and inspect | GET /api/v1/migrations, GET /api/v1/migrations/{migration} | POST /api/v1/migrations, DELETE /api/v1/migrations/{migration} when deletion is allowed |
| Attach and configure | GET /api/v1/migrations/{migration} | POST /api/v1/migrations/{migration}/api/{api}, POST /api/v1/migrations/{migration}/interlay/{interlay} |
| Analyze and verify compatibility | GET /analysis/info, GET /compatibility/info | POST /analysis/start, POST /compatibility/start, resolve or acknowledge compatibility issues |
| Plan heterogeneous movement | GET /planning/schema-mapping, GET /planning/request-mapping, GET /planning/query-seeding/status | POST /planning/run, patch mappings, POST /planning/validate, POST /planning/finalize |
| Run validation | GET /test/info, GET /test/runs, GET /test/runs/{run_uuid} | POST /test/runs, POST /test/cancel |
| Execute and observe | GET /live_metrics, GET /write-log/status, GET /live-write-mode/readiness | POST /execution/preflight, POST /migrate, PATCH /traffic, PATCH /live-write-mode |
| Cut over, recover, or finish | GET /api/v1/migrations/{migration} | POST /cutover/preflight, POST /complete, POST /cancel, rollback one or all interlays |
Routes in this table are relative to /api/v1/migrations/{migration} unless a full path is shown. The Migration APIs and Exodus Migration API Stage Map provide the complete request and response details.
Guided Redis Workflow Runs
Use the guided Redis workflow when the migration is Redis-compatible and an operator, dashboard, or supervised agent needs Eden to enforce the standard setup, preparation, approval, execution, and completion sequence.
| Method | Route | Purpose |
|---|---|---|
POST | /api/v1/migration-workflows/redis | Start a guided Redis workflow run. |
GET | /api/v1/migration-workflows/redis | List guided Redis workflow runs. |
GET | /api/v1/migration-workflows/redis/{run_id} | Read the current phase, blocked reason, allowed actions, and linked migration state. |
GET | /api/v1/migration-workflows/redis/{run_id}/events | Stream state changes and heartbeats as server-sent events. |
POST | /api/v1/migration-workflows/redis/{run_id}/setup | Submit source, target, strategy, and approval requirements. |
POST | /api/v1/migration-workflows/redis/{run_id}/target | Submit or provision target details. |
POST | /api/v1/migration-workflows/redis/{run_id}/recommendations | Generate target recommendations. |
POST | /api/v1/migration-workflows/redis/{run_id}/prepare | Resolve endpoints, create the underlying migration, analyze, validate, and prepare approval. |
POST | /api/v1/migration-workflows/redis/{run_id}/approve | Pass the explicit execution approval gate. |
POST | /api/v1/migration-workflows/redis/{run_id}/retry | Retry a recoverable failed step. |
POST | /api/v1/migration-workflows/redis/{run_id}/complete | Complete after target acceptance. |
POST | /api/v1/migration-workflows/redis/{run_id}/cancel | Cancel before completion. |
Durable Workflow Definitions And Runs
Generic workflows can orchestrate pre-migration checks, approvals, notifications, validation follow-up, or post-cutover actions. They do not replace the Exodus migration state machine or bypass its preflight and rollback controls.
| Method | Route | Purpose |
|---|---|---|
POST | /api/v1/workflows | Create a durable workflow definition. |
POST | /api/v1/workflows/{workflow}/runs | Start a workflow run. |
GET | /api/v1/workflow-runs/{run_id} | Inspect a workflow run. |
GET | /api/v1/workflow-runs/{run_id}/steps | Inspect per-step state. |
POST | /api/v1/workflow-runs/{run_id}/cancel | Cancel a workflow run. |
POST | /api/v1/workflow-runs/{run_id}/resume | Resume a paused workflow run. |
POST | /api/v1/workflow-runs/{run_id}/fork | Fork a run for controlled recovery or follow-up work. |
Operating Guidance
- Use a guided Redis workflow when its supported scope matches the migration.
- Use the Exodus migration API for every cross-engine or custom migration lifecycle.
- Use generic workflows only for durable orchestration around the migration; keep actual data movement and cutover decisions on the Exodus migration resource.
- Preserve the migration ID, guided workflow run ID when present, and any generic workflow run IDs in operational evidence and incident records.