API reference

Public Trunk Merge Queue API. All requests should be authenticated.

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 by providing the x-api-token header.

Endpoint summary

Endpoint	Method	Description
/submitPullRequest	POST	Submit a PR to the merge queue for testing and merging
/cancelPullRequest	POST	Remove a PR from the merge queue
/restartTestsOnPullRequest	POST	Re-run tests on a PR currently in the queue
/getSubmittedPullRequest	POST	Check the status of a submitted PR
/setImpactedTargets	POST	Set impacted targets for a PR (used with parallel queues)
/getMergeQueueTestingDetails	POST	Get details about in-progress merge queue testing
/createQueue	POST	Create a new merge queue for a branch
/deleteQueue	POST	Delete an empty merge queue
/getQueue	POST	Get queue state, configuration, and enqueued PRs
/updateQueue	POST	Update queue configuration (mode, concurrency, batching, etc.)
/getMergeQueueMetrics	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

Request bodies must not exceed 20 MiB.

Most endpoints accept a JSON request body with these common fields:

{
  "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

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

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

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

Cancel a pull request in a merge queue

Get a submitted pull request from a merge queue

Restart tests on a pull request in a merge queue

Set impacted targets for a pull request

Submit a pull request to a merge queue

Get details about testing that Merge Queue is performing

Large monorepos can produce target lists that exceed the 20 MiB request body limit. If you hit this limit, send "ALL" as the impactedTargets value to mark the PR as impacting every target.

Metrics endpoints

Prometheus metrics

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 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.

Create a new merge queue.

Delete the specified merge queue. The queue must be empty in order to be deleted.

Get the merge queue.

Update the merge queue.

The queue must be empty before it can be deleted. Cancel or merge all enqueued PRs first.

Related resources

• CLI reference — Command-line interface for merge queue operations
• Metrics and monitoring — Dashboard analytics and Prometheus endpoint details
• Webhooks — Event-driven notifications for queue activity
• Settings and configurations — Queue settings available in the Trunk web app
• Authentication — API token setup and management