Migration APIs

This reference covers the API surfaces used to run and operate migrations in Gateway.

There are two layers:

• Guided Redis workflow API: recommended for operators, dashboards, and supervised agents. It owns sequencing and reduces the chance of running steps out of order.
• Raw migration API: lower-level migration record, analysis, compatibility, testing, traffic, rollback, and completion controls.

All paths below are shown with the generated /api/v1 prefix.

Authentication

Most calls require:

Authorization: Bearer <token>

Examples assume:

export EDEN=http://localhost:8000/api/v1
export AUTH_HEADER="Authorization: Bearer $TOKEN"

Guided Redis Workflow

The guided workflow currently targets Redis-compatible migrations. Use it when you want Gateway to own the normal sequence: create run, collect setup, prepare, run analysis and validation, wait for approval, execute, monitor, and complete.

Create Workflow Run

POST /api/v1/migration-workflows/redis

curl -sS -X POST "$EDEN/migration-workflows/redis" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{}'

The response includes run.id. Store it as RUN_ID.

List Workflow Runs

GET /api/v1/migration-workflows/redis?limit=20

Optional filters include workflow phase. Common phases are:

Get Workflow Run

GET /api/v1/migration-workflows/redis/{run_id}

Use this for polling, recovery, and UI refreshes. The response includes current phase, source/target endpoint ids, interlay id, lower-level migration id, step results, blocked reason when present, and allowed actions.

Subscribe To Workflow Events

GET /api/v1/migration-workflows/redis/{run_id}/events

This endpoint streams server-sent events.

curl -N "$EDEN/migration-workflows/redis/$RUN_ID/events" \
  -H "$AUTH_HEADER"

Event names:

Submit Setup

POST /api/v1/migration-workflows/redis/{run_id}/setup

curl -sS -X POST "$EDEN/migration-workflows/redis/$RUN_ID/setup" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d "{
    \"source_endpoint_uuid\": \"$SOURCE_ENDPOINT_UUID\",
    \"target_choice\": \"existing_endpoint\",
    \"target_endpoint_uuid\": \"$TARGET_ENDPOINT_UUID\",
    \"strategy\": \"blue_green\",
    \"conflict_policy\": \"Replace\",
    \"data_movement_mode\": \"scan\",
    \"unify_conflict_resolution\": \"newest_write\",
    \"write_consistency\": \"SourceAuthoritative\",
    \"preserve_ttl\": true,
    \"require_manual_approval\": true
  }"

Submit Target Details

POST /api/v1/migration-workflows/redis/{run_id}/target

Use this when target_choice requires a target to be provisioned or described.

curl -sS -X POST "$EDEN/migration-workflows/redis/$RUN_ID/target" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "cloud_provider": "aws_elasticache",
    "instance_type": "cache.m7g.large",
    "region": "us-east-1"
  }'

Cloud provider values include aws_elasticache, azure_cache_for_redis, and self_hosted.

Get Recommendations

POST /api/v1/migration-workflows/redis/{run_id}/recommendations

Returns target recommendations based on available workload analysis and endpoint metadata.

Prepare Workflow

POST /api/v1/migration-workflows/redis/{run_id}/prepare

Prepare resolves endpoints, prepares the interlay, creates the lower-level migration record, runs analysis, compatibility checks, and validation tests, then moves the workflow to either awaiting_approval or execution depending on setup.

curl -sS -X POST "$EDEN/migration-workflows/redis/$RUN_ID/prepare" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{}'

Approve Workflow

POST /api/v1/migration-workflows/redis/{run_id}/approve

curl -sS -X POST "$EDEN/migration-workflows/redis/$RUN_ID/approve" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{}'

Only approve after compatibility issues, validation results, rollback ownership, and monitoring have been reviewed.

Retry, Complete, Or Cancel Workflow

All three accept an empty JSON object:

curl -sS -X POST "$EDEN/migration-workflows/redis/$RUN_ID/complete" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{}'

Raw Migration API

The raw migration API is useful when building a custom dashboard or when debugging a guided workflow. It does not protect you from running steps in the wrong order.

For the stage-by-stage operator flow, including planning, execution preflight, live-write mode readiness, and cutover preflight, see Live Migration API Stage Map.

Create Migration

POST /api/v1/migrations
Content-Type: application/json
Authorization: Bearer <token>

curl -sS -X POST "$EDEN/migrations" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "redis-bluegreen",
    "description": "Redis source to target migration",
    "strategy": {
      "type": "blue_green",
      "active_is_new": false,
      "write_mode": {
        "mode": "dual_write",
        "policy": "SourceAuthoritative"
      }
    },
    "data": {
      "Snapshot": {
        "replace": "Replace"
      }
    },
    "preserve_ttl": true,
    "skip_testing": false
  }'

skip_analysis:true is rejected. Use the governed migration-stage API after creation when an eligible advisory analysis result requires an audited operator decision.

List Migrations

GET /api/v1/migrations

curl -sS "$EDEN/migrations" \
  -H "$AUTH_HEADER"

Add X-Eden-Verbose: true for expanded details.

Get Migration

GET /api/v1/migrations/{migration_id}

curl -sS "$EDEN/migrations/$MIGRATION_ID" \
  -H "$AUTH_HEADER"

Attach API Or Interlay

Migration attachment belongs to Live Migrations. Use these routes to associate an approved API or an Gateway interlay with the migration record before execution; do not configure migration lifecycle through the Interlays API.

An interlay can be attached to one active migration at a time. Complete, cancel, or roll back its current association before attaching it to another migration. For the complete operator sequence, see Live Migration API Stage Map.

Attach an API:

POST /api/v1/migrations/{migration_id}/api/{api_id}

Attach an interlay:

POST /api/v1/migrations/{migration_id}/interlay/{interlay_id}

curl -sS -X POST "$EDEN/migrations/$MIGRATION_ID/interlay/$INTERLAY_UUID" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d "{
    \"target_endpoint\": \"$TARGET_ENDPOINT_UUID\"
  }"

Analysis

Analysis requires enough interlay traffic and Redis poll metrics to represent the workload.

Compatibility

Redis checks include version, DUMP/RESTORE compatibility, module mismatch warnings, ACL/write permission checks, and cluster topology checks.

Guided workflow retries reuse the current completed compatibility generation and do not refresh it automatically. This means an acknowledgement remains effective on retry. An explicit compatibility/start refresh preserves earlier snapshots and carries a disposition only when the finding fingerprint and policy semantics are unchanged; new, changed, removed-then-reintroduced, or expired findings remain blocking.

Failed refresh attempts remain in raw history and consume generation numbers, but they do not become disposition sources. The next successful refresh reconciles against the latest earlier successfully completed generation, so a transient check failure does not erase a still-matching acknowledgement.

compatibility/info exposes the snapshot revision, raw and disposition generations, is_latest_generation, generation_order_trusted, policy/check versions, and issue fingerprints. Raw generations are allocated atomically per migration, stored in a unique indexed database column, and are the only ordering authority; service host timestamps and response list position do not determine which result is current. Pre-generation rows remain visible after upgrade but are marked generation_order_trusted:false; they cannot authorize execution, disposition mutation or carry-forward, workflow reuse, or Redis topology. An explicit compatibility refresh creates the first trusted generation. If an untrusted row remains running or not_started, refresh atomically marks it failed and durably superseded before inserting the trusted row. The service logs each actual row transition from the allocator transaction with migration and compatibility UUIDs, generation/trust, status, revision and fence before/after, and the decision; it does not infer a transition from the latest history row. At most 64 transitions are allowed per refresh, and exceeding that bound rolls the allocator transaction back before any compatibility row changes. PostgreSQL and embedded Turso enforce the superseded marker with a trigger, so current CAS writers and old UUID-only writers are rejected after supersession and after restart. The old worker observes a database write failure; the preserved superseded row and the trusted generation remain the recovery authority. observed_status and observed_issues are immutable; effective_status, effective_dispositions, and issues show the current disposition projection. Send the latest successfully completed trusted compatibility_uuid and its expected_revision with compatibility/resolve or compatibility/unresolve to detect stale clients; historical, failed, and untrusted snapshots cannot be mutated. Concurrent updates—and disposition writes attempted while a refresh is running—return 409 Conflict instead of overwriting a decision. An exact retry is idempotent and can repair a migration-status projection without replacing the original audit decision. Bulk acknowledgement is all-or-nothing and rejects the entire request when any blocking finding lacks the explicit safe accept_risk option, is expired, or is malformed. Execution preflight and /migrate recheck the latest effective generation, so an untrusted/running/failed refresh, unhandled finding, or expired disposition cannot execute from a stale Ready state; /migrate also repairs a stale pre-execution status from the durable effective result before data movement.

Heterogeneous Planning

Heterogeneous migrations require a finalized schema mapping and request mapping plan before execution. The migration constructor intentionally does not accept the final mapping; Gateway discovers source schema and live query shapes first, then operators or agents patch the plan.

Query seeding is available when live request analysis is enabled:

Agent recommendation APIs are available when agent support is enabled:

HA Redis Migration Control

HA Redis Cluster migrations use a lane plan so several Eden nodes can own different Redis lanes while moving migration stages together. The HA plan is the authority for lane leases, checkpoints, validation digests, stage barriers, and cutover commitment. DBOS workflow tables may share the same Postgres deployment, but DBOS is a durable driver rather than a second HA stage authority.

Production evidence covers 3, 5, and 7 Eden participants. Forward stage movement requires every configured participant to confirm the identical state digest, even though the HA control plane uses a supermajority threshold for ordinary consensus-control progress.

See HA Redis Cluster Migrations for the deployment contract and examples.

Testing

Start a full test run:

curl -sS -X POST "$EDEN/migrations/$MIGRATION_ID/test/runs" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{}'

Start one named test:

curl -sS -X POST "$EDEN/migrations/$MIGRATION_ID/test/runs" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "test_name": "BatchSmokeTest"
  }'

Execute Migration

POST /api/v1/migrations/{migration_id}/migrate

curl -sS -X POST "$EDEN/migrations/$MIGRATION_ID/migrate" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "interlay_ids": ["redis-live-interlay"],
    "preserve_ttl": true,
    "redis_settings": {
      "enabled": false
    },
    "run_tests": true,
    "require_analysis": true
  }'

If interlay_ids is omitted or empty, Gateway migrates all interlays attached to the migration.

Traffic Controls

Canary example:

curl -sS -X PATCH "$EDEN/migrations/$MIGRATION_ID/traffic" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "read_percentage": 0.25,
    "reason": "Metrics healthy after initial canary."
  }'

Blue/green example:

curl -sS -X PATCH "$EDEN/migrations/$MIGRATION_ID/toggle" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "activate_new": true,
    "reason": "Target validated under live traffic."
  }'

Runtime Status And Metrics

Pause, Resume, Complete, Cancel

Completion example:

curl -sS -X POST "$EDEN/migrations/$MIGRATION_ID/complete" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Target stable after cutover.",
    "force": false
  }'

Rollback

Rollback one interlay:

POST /api/v1/migrations/{migration_id}/interlay/{interlay_id}/rollback

Rollback all interlays:

POST /api/v1/migrations/{migration_id}/interlays/rollback

curl -sS -X POST "$EDEN/migrations/$MIGRATION_ID/interlays/rollback" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Rollback migration.",
    "force": false,
    "preserve_config": true,
    "overwrite_on_reverse": false
  }'

Related Guides

• Live Migrations
• Gateway
• Endpoints