# Apply the live capsule's migration plan

Queues the live capsule’s declared migration plan against the Space’s database and returns the plan with an operation to poll. Use it to retry a plan that did not apply during publish; the plan is pinned to the version live at the time of the call, so a later publish cannot redirect the retry. An empty plan queues nothing and answers `queued: false`. Requires `versions:promote`, and only a Zero capsule declares a plan: a worker returns `runtime_kind_mismatch` and a Space with no database returns `db_not_available`.

## POST `/v1/spaces/{spaceId}/db/migrate`

### Authorization

`Authorization` Bearer token · header required

`Authorization: Bearer <key>` with the Space key (`sfc_` prefix) of an unclaimed Space. The same key is the fragment of the claim URL and the token in the Space's `/__/ <key>` sign-in URL.

or

`Authorization` Bearer token · header required

`Authorization: Bearer <token>` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

### Path parameters

`spaceId` string required

### Responses

#### 200 Response for status 200

`$schema` string <uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

`data` object required

- `versionId` string required
    - Live version whose declared plan this is.
    - min length 1
- `runtimeKind` string required
- `schemaHash` string | any required
- `operations` object[] required
    - Operations the live capsule declared, in the order they apply. Empty when the schema already matches.
    - Array of `object`
        - `op` string required
        - `table` string required
            - min length 1 · max length 128 · matches ^[A-Za-z_][A-Za-z0-9_]*

- `queued` boolean required
    - Whether an apply was queued. False when the plan has no operations, so nothing was queued and no operation is returned.
- `operation` object | any required
    - Background operation still running after this call. Null when all work finished before the response.
- `id` string required
- `kind` string required
- `status` string required
    - Allowed: `queued` `running` `succeeded` `failed` `canceled`
- `resources` object[] required
    - Array of `object`
        - `type` string required
        - `id` string required
        - `progress` object
            - `total` integer required
                - min 0 · max 9007199254740991
            - `completed` integer required
                - min 0 · max 9007199254740991
            - `failed` integer required
                - min 0 · max 9007199254740991
        - `diagnostics` object[]
            - Array of `object`
                - `code` string required
                    - Stable snake_case code for this diagnostic.
                - `severity` string required
                    - How serious the diagnostic is.
                    - Allowed: `info` `warning` `error`
                - `message` string required
                    - What happened, in a sentence a person can act on.
                - `path` string | any
                    - File or artifact path the diagnostic refers to.
                - `provider` string | any
                    - Upstream system that raised the diagnostic.
                - `details` object | any
                    - Machine-readable context keyed by the diagnostic code.
                - `fix` string | any
                    - What to change to clear the diagnostic.
                - `retryable` boolean | any
                    - True when repeating the same operation unchanged can clear the diagnostic.
- `createdAt` string <date-time> required
    - matches ^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$
- `finishedAt` string <date-time>
    - matches ^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$

#### 200default

```json
{
  "$schema": "http://example.com",
  "data": {
    "versionId": "string",
    "runtimeKind": "zero",
    "schemaHash": "string",
    "operations": [
      {  
        "op": "create_table",
        "table": "string"  
      }
    ],
    "queued": true
  },
  "operation": {
    "id": "string",
    "kind": "string",
    "status": "queued",
    "resources": [
      {  
        "type": "string",
        "id": "string"
      }
    ],
    "progress": {
      "total": 9007199254740991,
      "completed": 9007199254740991,
      "failed": 9007199254740991
    },
    "diagnostics": [
      {
        "code": "string",
        "severity": "info",
        "message": "string",
        "path": "string",
        "provider": "infra",
        "details": {
          "property1": null,
          "property2": null
        },
        "fix": "string",
        "retryable": true
      }
    ],
    "createdAt": "2019-08-24T14:15:22Z",
    "finishedAt": "2019-08-24T14:15:22Z"
  }
}
```

```json
{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}
```