Migration APIs

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

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:

http

Authorization: Bearer <token>

Examples assume:

bash

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 Eve to own the normal sequence: create run, collect setup, prepare, run analysis and validation, wait for approval, execute, monitor, and complete.

Create Workflow Run

http

POST /api/v1/migration-workflows/redis

bash

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

http

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

Optional filters include workflow phase. Common phases are:

Phase	Meaning
`setup`	The run exists but still needs source, target, and strategy selections.
`target_provisioning`	Target creation or target details are in progress.
`validation`	Eve is preparing analysis, compatibility, and test inputs.
`awaiting_approval`	The run is ready for a human approval gate.
`executing`	Migration execution is active.
`monitoring`	Execution finished enough to monitor before completion.
`awaiting_completion`	The target can be accepted or the workflow can be cancelled.
`completed`	Workflow completed.
`failed`	Workflow failed and may be retried.
`cancelled`	Workflow was cancelled.

Get Workflow Run

http

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

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.

http

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

This endpoint streams server-sent events.

bash

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

Event names:

Event	Meaning
`snapshot`	Initial workflow state.
`workflow`	Workflow state changed.
`heartbeat`	Keepalive during quiet periods.
`terminal`	Workflow reached `completed`, `failed`, or `cancelled`.

Submit Setup

http

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

bash

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
  }"

Field	Values
`target_choice`	`existing_endpoint`, `provision_new_aws`, `provision_new_azure`, `self_hosted`
`strategy`	`big_bang`, `canary`, `blue_green`
`conflict_policy`	`Replace`, `None`, `Merge`
`data_movement_mode`	`scan`, `bidirectional_unify`
`unify_conflict_resolution`	`newest_write`, `source_wins`, `target_wins`, `manual`
`write_consistency`	`SourceAuthoritative`, `BestEffort`, `TargetAuthoritative`, `BothRequired`

Submit Target Details

http

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

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

bash

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

http

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

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

Prepare Workflow

http

POST /api/v1/migration-workflows/redis/{runId}/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.

bash

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

Approve Workflow

http

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

bash

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

Method	Path	Purpose
`POST`	`/api/v1/migration-workflows/redis/{runId}/retry`	Retry a failed workflow.
`POST`	`/api/v1/migration-workflows/redis/{runId}/complete`	Complete a workflow after target acceptance.
`POST`	`/api/v1/migration-workflows/redis/{runId}/cancel`	Cancel a workflow before completion.

All three accept an empty JSON object:

bash

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 Exodus Migration API Stage Map.

Create Migration

http

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

bash

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": false
  }'

List Migrations

http

GET /api/v1/migrations

bash

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

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

Get Migration

http

GET /api/v1/migrations/{migrationId}

bash

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

Attach API Or Interlay

Migration attachment belongs to Exodus. Use these routes to associate an approved API or an Eve 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 Exodus Migration API Stage Map.

Attach an API:

http

POST /api/v1/migrations/{migrationId}/api/{apiId}

Attach an interlay:

http

POST /api/v1/migrations/{migrationId}/interlay/{interlayId}

bash

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

Method	Path	Purpose
`POST`	`/api/v1/migrations/{migrationId}/analysis/run`	Start or rerun analysis.
`GET`	`/api/v1/migrations/{migrationId}/analysis/info`	Read analysis status.
`GET`	`/api/v1/migrations/{migrationId}/analysis/history`	Read the historical window used by analysis.
`GET`	`/api/v1/migrations/{migrationId}/analysis/timeseries`	Read analysis timeseries.
`PATCH`	`/api/v1/migrations/{migrationId}/analysis/config`	Configure automatic analysis.
`POST`	`/api/v1/migrations/{migrationId}/analysis/stop`	Stop an active analysis run.

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

Compatibility

Method	Path	Purpose
`POST`	`/api/v1/migrations/{migrationId}/compatibility/start`	Start compatibility checks.
`GET`	`/api/v1/migrations/{migrationId}/compatibility/info`	Read issues and check status.
`POST`	`/api/v1/migrations/{migrationId}/compatibility/resolve`	Mark one issue resolved with notes.
`POST`	`/api/v1/migrations/{migrationId}/compatibility/unresolve`	Reopen one issue.
`POST`	`/api/v1/migrations/{migrationId}/compatibility/acknowledge-all`	Acknowledge all unresolved issues.

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

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; Eve discovers source schema and live query shapes first, then operators or agents patch the plan.

Method	Path	Purpose
`POST`	`/api/v1/migrations/{migrationId}/planning/run`	Discover source schema, source keys, query coverage, and planning blockers.
`POST`	`/api/v1/migrations/{migrationId}/planning/validate`	Validate the current schema and request mapping plan without advancing execution.
`POST`	`/api/v1/migrations/{migrationId}/planning/finalize`	Mark planning complete only when schema and request mapping blockers are gone.
`GET`	`/api/v1/migrations/{migrationId}/planning/schema-mapping`	Read the current schema mapping.
`PATCH`	`/api/v1/migrations/{migrationId}/planning/schema-mapping`	Patch schema mapping with a source-key map or full route mapping.
`GET`	`/api/v1/migrations/{migrationId}/planning/schema-mapping/missing`	List unmapped source objects and fields discovered from the source.
`GET`	`/api/v1/migrations/{migrationId}/planning/target-schema-plan`	Preview target objects, fields, primary keys, foreign keys, and index counts generated by the mapping.
`GET`	`/api/v1/migrations/{migrationId}/planning/request-mapping`	Read the request and response mapping plan.
`PATCH`	`/api/v1/migrations/{migrationId}/planning/request-mapping`	Replace the request mapping plan.
`GET`	`/api/v1/migrations/{migrationId}/planning/request-mapping/missing`	List unmapped live writes, reads, procedures, response templates, blocked DDLs, and unsupported query shapes.
`GET`	`/api/v1/migrations/{migrationId}/planning/request-mapping/query/{queryKey}`	Read one request mapping.
`PATCH`	`/api/v1/migrations/{migrationId}/planning/request-mapping/query/{queryKey}`	Patch one request mapping.
`PATCH`	`/api/v1/migrations/{migrationId}/planning/request-mapping/queries`	Patch multiple request mappings in one request.
`GET`	`/api/v1/migrations/{migrationId}/planning/agent`	Read the planning agent configuration.
`PATCH`	`/api/v1/migrations/{migrationId}/planning/agent`	Configure the planning agent used for mapping recommendations.

Query seeding is available when live request analysis is enabled:

Method	Path	Purpose
`POST`	`/api/v1/migrations/{migrationId}/planning/query-seeding/start`	Start a timed window that records normalized live source query shapes.
`GET`	`/api/v1/migrations/{migrationId}/planning/query-seeding/status`	Read seeding progress and query counts.
`GET`	`/api/v1/migrations/{migrationId}/planning/query-seeding/queries`	List discovered source query shapes.
`GET`	`/api/v1/migrations/{migrationId}/planning/query-seeding/queries/{queryKey}`	Read one discovered query shape.

Agent recommendation APIs are available when agent support is enabled:

Method	Path	Purpose
`POST`	`/api/v1/migrations/{migrationId}/planning/agent/recommend`	Recommend schema mappings from discovered source shape.
`POST`	`/api/v1/migrations/{migrationId}/planning/agent/recommend-request-mapping`	Recommend request and response mappings from seeded query shapes.

Testing

Method	Path	Purpose
`GET`	`/api/v1/migrations/{migrationId}/test/info`	Get configured tests and current test status.
`POST`	`/api/v1/migrations/{migrationId}/test`	Create one test definition.
`PATCH`	`/api/v1/migrations/{migrationId}/test/config`	Replace the full suite.
`GET`	`/api/v1/migrations/{migrationId}/test/{testName}`	Get one test status.
`PATCH`	`/api/v1/migrations/{migrationId}/test/{testName}`	Replace one test definition.
`DELETE`	`/api/v1/migrations/{migrationId}/test/{testName}`	Delete one test definition.
`POST`	`/api/v1/migrations/{migrationId}/test/runs`	Start a full run or a named test run.
`GET`	`/api/v1/migrations/{migrationId}/test/runs`	List test run history.
`GET`	`/api/v1/migrations/{migrationId}/test/runs/{runUuid}`	Read one test run.
`GET`	`/api/v1/migrations/{migrationId}/test/runs/{runUuid}/logs?since=0`	Tail run logs.
`POST`	`/api/v1/migrations/{migrationId}/test/cancel`	Cancel active test run.
`GET`	`/api/v1/migrations/{migrationId}/test/logs?since=0`	Back-compatible active log tail.

Start a full test run:

bash

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

Start one named test:

bash

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

Execute Migration

http

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

bash

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, Eve migrates all interlays attached to the migration.

Traffic Controls

Method	Path	Purpose
`PATCH`	`/api/v1/migrations/{migrationId}/traffic`	Adjust canary read percentage.
`PATCH`	`/api/v1/migrations/{migrationId}/toggle`	Toggle blue/green active environment.
`GET`	`/api/v1/migrations/{migrationId}/live-write-mode`	Read the current heterogeneous live-write execution mode.
`GET`	`/api/v1/migrations/{migrationId}/live-write-mode/readiness`	Check whether LogAndReplay is caught up enough to switch to strict dual-write.
`PATCH`	`/api/v1/migrations/{migrationId}/live-write-mode`	Switch a ready LogAndReplay migration to strict dual-write.

Canary example:

bash

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:

bash

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

Method	Path	Purpose
`GET`	`/api/v1/migrations/{migrationId}/live_metrics`	Read runtime migration metrics.
`GET`	`/api/v1/migrations/{migrationId}/error-keys?limit=100`	Read Redis keys that failed migration or need review.
`GET`	`/api/v1/migrations/{migrationId}/write-log/status`	Read LogAndReplay captured, replayed, lag, gap, and high-watermark status.
`GET`	`/api/v1/migrations/{migrationId}/write-log/events?limit=100`	List recent captured write-log events without raw payload bytes.
`GET`	`/api/v1/migrations/{migrationId}/write-log/gaps?limit=100`	List write-log consistency gaps that block replay readiness or cutover.
`GET`	`/api/v1/migrations/{migrationId}/runtime-query-misses?limit=100`	List runtime query misses recorded as consistency gaps.
`POST`	`/api/v1/migrations/{migrationId}/refresh`	Refresh migration state.
`GET`	`/api/v1/migrations/{migrationId}/jobs`	List migration jobs when job tracking is enabled.

Pause, Resume, Complete, Cancel

Method	Path	Purpose
`POST`	`/api/v1/migrations/{migrationId}/pause`	Pause execution.
`POST`	`/api/v1/migrations/{migrationId}/resume`	Resume execution.
`POST`	`/api/v1/migrations/{migrationId}/complete`	Complete migration.
`POST`	`/api/v1/migrations/{migrationId}/cancel`	Cancel migration.
`DELETE`	`/api/v1/migrations/{migrationId}`	Delete migration record when allowed.

Completion example:

bash

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:

http

POST /api/v1/migrations/{migrationId}/interlay/{interlayId}/rollback

Rollback all interlays:

http

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

bash

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
  }'

Last updated: July 10, 2026

Migration APIs

Authentication

Guided Redis Workflow

Create Workflow Run

List Workflow Runs

Get Workflow Run

Subscribe To Workflow Events

Submit Setup

Submit Target Details

Get Recommendations

Prepare Workflow

Approve Workflow

Retry, Complete, Or Cancel Workflow

Raw Migration API

Create Migration

List Migrations

Get Migration

Attach API Or Interlay

Analysis

Compatibility

Heterogeneous Planning

Testing

Execute Migration

Traffic Controls

Runtime Status And Metrics

Pause, Resume, Complete, Cancel

Rollback

Related Guides