Skip to main content
POST/migrations/queue

Queue Migration

Proposes one or more migration files for admin approval by inserting them into the pending-migration queue with status queued.

The body accepts an array of migration payloads; each queued row carries a SHA-256 checksum of the migration content, ensuring byte-identical execution at apply time.

Emits a migration.queued audit event covering all rows in the batch.

Returns data: PendingMigration[] for the queued rows.

Requires PROJECT_ADMIN.

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe request body is not a JSON object with a migrations array; fix the request and retry.
403K9O_ACCESS_DENIEDQueuing migrations requires the PROJECT_ADMIN role.
Response body (200)
data *object[]

One entry per submitted migration, in the order submitted.

id *string

The pending migration's id (pmig_...).

version *integer

The migration's version, an integer from 1 to 2147483647.

Versions apply in ascending order.

slug *string

The migration's slug, as given when it was submitted.

status *"queued" | "pending_approval"

queued: a project admin can apply it. pending_approval: it touches a protected collection (or loosens a collection's gate scope), and applies only when a different project admin grants the linked approval.

approvalId *any

The linked approval (apr_...) when the migration is governed by one; otherwise null.

One of: string
or: null
affectedCollections *string[]

The collections the migration's operations and policy section touch.

meta *any

Request metadata: cost, timing and correlation ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.migrations.queue()

Showing example in TypeScript

Response example (200)
{
  "data": [
    {
      "id": "string",
      "version": 0,
      "slug": "string",
      "status": "queued",
      "approvalId": "string",
      "affectedCollections": [
        "string"
      ]
    }
  ]
}

More in Storage & Schema