Execute migration

POST https://app.speybooks.com/api/v1/migrations/{id}/execute

Execute a validated migration, atomically importing all data into SpeyBooks. This operation is irreversible.

Prerequisites

Migration must be in ready_to_execute status. Call /validate first to ensure all gates pass.

Idempotency

If the migration is already completed, returns the existing reconciliation proof without re-executing. This makes the endpoint safe to retry on network failures.

On Success

  • Status advances to completed
  • reconciliation proof is stored (debits, credits, net)
  • completed_at timestamp is set

On Failure

Returns 422 with the specific error. The migration remains in ready_to_execute and can be retried after fixing the underlying issue.

Error responses:

  • 404 { code: "not_found" } — migration not found
  • 422 { code: "INVALID_TRANSITION" } — not in ready_to_execute status
  • 422 — execution failed (error details in response)

Path parameters

id string required
Migration ID (e.g. mig_1). Must be in ready_to_execute status.

Response

200 Migration executed and sealed. Returns reconciliation proof. Idempotent if already completed.
Show response fields
migrationId string
reconciliation object
Show child attributes
net integer
totalCredits integer
totalDebits integer
status string

Error codes

400 Invalid migration ID format.
404 Migration not found.
422 Migration is not in ready_to_execute status, or execution failed validation.