REST API Client (Headless / Automated Migrations)

📚 Overview & Scope

Endrias Bridge ships a local REST API (migrationbridge api) alongside the desktop wizard. It runs the exact same migration engine — same schema copy, same parallel data copy, same same-engine-family views/procedures/triggers step — just triggered by an HTTP request instead of a button click. There are two ways to drive it:

🔗 Endpoints Reference

✓ Prerequisites

From the desktop app: open the API Client tab, set a port (default 8765), and click Start API Server. The status label turns green (Running on http://localhost:8765) once it responds to a health check — usually under two seconds.

From a terminal (useful for a server/CI box with no GUI at all):

python -m migrationbridge api --port 8765

Once the status label shows Running, you have two equivalent ways to send requests:

• Stay in the desktop app's API Client tab — pick an action from the dropdown, edit the JSON, click Submit Request.
• Click Open /docs (Swagger UI) to launch the full interactive API explorer in your browser — every endpoint, schema, and a "Try it out" button per action.

Select Start Replication — POST /replications from the API Action dropdown. The Request pane pre-fills a template — edit the two connectionString values for your real source and target:

{
  "source": {
    "connectionString": "Data Source=HOST,1433;Initial Catalog=DB;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True",
    "encryptDataInTransit": "True",
    "changeTrackingMethod": "ChangeDataCapture",
    "changeTrackingRetentionPeriod": "3 DAYS"
  },
  "destination": {
    "connectionString": "Data Source=HOST,1433;Initial Catalog=DB;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True",
    "encryptDataInTransit": "True"
  },
  "replicationName": "my-job",
  "replicationMethod": "OneTime",
  "bulkCopyBatchSize": "100000",
  "parallelTablesLimit": "4",
  "pkRangeStreams": "4",
  "replicateTablesOnly": "False",
  "replicateViews": "True",
  "replicateStoredProcedures": "True",
  "replicateLoginsUsersAndRoles": "False",
  "addSourceObjectsToExclusionList": { "tables": "", "views": "", "storedProcedures": "" },
  "addNewTablesToExclusionList": "False",
  "dynamicTablesExclusionRules": "",
  "stagingBufferType": "TempDb"
}

Faster alternative to hand-typing connection strings: the API Client tab has the same Working database picker every other tab uses, fed by the active Migration Project's configured source/target databases. Pick a database pair there, then click Fill from Selected Project to build both connectionString values automatically instead of typing them by hand — only the job-level options (parallelTablesLimit, exclusions, etc.) are left for you to adjust.

changeTrackingMethod is informational only — this endpoint always performs a one-time full seed regardless of what's set here. changeTrackingRetentionPeriod (e.g. "3 DAYS") is applied for real, but not until the stream actually starts: it's carried on the seed job and applied via sp_cdc_change_job when you later call POST /replications/{job_id}/stream (Step 5) — the connecting login needs db_owner on the source for that call to succeed; if it doesn't, the stream still starts, with a warning in its log instead of the retention change. Once the seed job reaches state done, call Step 5 to start continuous CDC streaming for cutover.

Click Submit Request. The Response pane returns immediately with a job_id — the migration itself keeps running in the background:

HTTP 202

{
  "job_id": "b6ac19bf-f16b-48d1-963d-25d7cfff37a8",
  "replicationName": "my-job",
  "resume": false,
  "notes": []
}

Migrating multiple databases in one request

Add a databases list to migrate several databases from the same source server to the same target server in one call — one job is started per database, mirroring what the desktop app's Projects tab does for a batch. When set, the Initial Catalog in both connection strings is ignored and replaced with each name in the list:

{
  "source": {"connectionString": "Data Source=src-host,1433;Initial Catalog=ignored;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True"},
  "destination": {"connectionString": "Data Source=tgt-host,1433;Initial Catalog=ignored;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True"},
  "replicationName": "batch-job",
  "databases": ["Sales", "Inventory", "Billing"]
}

The response returns a map instead of a single ID — poll each one individually with Job Status:

{
  "job_id": null,
  "job_ids": {"Sales": "...", "Inventory": "...", "Billing": "..."},
  "replicationName": "batch-job",
  "resume": false,
  "notes": []
}

Migrating several differently-named databases (separate calls)

The databases list only helps when every database keeps the same name on both source and destination. When source/destination database names don't match per pair — a common real-world shape, e.g. environment-suffixed database names — submit one independent POST /replications call per database instead, each with its own full connection strings:

{
  "source": {"connectionString": "Data Source=src-host,1433;Initial Catalog=db1;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True"},
  "destination": {"connectionString": "Data Source=tgt-host,1433;Initial Catalog=z1;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True"},
  "replicationName": "db1-to-z1"
}
{
  "source": {"connectionString": "Data Source=src-host,1433;Initial Catalog=db2;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True"},
  "destination": {"connectionString": "Data Source=tgt-host,1433;Initial Catalog=z2;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True"},
  "replicationName": "db2-to-z2"
}
{
  "source": {"connectionString": "Data Source=src-host,1433;Initial Catalog=db3;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True"},
  "destination": {"connectionString": "Data Source=tgt-host,1433;Initial Catalog=z3;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True"},
  "replicationName": "db3-to-z3"
}

Each call returns its own independent job_id — track and poll them separately, same as any single-database request. This is also the right pattern when source and destination are the same server pair for every database but you want per-database control over options like replicateTablesOnly or table exclusions, since databases mode applies the same options to every entry in the list.

Copy the job_id from Step 3 into the Job ID field, switch the API Action dropdown to Job Status — GET /jobs/{job_id}, and click Submit Request again — repeat every few seconds until state is done or failed.

Resuming an interrupted job (crash, power loss, closed window)

If the machine running migrationbridge api loses power, the process gets killed, or the window it was running in gets closed, the job dies — but its progress isn't lost. Each table's PK-range checkpoint is written to disk after every committed batch, not held only in memory, so it survives the process itself dying.

1. Start migrationbridge api again (or the desktop app's API Client tab → Start API Server) — the old job_id is gone along with the process; that's expected, checkpoints don't depend on it.
2. Resubmit the exact same request you used originally — same source database name(s), same target host/database — with "resume": true added:

{
  "source": {
    "connectionString": "Data Source=HOST,1433;Initial Catalog=DB;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True",
    "encryptDataInTransit": "True",
    "changeTrackingMethod": "ChangeDataCapture",
    "changeTrackingRetentionPeriod": "3 DAYS"
  },
  "destination": {
    "connectionString": "Data Source=HOST,1433;Initial Catalog=DB;User ID=USER;Password=PASSWORD;Encrypt=True;TrustServerCertificate=True",
    "encryptDataInTransit": "True"
  },
  "replicationName": "my-job",
  "replicationMethod": "OneTime",
  "bulkCopyBatchSize": "100000",
  "parallelTablesLimit": "4",
  "pkRangeStreams": "4",
  "replicateTablesOnly": "False",
  "replicateViews": "True",
  "replicateStoredProcedures": "True",
  "replicateLoginsUsersAndRoles": "False",
  "addSourceObjectsToExclusionList": { "tables": "", "views": "", "storedProcedures": "" },
  "addNewTablesToExclusionList": "False",
  "dynamicTablesExclusionRules": "",
  "stagingBufferType": "TempDb",
  "resume": true
}

The response echoes "resume": true back immediately, so you can confirm at submission time — before waiting for the job to reach done — that it was accepted as a resume rather than silently treated as a fresh start:

{
  "job_id": "9f2a7c1e-...",
  "replicationName": "my-job",
  "resume": true,
  "notes": []
}

This is the same full request you'd use to start the job — every field carries over unchanged, with "resume": true added at the end. source, destination, and replicationName must be byte-for-byte identical to the original submission (see the warning below); the rest of the options don't affect checkpoint lookup and can differ if needed.

In databases batch mode, add "resume": true at the top level alongside "databases": [...] — it applies to every database in the list. Confirm it actually took effect by checking the new job's log for [info] Resuming from checkpoint (rather than [info] Cleared checkpoint file for fresh start, which means it started over).

While a job is running, switch to the desktop app's Migration Health tab — it shows the same live per-table progress dashboard whether the migration was started from the Migrate tab or, like here, the REST API. No extra setup: the dashboard polls the local API server automatically whenever it's running.

The full response includes log (every line the migration engine printed, same content you'd see in the wizard's Migration Log tab) and report (structured per-table results). For a script, the useful check is usually:

import json, urllib.request

with urllib.request.urlopen(f"http://localhost:8765/jobs/{job_id}") as r:
    d = json.load(r)

if d["state"] == "failed":
    errors = [x for x in d["report"]["results"] if x["status"] == "error"]
    raise SystemExit(f"{len(errors)} table(s) failed: {errors}")

Continuous CDC streaming after the seed

Once a seed job reaches state: "done", start continuous CDC streaming for that same source/target pair with POST /replications/{job_id}/stream — no request body needed. This requires CDC enabled on the source tables (EXEC sys.sp_cdc_enable_db, then EXEC sys.sp_cdc_enable_table ... @supports_net_changes = 1 per table — tables without it are skipped and logged, not an error):

curl -X POST http://localhost:8765/replications/<job_id>/stream
# -> {"stream_job_id": "...", "notes": []}

The stream is tracked as its own job — poll GET /jobs/{stream_job_id} the same way, except it stays in state running indefinitely (it doesn't resolve to done on its own). The log shows applied changes as they happen:

CDC: 3 change(s) applied (total 3), rate 0.5/s, LSN 0000002d000006180003

Stop it with DELETE /jobs/{stream_job_id} — but only once lag is at zero, per the cutover procedure below. Stopping earlier means whatever changes hadn't been applied yet are lost, same as stopping the desktop app's CDC Stream early.

To cancel a running job early: select Stop Job — DELETE /jobs/{job_id} with the Job ID filled in, and submit. To shut the server down entirely, click Stop API Server in the desktop app (or Ctrl+C the terminal if you started it from the CLI). Closing the desktop app also stops any server it started, so you don't end up with an orphaned background process.

Switch to the API Logs sub-tab (next to Request) to see every past request: time, method, path, status, and job ID, newest first. Use the DB (Job ID) dropdown to narrow the list to one job, and click a row to see its full redacted request body below the table (passwords always show as ***, even here).

The Retention dropdown controls how long entries are kept — 7, 14, or 28 days, applied immediately to the running server (no restart needed). It defaults to 7 days, or whatever api_log_retention_days is set to in migrationbridge.conf if you want that as the default on every server start instead of picking it each time.

💻 Calling It From a Script (curl)

Everything above works identically from any HTTP client. A full start-and-poll sequence with curl:

\
curl -X POST http://localhost:8765/replications \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"connectionString": "Data Source=src-host,1433;Initial Catalog=MyDB;User ID=sa;Password=***;Encrypt=True;TrustServerCertificate=True"},
    "destination": {"connectionString": "Data Source=tgt-host,1433;Initial Catalog=MyDB;User ID=sa;Password=***;Encrypt=True;TrustServerCertificate=True"},
    "replicationName": "nightly-sync",
    "parallelTablesLimit": "4"
  }'
# -> {"job_id": "...", "replicationName": "nightly-sync", "resume": false, "notes": []}

curl http://localhost:8765/jobs/<job_id>
# -> poll until "state" is "done" or "failed"

⚠ Known Limitations