Create a merge queue
Requires the Update Merge Queue settings permission. Creates a merge queue for a repository and target branch. At most one queue exists per pair, so a second create returns QUEUE_ALREADY_EXISTS.
This operation is not atomic. bisectionConcurrency and enqueueingLabel are applied by a second write, so an error response does not guarantee that no queue was created — if the first write succeeded and the second failed, the queue exists with those two fields at their defaults and this call still returns the second write’s error. Do not blindly retry: a retry returns 409 QUEUE_ALREADY_EXISTS. Instead read the queue back (GET /v2/merge-queues?repositoryId=…&targetBranch=…) and, if it exists, finish the configuration with PATCH /v2/merge-queues/{id}/config.
Authorizations
An API key, sent as Authorization: Bearer <key>. An organization admin creates one in the Trunk app under Settings → Developer → API Keys and chooses the permissions it holds. A new key starts with no permissions: it can read merge queues but change nothing in them, and it cannot get a Dynamic CI plan. Each endpoint that needs a permission names it in its description; the Dynamic CI plan endpoints need Generate Dynamic CI plans.
Body
Omitting mode creates a queue-mode queue, and omitting concurrency sets it to 5.
Response
The created merge queue
The engine a queue runs. queue tests entries in strict arrival order, one line. graph builds a dependency graph and may test entries speculatively in parallel, which merges faster but can require bisection to attribute a failure. Changing mode is a real conversion, not a flag flip — see mergeQueues.switchModes.
queue, graph "queue"
Who owns the queue's configuration. terraform — the last write came from Terraform, identified on any queue write (create, config, pause/resume/drain, mode switch) by a User-Agent or X-Source header containing terraform or opentofu, case-insensitively — the same rule as v1. terraformWithDrift — Terraform owned it and a later write was not identified as Terraform's, so the live configuration may differ from the plan. Any such write counts, including pause/resume from other automation. manual — never written by Terraform.
manual, terraform, terraformWithDrift