Eden REST API
Migration Workflow And Run APIs
/api/v1Live Migrations 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 Live 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 Live migration lifecycle; do not infer unimplemented routes such as /migration-workflows/postgres or /migration-workflows/mongo.
Execution Model
Cross-Engine Live 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, explicitly refresh with 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 Live Migration API Stage Map provide the complete request and response details.
A guided retry at check_compatibility reuses the highest trusted durable raw generation, including effective acknowledgements. Generation order is database-monotonic and does not depend on service host clocks. History backfilled during an upgrade is marked untrusted, so the workflow requests an explicit fresh compatibility check instead of reusing inferred chronology. An untrusted legacy running or not_started row is not polled as live: the refresh durably supersedes it before allocating the trusted generation. Every changed row emits bounded transition evidence directly from the allocator transaction; if more than 64 legacy rows would change, the allocator fails before changing any compatibility row. PostgreSQL and embedded Turso reject later current-CAS and old UUID-only updates to a superseded row, including after restart; the old worker records a write failure without changing the trusted recovery authority. Ordinary retries never refresh a trusted raw observation implicitly; use the raw compatibility/start route when a new generation is required.
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 Live 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 Live 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 Live migration resource.
- Preserve the migration ID, guided workflow run ID when present, and any generic workflow run IDs in operational evidence and incident records.