> ## Documentation Index > Fetch the complete documentation index at: https://docs.vern.so/llms.txt > Use this file to discover all available pages before exploring further. # Update a migration > The API version of the app's "Edit company" and "Add New Sheet". Send only the fields to change; any other field is a 400. `templates` ADDS templates: each slug without a sheet gets a new, empty one, and slugs that already have one are skipped — templates are never removed. Changing `source` or adding `templates` is refused with 409 (`code: imports_in_flight`) while an import is in progress, including a preview waiting for approval; `name` and `external_id` can always change. ## OpenAPI ````yaml /api-reference/openapi.json patch /migrations/{migration_id} openapi: 3.1.0 info: title: Vern Migration API version: 1.0.0 description: >- Run Vern as a headless migration engine. Create a migration, upload a customer's files, run the managed agent to generate a preview, then execute and export clean data. See the Migration API guides for concepts and walkthroughs. **Rate limits** are counted per account (company), not per key or IP, in four classes: reads 30/minute, writes 30/minute, jobs (starting an export) 15/hour, and agent calls (starting a run, answering, submitting credentials) 30/hour. Creating a migration and starting a `generate` run each also have a 30/hour cap. A `429` carries `Retry-After` plus `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. **Errors** are `{"error": "..."}`; some add a machine-readable `code` (e.g. `migration_archived`, `imports_in_flight`, `knowledge_too_long`, `storage_quota_exceeded`, `DOCUMENT_EXTRACTION_DISABLED`, `run_concurrency_limit`). An archived migration stays readable and exportable, but every call that changes it returns `409` with `code: migration_archived`. **Region**: accounts hosted in Australia use `https://au.app.vern.so/api/v1`. A key sent to the other region's base URL is answered `421` with `{"error", "code": "wrong_region", "region", "base_url", "mcp_url", "app_url"}` — switch to `base_url`. servers: - url: https://app.vern.so/api/v1 description: US-hosted accounts - url: https://au.app.vern.so/api/v1 description: Australia-hosted accounts security: - apiKey: [] tags: - name: Catalog description: Discover the sources and templates you set up in the Vern UI. - name: Migrations description: >- Create, list, update and archive migration workspaces, and upload a customer's files. - name: Runs description: 'Drive the managed agent: generate, refine, execute, answer, and observe.' - name: Export description: Download a migration's validated data as CSV. - name: Log description: The settled record of what a migration did. - name: Knowledge description: Durable context the agent reads before every run. - name: Exports description: Download imported data. paths: /migrations/{migration_id}: parameters: - $ref: '#/components/parameters/MigrationId' patch: tags: - Migrations summary: Update a migration description: >- The API version of the app's "Edit company" and "Add New Sheet". Send only the fields to change; any other field is a 400. `templates` ADDS templates: each slug without a sheet gets a new, empty one, and slugs that already have one are skipped — templates are never removed. Changing `source` or adding `templates` is refused with 409 (`code: imports_in_flight`) while an import is in progress, including a preview waiting for approval; `name` and `external_id` can always change. operationId: updateMigration requestBody: required: true content: application/json: schema: type: object minProperties: 1 additionalProperties: false properties: name: type: string description: New display name. Must be non-blank. source: type: - string - 'null' description: Source name to bind, or null for a sourceless migration. external_id: type: - string - 'null' maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ description: >- A new external ID, unique among your migrations, or null to clear it. templates: type: array items: type: string description: Template slugs to add. example: name: Acme Corporation templates: - accounts responses: '200': description: The updated migration. content: application/json: schema: type: object properties: migration: $ref: '#/components/schemas/Migration' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': description: No such migration, or the named source doesn't exist. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The migration is archived (`code: migration_archived`), an import is in progress (`code: imports_in_flight`, with the blocking `runs`), the `external_id` is already used by another migration, or the source name is ambiguous. content: application/json: schema: $ref: '#/components/schemas/ImportsInFlightError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: parameters: MigrationId: name: migration_id in: path required: true description: The migration ID returned by Create a migration. schema: type: string format: uuid example: c0a8012e-4f1b-4d3a-9b2c-7e6f5a4b3c2d schemas: Migration: type: object properties: id: type: string format: uuid description: The migration ID — pass it to every later call. name: type: string external_id: type: - string - 'null' description: Your own identifier for this customer. source: type: - string - 'null' status: type: string enum: - awaiting_files - ready - awaiting_approval - completed description: Omitted from `GET /migrations` list items. templates: type: array items: type: object properties: slug: type: string name: type: string archived: type: boolean description: >- Archived migrations stay readable and exportable but refuse uploads, runs and edits. Restore one from the Archived page in Vern. created_at: type: string format: date-time url: type: string format: uri description: >- Opens the company in Vern. `/companies/open/{key}` also accepts the `external_id`. Error: type: object properties: error: type: string description: A human-readable error message. code: type: string description: >- A machine-readable code, on errors whose status alone is ambiguous (e.g. migration_archived, imports_in_flight, knowledge_too_long). required: - error ImportsInFlightError: type: object description: >- An error body; with `code: imports_in_flight` it also lists the runs in the way. properties: error: type: string code: type: string enum: - imports_in_flight - migration_archived runs: type: array items: type: object properties: id: type: string status: type: string description: >- One of `pending`, `queued`, `running`, `blocked`, `awaiting_approval`. updatedAt: type: - string - 'null' format: date-time runKind: type: - string - 'null' required: - error responses: BadRequest: description: Malformed request. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: API key missing, malformed, or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Rate limit hit. Counted per account (company), not per API key or IP. Each endpoint is in one class: reads 30/minute, writes 30/minute, jobs (starting an export) 15/hour, agent (starting a run, answering, submitting credentials) 30/hour. Creating a migration and starting a `generate` run also have their own 30/hour caps. A separate per-IP ceiling absorbs floods before authentication. `Retry-After` gives the seconds until the window resets, alongside `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. headers: Retry-After: description: Seconds until the rate-limit window resets. schema: type: integer X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer X-RateLimit-Reset: description: Unix time (seconds) when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Too many requests ServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your Vern API key. Create one at Settings → API keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.