All docs

API reference: Migrations

Check a manifest, import it in resumable batches, reconcile counts and checksums, cut over, or roll back.

Updated . 4 min read.

Move short links from another product into your workspace with a manifest. You check it first without writing anything, import it in batches that can be repeated safely, compare counts and checksums, and only then cut over. Nothing at the source is ever changed or deleted, and you can reverse the import without losing anything you have edited since.

Base URL: https://formspring.io/api/v1

Method Path Ability
POST /migrations/dry-run account:write
POST /migrations account:write
GET /migrations/{run} account:read
POST /migrations/{run}/apply account:write
POST /migrations/{run}/reconcile account:write
POST /migrations/{run}/cutover account:write
POST /migrations/{run}/rollback account:write

The token owner must be a workspace owner or administrator. A run from another workspace answers 404.

The manifest

json
{
  "version": 1,
  "source": { "name": "Acme Links", "exported_at": "2026-10-01T00:00:00Z" },
  "domains": ["go.example.com"],
  "entities": {
    "links": [
      { "source_id": "b1", "slug": "promo", "target_url": "https://example.com/promo", "comment": "Autumn", "expires_at": null, "domain": "go.example.com" }
    ]
  }
}
  • source_id is your id for the record, unique within its type. It is what makes a repeated import safe.
  • Supported types today: links. Anything else is listed as unsupported and never imported.
  • A manifest holds up to 5,000 records. Split bigger moves into several runs.
  • domain must be a verified custom domain of the workspace. domains lists hostnames to check ahead of the cutover.

A scripted move

Every step can be repeated, so a script that was interrupted runs the same call again.

bash
BASE=https://formspring.io/api/v1
AUTH="Authorization: Bearer $FORMSPRING_TOKEN"

curl -s -H "$AUTH" -H 'Content-Type: application/json' -d @manifest.json $BASE/migrations/dry-run   # nothing is written
RUN=$(curl -s -H "$AUTH" -H 'Content-Type: application/json' -d @manifest.json $BASE/migrations | jq -r .data.id)
curl -s -X POST -H "$AUTH" $BASE/migrations/$RUN/apply                                               # run again after an interruption
curl -s -H "$AUTH" $BASE/migrations/$RUN                                                             # progress and unresolved records
curl -s -X POST -H "$AUTH" $BASE/migrations/$RUN/reconcile
curl -s -X POST -H "$AUTH" $BASE/migrations/$RUN/cutover

1. Dry run

http
POST /migrations/dry-run

Returns, per type, how many records are ready and how many are not, a checksum of the source records, the records that cannot be imported with reason codes, and a status for each domain. Nothing is written.

Reason codes for links: slug_taken, slug_reserved, slug_blocked, invalid_slug, invalid_target_url, unsafe_target_url, already_expired, domain_not_verified, duplicate_slug_in_manifest, plan_limit_reached. Domain statuses: available, verified, pending_verification, unavailable, invalid. Each domain also carries a next_step.

2. Record the run

http
POST /migrations

Returns 201 with the run. Sending the same manifest again while the run is still open returns that run with 200.

3. Import, and resume

http
POST /migrations/{run}/apply

Returns 202; the import runs in batches on the queue. If a worker stops or the run ends interrupted, call it again: it continues where the ledger says it stopped, never creates a record twice, and keeps the unresolved ones listed under unresolved on GET /migrations/{run}. A record that cannot be imported (for example a slug that is already taken) is never overwritten or renamed.

4. Reconcile

http
POST /migrations/{run}/reconcile

Compares the manifest with what the workspace holds now, per type: source, imported, unresolved, pending, missing, drifted, and a checksum of each side. A run is balanced only when nothing is pending, missing or changed since the import.

5. Cut over

http
POST /migrations/{run}/cutover
{ "accept_unresolved": false }

Allowed only when the run reconciles. Records that stayed unresolved need "accept_unresolved": true. Otherwise 409 with error.code of not_reconciled or unresolved_mappings.

Roll back

http
POST /migrations/{run}/rollback

Returns 202; the reversal runs on the queue. It reverses only what this run created. A link that was edited after the import (modified) or that has recorded clicks (has_activity) is kept and reported, so nothing of value is lost, and links that existed before are never touched. Reversed links stop redirecting but are kept, so they can be restored. Repeating the call finishes what is left. It is available until the run is rolled back, including after the cutover.

Errors

409 carries error.code: not_importable, not_reconcilable, not_ready, not_reconciled, unresolved_mappings or not_reversible. 422 lists what is wrong with the manifest.