Manage migrations

GET    https://app.vern.so/api/v1/migrations
GET    https://app.vern.so/api/v1/migrations/{migration_id}
PATCH  https://app.vern.so/api/v1/migrations/{migration_id}
DELETE https://app.vern.so/api/v1/migrations/{migration_id}

These endpoints manage migrations after you’ve created them. They cover every migration in your account, including companies created in the Vern app — an app-created company is addressed by its company id, which the company page shows as Migration ID.

Authentication

Requires an x-api-key header. The key can address every migration in its account; a migration from another account returns 404, never 403. See Authentication.

The migration object

Every endpoint here returns migrations in the same shape:

{
  "id": "c0a8012e-4f1b-4d3a-9b2c-7e6f5a4b3c2d",
  "name": "Acme Corp",
  "external_id": "acme-001",
  "source": "Salesforce",
  "status": "awaiting_approval",
  "templates": [
    { "slug": "contacts", "name": "Contacts" }
  ],
  "archived": false,
  "created_at": "2026-06-19T15:29:40.000Z",
  "url": "https://app.vern.so/companies/open/c0a8012e-4f1b-4d3a-9b2c-7e6f5a4b3c2d"
}

string (uuid)

The migration ID — pass it to every other call.

string

The display name.

string | null

Your own identifier for this customer, or null.

string | null

The source name, or null for a sourceless migration.

string

awaiting_files, ready, awaiting_approval or completed — see Core concepts → Migration. Omitted from list results, because working it out costs several lookups per migration; get the migration to read it.

object[]

The templates that have a sheet in this migration, each { slug, name }.

boolean

true once the migration is archived.

string (date-time)

When the migration was created.

string

Opens the company in the Vern app. /companies/open/{key} also accepts the external_id in place of the id.

List migrations

GET https://app.vern.so/api/v1/migrations

Returns your migrations newest first, a page at a time.

string

Exact match on the migration’s external ID (the one shown on its company page). Alphanumeric, hyphens and underscores, at most 255 characters.

string

Only migrations from this source, by name. A name that matches no source returns an empty page, not a 404.

boolean

default:"false"

Pass true to include archived migrations. By default they’re left out.

integer

default:"50"

Page size, from 1 to 200.

string

The next_cursor from the previous page. Omit it for the first page.

{
  "migrations": [
    {
      "id": "c0a8012e-4f1b-4d3a-9b2c-7e6f5a4b3c2d",
      "name": "Acme Corp",
      "external_id": "acme-001",
      "source": "Salesforce",
      "templates": [{ "slug": "contacts", "name": "Contacts" }],
      "archived": false,
      "created_at": "2026-06-19T15:29:40.000Z",
      "url": "https://app.vern.so/companies/open/c0a8012e-4f1b-4d3a-9b2c-7e6f5a4b3c2d"
    }
  ],
  "next_cursor": "WyIyMDI2LTA2LTE5VDE1OjI5OjQwLjAwMFoiLCJjMGE4MDEyZS0uLi4iXQ"
}

string | null

Pass it as cursor to get the next page. null on the last page. Treat it as opaque.

To page through everything, repeat the call with each next_cursor until it comes back null:

curl "https://app.vern.so/api/v1/migrations?limit=200" \
  -H "x-api-key: $VERN_API_KEY"

curl "https://app.vern.so/api/v1/migrations?limit=200&cursor=$NEXT_CURSOR" \
  -H "x-api-key: $VERN_API_KEY"

To find the migration for one of your customers, filter by external_id:

curl "https://app.vern.so/api/v1/migrations?external_id=acme-001" \
  -H "x-api-key: $VERN_API_KEY"

Get a migration

GET https://app.vern.so/api/v1/migrations/{migration_id}

Returns { "migration": { … } }, including its status. Archived migrations can still be read.

curl https://app.vern.so/api/v1/migrations/c0a8012e-... \
  -H "x-api-key: $VERN_API_KEY"

Update a migration

PATCH https://app.vern.so/api/v1/migrations/{migration_id}

The API version of the app’s Edit company and Add New Sheet. Send only the fields you want to change; any other field is refused with 400.

string

New display name. Must not be blank.

string | null

The source name to bind, or null (or empty) to make the migration sourceless.

string | null

A new external ID, or null to clear it. Alphanumeric, hyphens and underscores, at most 255 characters, and unique among your migrations.

string[]

Template slugs to add. Each one without a sheet gets a new, empty sheet; slugs that already have one are skipped. Templates are never removed this way, because removing one would drop its sheet and data.

Changing source or adding templates is refused with 409 (code: "imports_in_flight") while an import is in progress for the migration — including a preview waiting for approval — because it would change what that import reads from or writes into. Cancel it or let it finish first. name and external_id can always change.

curl -X PATCH https://app.vern.so/api/v1/migrations/c0a8012e-... \
  -H "x-api-key: $VERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corporation", "templates": ["accounts"] }'

200 OK with the updated { "migration": { … } }.

Archive a migration

DELETE https://app.vern.so/api/v1/migrations/{migration_id}

Archives the migration, like Archive in the app. Nothing is deleted:

It drops out of GET /migrations unless you pass include_archived=true.
It stays readable — the migration, its runs, files, preview, thread, session log and knowledge — and exportable.
Anything that changes it is refused with 409 and code: "migration_archived": uploads, runs, answers, credentials, knowledge, source connection, cancelling a run, and PATCH.

{
  "error": "This migration is archived. Restore it from the Archived page in Vern before changing it.",
  "code": "migration_archived"
}

To bring it back, restore it from the Archived page in Vern. There is no restore endpoint. You can’t archive while an import is in progress, including a preview waiting for approval: the request is refused with 409, code: "imports_in_flight", and the runs to cancel first:

{
  "error": "An import is still in progress for this company. Cancel it before archiving.",
  "code": "imports_in_flight",
  "runs": [
    { "id": "d4c3b2a1-...", "status": "awaiting_approval", "updatedAt": "2026-06-19T15:40:02.000Z", "runKind": "generate" }
  ]
}

Archiving an archived migration does nothing and returns the same 200.

curl -X DELETE https://app.vern.so/api/v1/migrations/c0a8012e-... \
  -H "x-api-key: $VERN_API_KEY"

200 OK with the migration, now "archived": true.

Errors

Status	Meaning
`400`	List: a malformed `external_id`, a `limit` outside 1–200, or an invalid `cursor`. PATCH: malformed JSON, no fields, an unknown field, a blank `name`, a malformed `external_id`, `templates` not an array of slugs, or an unknown template slug.
`401`	API key missing or invalid.
`404`	No migration with that `{migration_id}` in your account, or (PATCH) the named `source` doesn’t exist.
`409`	`migration_archived` (PATCH on an archived migration); `imports_in_flight` (archiving, or changing `source`/`templates`, while an import is in progress — the body lists the `runs`); the `external_id` is already used by another migration; the source name is ambiguous; or your account’s region isn’t live yet.
`429`	Listing and getting are Reads (30 / minute); PATCH and DELETE are Writes (30 / minute). Check `Retry-After`. See Rate limits.
`500`	Server error. A PATCH that changed some fields but failed to add the templates says so; retry with just `templates`.

See Errors & limits for the shared error model.

Create a migration
Upload files
Poll a run — including how to cancel one.

Overview

Get started

MCP server

API reference

Reference

Authentication

The migration object

List migrations

Get a migration

Update a migration

Archive a migration

Errors

Next

​Authentication

​The migration object

​List migrations

​Get a migration

​Update a migration

​Archive a migration

​Errors

​Next

Authentication

The migration object

List migrations

Get a migration

Update a migration

Archive a migration

Errors

Next