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
{
"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_idis 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.
domainmust be a verified custom domain of the workspace.domainslists 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.
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
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
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
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
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
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
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.
