# API reference The Trunk Merge Queue API lets you manage pull requests, configure queues, and monitor queue health programmatically. Use it to integrate merge queue operations into your CI/CD pipelines, build custom dashboards, or automate queue management across repositories. The API is an HTTP REST API hosted at `https://api.trunk.io/v1`. It returns JSON from all requests and uses standard HTTP response codes. All requests must be [authenticated](https://docs.trunk.io/setup-and-administration/apis#authentication) by providing the `x-api-token` header. ## Endpoint summary | Endpoint | Method | Description | | ------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | | [`/submitPullRequest`](#post-submitpullrequest) | POST | Submit a PR to the merge queue for testing and merging | | [`/cancelPullRequest`](#post-cancelpullrequest) | POST | Remove a PR from the merge queue | | [`/restartTestsOnPullRequest`](#post-restarttestsonpullrequest) | POST | Re-run tests on a PR currently in the queue | | [`/getSubmittedPullRequest`](#post-getsubmittedpullrequest) | POST | Check the status of a submitted PR | | [`/setImpactedTargets`](#post-setimpactedtargets) | POST | Set impacted targets for a PR (used with [parallel queues](https://docs.trunk.io/merge-queue/optimizations/parallel-queues)) | | [`/getMergeQueueTestingDetails`](#post-getmergequeuetestingdetails) | POST | Get details about in-progress merge queue testing | | [`/createQueue`](#post-createqueue) | POST | Create a new merge queue for a branch | | [`/deleteQueue`](#post-deletequeue) | POST | Delete an empty merge queue | | [`/getQueue`](#post-getqueue) | POST | Get queue state, configuration, and enqueued PRs | | [`/updateQueue`](#post-updatequeue) | POST | Update queue configuration (mode, concurrency, batching, etc.) | | [`/getMergeQueueMetrics`](#prometheus-metrics) | GET | Get Prometheus-format metrics for monitoring | ## Common use cases **CI/CD automation** — Submit PRs to the queue, check their status, and restart tests automatically from your CI pipelines. **Queue management** — Create and configure queues for different branches, adjust concurrency and batching settings, or pause and drain queues during maintenance windows. **Monitoring dashboards** — Use the Prometheus metrics endpoint to build custom Grafana dashboards or feed queue health data into your existing observability stack. **PR status checks** — Query the status of submitted PRs to build custom notifications or gate downstream workflows. ## Request format Most endpoints accept a JSON request body with these common fields: ```json { "repo": { "host": "github.com", "owner": "my-org", "name": "my-repo" }, "targetBranch": "main", "pr": { "number": 123 } } ``` | Field | Type | Required | Description | | -------------- | ------- | -------- | --------------------------------------------------- | | `repo.host` | string | Yes | Repository host (e.g., `github.com`) | | `repo.owner` | string | Yes | Repository owner or organization | | `repo.name` | string | Yes | Repository name | | `targetBranch` | string | Yes | The branch the merge queue targets | | `pr.number` | integer | Varies | The pull request number (required for PR endpoints) | ## Examples ### Submit a PR to the queue ```bash curl -X POST https://api.trunk.io/v1/submitPullRequest \ -H "Content-Type: application/json" \ -H "x-api-token: $TRUNK_API_TOKEN" \ -d '{ "repo": { "host": "github.com", "owner": "my-org", "name": "my-repo" }, "targetBranch": "main", "pr": { "number": 123 } }' ``` ### Check PR status ```bash curl -X POST https://api.trunk.io/v1/getSubmittedPullRequest \ -H "Content-Type: application/json" \ -H "x-api-token: $TRUNK_API_TOKEN" \ -d '{ "repo": { "host": "github.com", "owner": "my-org", "name": "my-repo" }, "targetBranch": "main", "pr": { "number": 123 } }' ``` The response includes the PR state (`NOT_READY`, `PENDING`, `TESTING`, `TESTS_PASSED`, `MERGED`, `FAILED`, `CANCELLED`, or `PENDING_FAILURE`), priority information, and whether the PR is currently submitted to the queue. ### Get queue state ```bash curl -X POST https://api.trunk.io/v1/getQueue \ -H "Content-Type: application/json" \ -H "x-api-token: $TRUNK_API_TOKEN" \ -d '{ "repo": { "host": "github.com", "owner": "my-org", "name": "my-repo" }, "targetBranch": "main" }' ``` The response includes the queue state (`RUNNING`, `PAUSED`, `DRAINING`, or `SWITCHING_MODES`), configuration settings, and a list of all enqueued pull requests with their current states. *** ## Pull request endpoints ## POST /cancelPullRequest > Cancel a pull request in a merge queue. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/cancelPullRequest":{"post":{"summary":"Cancel a pull request in a merge queue.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"pr":{"type":"object","properties":{"number":{"type":"integer","minimum":0,"maximum":4294967295}},"required":["number"]},"targetBranch":{"type":"string"}},"required":["repo","pr","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## POST /getSubmittedPullRequest > Get a submitted pull request from a merge queue. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/getSubmittedPullRequest":{"post":{"summary":"Get a submitted pull request from a merge queue.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"pr":{"type":"object","properties":{"number":{"type":"integer","minimum":0,"maximum":4294967295}},"required":["number"]},"targetBranch":{"type":"string"}},"required":["repo","pr","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["not_ready","pending","testing","tests_passed","merged","failed","cancelled","pending_failure"],"description":"The state of a pull request in the merge queue. See https://docs.trunk.io/merge-queue/using-the-queue/reference#pull-request-states for the full description of each state."},"readiness":{"type":"object","properties":{"hasImpactedTargets":{"type":"boolean","description":"Whether the set of impacted build/test targets for this PR has been reported."},"requiresImpactedTargets":{"type":"boolean","description":"Whether the queue is configured to require impacted-target reporting before a PR can start testing."},"doesBaseBranchMatch":{"type":"boolean","description":"Whether the PR's base branch matches the queue's target branch."},"gitHubMergeability":{"type":"string","enum":["unspecified","in_progress","mergeable","not_mergeable"],"description":"GitHub's mergeability state for the PR (cached). `unspecified` — not yet known. `in_progress` — GitHub is still computing mergeability. `mergeable` — GitHub reports the PR can be merged. `not_mergeable` — GitHub reports the PR cannot be merged (e.g. merge conflict)."}},"required":["requiresImpactedTargets","doesBaseBranchMatch","gitHubMergeability"],"description":"Readiness signals for a pull request in the merge queue. A PR can start testing when `doesBaseBranchMatch` is true, `gitHubMergeability` is `mergeable`, and (when `requiresImpactedTargets` is true) `hasImpactedTargets` is true."},"stateChangedAt":{"type":"string"},"priorityValue":{"type":"number"},"priorityName":{"type":"string"},"usedDefaultPriorityName":{"type":"string"},"skipTheLine":{"type":"boolean"},"forceEnqueued":{"type":"boolean"},"isCurrentlySubmittedToQueue":{"type":"boolean"},"prNumber":{"type":"number"},"prTitle":{"type":"string"},"prSha":{"type":"string"},"prBaseBranch":{"type":"string"},"prAuthor":{"type":"string"}},"required":["stateChangedAt","priorityValue","priorityName","skipTheLine","forceEnqueued","isCurrentlySubmittedToQueue","prNumber","prTitle","prSha","prBaseBranch","prAuthor"]}}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## POST /restartTestsOnPullRequest > Restart tests on a pull request in a merge queue. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/restartTestsOnPullRequest":{"post":{"summary":"Restart tests on a pull request in a merge queue.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"pr":{"type":"object","properties":{"number":{"type":"integer","minimum":0,"maximum":4294967295}},"required":["number"]},"targetBranch":{"type":"string"}},"required":["repo","pr","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## POST /setImpactedTargets > Set impacted targets for a pull request. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/setImpactedTargets":{"post":{"summary":"Set impacted targets for a pull request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"pr":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":4294967295},"sha":{"type":"string"}},"required":["number","sha"]},"targetBranch":{"type":"string"},"impactedTargets":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string","const":"ALL"}]}},"required":["repo","pr","targetBranch","impactedTargets"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## POST /submitPullRequest > Submit a pull request to a merge queue. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/submitPullRequest":{"post":{"summary":"Submit a pull request to a merge queue.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"pr":{"type":"object","properties":{"number":{"type":"integer","minimum":0,"maximum":4294967295}},"required":["number"]},"targetBranch":{"type":"string"},"priority":{"anyOf":[{"type":"integer","minimum":0,"maximum":4294967295},{"type":"string"},{"type":"null"}]},"noBatch":{"type":"boolean"}},"required":["repo","pr","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## POST /getMergeQueueTestingDetails > Get details about testing that Merge Queue is performing ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/getMergeQueueTestingDetails":{"post":{"summary":"Get details about testing that Merge Queue is performing","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string","description":"The host of the repository (e.g. `github.com`)."},"owner":{"type":"string","description":"The owner of the repository (e.g. `my-org`)."},"name":{"type":"string","description":"The name of the repository (e.g. `my-repo`)."}},"required":["host","owner","name"],"description":"The repository whose merge queue is running the test run."},"testRunId":{"type":"string"},"targetBranch":{"type":"string","description":"The target branch of the merge queue that is running the test run (e.g. `main`)."}},"required":["repo","testRunId","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"requiredStatuses":{"type":"array","items":{"type":"string"},"description":"The list of status check names that must all pass for the test run to succeed and its PRs to merge."},"requiredStatusesSource":{"type":"string","enum":["trunk_config","repo_provider_branch_protection","merge_instance"],"description":"Where the merge queue sourced the list of required statuses from. `trunk_config` — from the repository's `.trunk/trunk.yaml`. `repo_provider_branch_protection` — from the Git provider's branch protection settings (e.g. GitHub branch protection rules). `merge_instance` — from the merge queue's own configuration (e.g. set via the API)."},"testBranch":{"type":"string","description":"The name of the temporary branch the merge queue created to run tests against (e.g. `trunk-merge/pr-1815/5df78918-...`)."},"testBranchSha":{"type":"string","description":"The commit SHA at the tip of the test branch that the test run was started on."},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the test run was created."},"status":{"type":"string","enum":["in_progress","failed","cancelled","succeeded"],"description":"The status of a merge queue test run. `in_progress` — tests are currently running. `succeeded` — all required statuses passed. `failed` — at least one required status failed. `cancelled` — the test run was cancelled before completion."},"checkSuites":{"type":"array","items":{"type":"object","properties":{"checkRuns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The name of the GitHub check run (e.g. `build`, `lint`)."},"url":{"type":"string","description":"URL to the check run on GitHub."},"status":{"type":"string","enum":["QUEUED","IN_PROGRESS","COMPLETED"],"description":"The status of a GitHub check run. Mirrors GitHub's check run status values."},"conclusion":{"type":"string","enum":["ACTION_REQUIRED","CANCELLED","FAILURE","NEUTRAL","SUCCESS","SKIPPED","STALE","TIMED_OUT"],"description":"The conclusion of a completed GitHub check run. Mirrors GitHub's check run conclusion values; only set once `status` is `COMPLETED`."}},"required":["name","url"]},"description":"The individual check runs that make up this check suite."}},"required":["checkRuns"]},"description":"GitHub check suites reported against the test branch."},"statusChecks":{"type":"array","items":{"type":"object","properties":{"context":{"type":"string","description":"The context (name) of the status check as posted to GitHub (e.g. `ci/lint`)."},"url":{"type":"string","description":"URL with more details about this status check, if any."},"state":{"type":"string","enum":["ERROR","FAILURE","PENDING","SUCCESS"],"description":"The state of a GitHub commit status check. Mirrors GitHub's commit status state values."}},"required":["context"]},"description":"GitHub commit status checks reported against the test branch SHA."},"testedPullRequests":{"type":"array","items":{"type":"object","properties":{"prNumber":{"type":"number","description":"The pull request number on the Git provider."},"prUrl":{"type":"string","description":"URL of the pull request on the Git provider."},"title":{"type":"string","description":"The title of the pull request."}},"required":["prNumber","prUrl","title"]},"description":"The pull requests that this test run is testing. Contains multiple entries when batching is enabled."},"impactedTargets":{"type":"array","items":{"type":"string"},"description":"The union of impacted build/test targets across all PRs involved in the test run, including any dependent PRs previously merged into the test branch. Only present when impacted targets are being uploaded for the repository."},"impactedTargetsForTestedPrs":{"type":"array","items":{"type":"string"},"description":"The impacted build/test targets for only the PRs being tested in this run (i.e. `testedPullRequests`), excluding any dependent PRs. Only present when impacted targets are being uploaded for the repository."},"dependentPrs":{"type":"array","items":{"type":"number"},"description":"PR numbers of other PRs this test run depends on but is not itself testing. Populated in parallel-mode queues when previously-passed PRs ahead of the tested PR are merged into the test branch to form the predicted base."}},"required":["requiredStatuses","testBranch","testBranchSha","checkSuites","statusChecks","testedPullRequests"]}}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## Metrics endpoints ### Prometheus metrics `GET /v1/getMergeQueueMetrics` Returns merge queue metrics in Prometheus text exposition format. Authenticate with the `x-api-token` header. | Parameter | Required | Description | | ---------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `repo` | No | Repository in `owner/name` format. If omitted, returns metrics for all repositories in the organization. Must be provided together with `repoHost`. | | `repoHost` | Conditional | Repository host (e.g., `github.com`). Required if `repo` is specified. | Response content type: `text/plain; version=0.0.4; charset=utf-8` See [Prometheus metrics endpoint](https://docs.trunk.io/administration/metrics#prometheus-metrics-endpoint) for the full list of available metrics, scrape configuration, and example queries. ## Queue endpoints Use these endpoints to create, configure, and manage merge queues. Each queue targets a specific branch in your repository. For more on running multiple queues, see [parallel queues](https://docs.trunk.io/merge-queue/optimizations/parallel-queues). ## POST /createQueue > Create a new merge queue. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/createQueue":{"post":{"summary":"Create a new merge queue.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"targetBranch":{"type":"string"},"mode":{"type":"string","enum":["single","parallel"],"description":"The queue processing mode. See https://docs.trunk.io/merge-queue/administration/advanced-settings#merge-queue-mode for details."},"concurrency":{"type":"integer","minimum":1,"maximum":4294967295}},"required":["repo","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## POST /deleteQueue > Delete the specified merge queue. The queue must be empty in order to be deleted. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/deleteQueue":{"post":{"summary":"Delete the specified merge queue. The queue must be empty in order to be deleted.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"targetBranch":{"type":"string"}},"required":["repo","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` {% hint style="warning" %} The queue must be empty before it can be deleted. Cancel or merge all enqueued PRs first. {% endhint %} ## POST /getQueue > Get the merge queue. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/getQueue":{"post":{"summary":"Get the merge queue.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"targetBranch":{"type":"string"}},"required":["repo","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["running","paused","draining","switching_modes"],"description":"The state of the merge queue. See https://docs.trunk.io/merge-queue/administration/advanced-settings#merge-queue-state for the full description of each state."},"branch":{"type":"string"},"concurrency":{"type":"number"},"testingTimeoutMinutes":{"type":"number"},"mode":{"type":"string","enum":["single","parallel"]},"canOptimisticallyMerge":{"type":"boolean"},"pendingFailureDepth":{"type":"number"},"batch":{"type":"boolean"},"batchingMaxWaitTimeMinutes":{"type":"number"},"batchingMinSize":{"type":"number"},"createPrsForTestingBranches":{"type":"boolean"},"commentsEnabled":{"type":"boolean"},"commandsEnabled":{"type":"boolean"},"statusCheckEnabled":{"type":"boolean"},"bisectionConcurrency":{"type":"number"},"requiredStatuses":{"type":"array","items":{"type":"string"}},"directMergeMode":{"type":"string","enum":["off","always"],"description":"Controls whether PRs can skip the queue's test run and merge directly when already up to date with the target branch. See https://docs.trunk.io/merge-queue/administration/advanced-settings#direct-merge-to-main for details."},"optimizationMode":{"type":"string","enum":["off","bisection_skip_redundant_tests"],"description":"The optimization strategy for the merge queue. `off` — no optimizations. See https://docs.trunk.io/merge-queue/optimizations/batching#test-caching-during-bisection for details on `bisection_skip_redundant_tests`."},"mergeMethod":{"type":"string","enum":["merge_commit","squash","rebase"],"description":"The Git strategy used to merge a PR into the target branch. See https://docs.trunk.io/merge-queue/administration/advanced-settings#merge-method for details."},"enqueuedPullRequests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["not_ready","pending","testing","tests_passed","merged","failed","cancelled","pending_failure"],"description":"The state of a pull request in the merge queue. See https://docs.trunk.io/merge-queue/using-the-queue/reference#pull-request-states for the full description of each state."},"stateChangedAt":{"type":"string"},"priorityValue":{"type":"number"},"priorityName":{"type":"string"},"usedDefaultPriorityName":{"type":"string"},"skipTheLine":{"type":"boolean"},"noBatch":{"type":"boolean"},"prNumber":{"type":"number"},"prTitle":{"type":"string"},"prSha":{"type":"string"},"prBaseBranch":{"type":"string"},"prAuthor":{"type":"string"}},"required":["stateChangedAt","priorityValue","priorityName","skipTheLine","noBatch","prNumber","prTitle","prSha","prBaseBranch","prAuthor"]}}},"required":["state","branch","concurrency","testingTimeoutMinutes","mode","canOptimisticallyMerge","pendingFailureDepth","batch","batchingMaxWaitTimeMinutes","batchingMinSize","createPrsForTestingBranches","commentsEnabled","commandsEnabled","statusCheckEnabled","bisectionConcurrency","requiredStatuses","directMergeMode","optimizationMode","mergeMethod","enqueuedPullRequests"]}}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## POST /updateQueue > Update the merge queue. ```json {"openapi":"3.1.0","info":{"title":"Trunk APIs","version":"1.0.0"},"servers":[{"url":"https://api.trunk.io/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-token"}}},"paths":{"/updateQueue":{"post":{"summary":"Update the merge queue.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"object","properties":{"host":{"type":"string"},"owner":{"type":"string"},"name":{"type":"string"}},"required":["host","owner","name"]},"targetBranch":{"type":"string","description":"The branch that the merge queue is targeting."},"state":{"type":"string","enum":["running","paused","draining"],"description":"The desired state of the merge queue. Valid values: RUNNING, PAUSED, DRAINING."},"concurrency":{"type":"integer","minimum":1,"maximum":4294967295,"description":"The number of PRs or batches of PRs the queue can test at once."},"bisectionConcurrency":{"type":"integer","minimum":1,"maximum":4294967295,"description":"The number of tests the merge queue can run when bisecting a batch to figure out what PR in the batch failed."},"testingTimeoutMinutes":{"type":"integer","minimum":1,"maximum":4294967295,"description":"The maximum number of minutes the merge queue will wait for tests to complete before timing out."},"pendingFailureDepth":{"type":"integer","minimum":1,"maximum":4294967295,"description":"When enabled, PRs that fail tests will wait for the specified number of PRs below them to finish testing before getting kicked from the queue. This works best with optimistic merging enabled."},"canOptimisticallyMerge":{"type":"boolean","description":"When enabled, a PR that passes tests will also cause any PR ahead of it in the queue to also get marked as passing, since tests have passed with those commits."},"batch":{"type":"boolean","description":"Enable or disable batching. When enabled, the merge queue will group PRs into batches for testing."},"batchingMaxWaitTimeMinutes":{"type":"integer","minimum":1,"maximum":4294967295,"description":"The maximum number of minutes the merge queue will wait to collect PRs into a batch before starting tests."},"batchingMinSize":{"type":"integer","minimum":1,"maximum":4294967295,"description":"The minimum number of PRs required to form a batch."},"mode":{"type":"string","enum":["single","parallel"],"description":"The queue mode. 'single' processes PRs one at a time. 'parallel' processes multiple PRs concurrently."},"commentsEnabled":{"type":"boolean","description":"Whether or not Merge Queue will post GitHub comments on PRs."},"commandsEnabled":{"type":"boolean","description":"Whether or not users are allowed to submit PRs to the merge queue by commenting `/trunk merge`."},"createPrsForTestingBranches":{"type":"boolean","description":"Whether or not the merge queue will create PRs for its testing branches, allowing CI to run on them."},"directMergeMode":{"type":"string","enum":["off","always"],"description":"Allow PRs to merge directly into the target branch if they're up to date with the target branch when submitting them to the queue instead of running tests on them in the merge queue."},"optimizationMode":{"type":"string","enum":["off","bisection_skip_redundant_tests"],"description":"The optimization strategy for the merge queue. 'off' disables optimizations. 'bisection_skip_redundant_tests' uses bisection and skips redundant tests."},"mergeMethod":{"type":"string","enum":["merge_commit","squash","rebase"],"description":"The Git merge method used when merging PRs into the target branch. Valid values: merge_commit, squash, rebase."},"statusCheckEnabled":{"type":"boolean","description":"Post a GitHub status check on PRs with the status of the PR in the merge queue."},"requiredStatuses":{"type":"array","items":{"type":"string"},"description":"Allows setting the statuses that must pass when the merge queue performs tests in order for a PR to merge. Setting the statuses here will override GitHub branch protection settings or your `.trunk/trunk.yaml`."},"deleteRequiredStatuses":{"type":"boolean","description":"Removes a manually specified set of required statuses. After this, the statuses that must pass when the merge queue performs testing will be pulled from either GitHub branch protection settings or your `.trunk/trunk.yaml`."}},"required":["repo","targetBranch"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["running","paused","draining","switching_modes"],"description":"The state of the merge queue. See https://docs.trunk.io/merge-queue/administration/advanced-settings#merge-queue-state for the full description of each state."},"branch":{"type":"string"},"concurrency":{"type":"number"},"testingTimeoutMinutes":{"type":"number"},"mode":{"type":"string","enum":["single","parallel"]},"canOptimisticallyMerge":{"type":"boolean"},"pendingFailureDepth":{"type":"number"},"batch":{"type":"boolean"},"batchingMaxWaitTimeMinutes":{"type":"number"},"batchingMinSize":{"type":"number"},"createPrsForTestingBranches":{"type":"boolean"},"commentsEnabled":{"type":"boolean"},"commandsEnabled":{"type":"boolean"},"statusCheckEnabled":{"type":"boolean"},"bisectionConcurrency":{"type":"number"},"requiredStatuses":{"type":"array","items":{"type":"string"}},"directMergeMode":{"type":"string","enum":["off","always"],"description":"Controls whether PRs can skip the queue's test run and merge directly when already up to date with the target branch. See https://docs.trunk.io/merge-queue/administration/advanced-settings#direct-merge-to-main for details."},"optimizationMode":{"type":"string","enum":["off","bisection_skip_redundant_tests"],"description":"The optimization strategy for the merge queue. `off` — no optimizations. See https://docs.trunk.io/merge-queue/optimizations/batching#test-caching-during-bisection for details on `bisection_skip_redundant_tests`."},"mergeMethod":{"type":"string","enum":["merge_commit","squash","rebase"],"description":"The Git strategy used to merge a PR into the target branch. See https://docs.trunk.io/merge-queue/administration/advanced-settings#merge-method for details."}},"required":["state","branch","concurrency","testingTimeoutMinutes","mode","canOptimisticallyMerge","pendingFailureDepth","batch","batchingMaxWaitTimeMinutes","batchingMinSize","createPrsForTestingBranches","commentsEnabled","commandsEnabled","statusCheckEnabled","bisectionConcurrency","requiredStatuses","directMergeMode","optimizationMode","mergeMethod"]}}}},"400":{"description":"Bad Request","content":{"application/plain-text":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/plain-text":{"schema":{"type":"string"}}}},"404":{"description":"Not Found","content":{"application/plain-text":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/plain-text":{"schema":{"type":"string"}}}}}}}}} ``` ## Related resources * [CLI reference](https://docs.trunk.io/merge-queue/reference/merge-queue-cli-reference) — Command-line interface for merge queue operations * [Metrics and monitoring](https://docs.trunk.io/merge-queue/administration/metrics) — Dashboard analytics and Prometheus endpoint details * [Webhooks](https://docs.trunk.io/merge-queue/webhooks) — Event-driven notifications for queue activity * [Settings and configurations](https://docs.trunk.io/merge-queue/administration/advanced-settings) — Queue settings available in the Trunk web app * [Authentication](https://docs.trunk.io/setup-and-administration/apis#authentication) — API token setup and management --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.trunk.io/merge-queue/reference/merge.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.