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

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.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/cancelPullRequest

HTTPcURLJavaScriptPython

POST /v1/cancelPullRequest HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "text"
}

Get a submitted pull request from a merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

idstringOptional

statestring · enumOptionalPossible values:

stateChangedAtstringRequired

priorityValuenumberRequired

priorityNamestringRequired

usedDefaultPriorityNamestringOptional

skipTheLinebooleanRequired

forceEnqueuedbooleanRequired

isCurrentlySubmittedToQueuebooleanRequired

prNumbernumberRequired

prTitlestringRequired

prShastringRequired

prBaseBranchstringRequired

prAuthorstringRequired

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/getSubmittedPullRequest

HTTPcURLJavaScriptPython

POST /v1/getSubmittedPullRequest HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "text"
}

{
  "id": "text",
  "state": "NOT_READY",
  "readiness": {
    "hasImpactedTargets": true,
    "requiresImpactedTargets": true,
    "doesBaseBranchMatch": true,
    "gitHubMergeability": "UNSPECIFIED"
  },
  "stateChangedAt": "text",
  "priorityValue": 1,
  "priorityName": "text",
  "usedDefaultPriorityName": "text",
  "skipTheLine": true,
  "forceEnqueued": true,
  "isCurrentlySubmittedToQueue": true,
  "prNumber": 1,
  "prTitle": "text",
  "prSha": "text",
  "prBaseBranch": "text",
  "prAuthor": "text"
}

Restart tests on a pull request in a merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/restartTestsOnPullRequest

HTTPcURLJavaScriptPython

POST /v1/restartTestsOnPullRequest HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "text"
}

Set impacted targets for a pull request.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

impactedTargetsany ofRequired

string[]Optional

or

const: ALLOptional

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/setImpactedTargets

HTTPcURLJavaScriptPython

POST /v1/setImpactedTargets HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1,
    "sha": "text"
  },
  "targetBranch": "text",
  "impactedTargets": [
    "text"
  ]
}

Submit a pull request to a merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

priorityany ofOptional

integer · max: 4294967295Optional

or

stringOptional

or

nullOptional

noBatchbooleanOptional

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/submitPullRequest

HTTPcURLJavaScriptPython

POST /v1/submitPullRequest HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "text",
  "priority": 1,
  "noBatch": true
}

Get details about testing that Merge Queue is performing

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

testRunIdstringRequired

targetBranchstringRequired

Responses

200

OK

application/json

requiredStatusesstring[]Required

requiredStatusesSourcestring · enumOptionalPossible values:

testBranchstringRequired

testBranchShastringRequired

createdAtstringOptional

statusstring · enumOptionalPossible values:

impactedTargetsstring[]Optional

impactedTargetsForTestedPrsstring[]Optional

dependentPrsnumber[]Optional

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/getMergeQueueTestingDetails

HTTPcURLJavaScriptPython

POST /v1/getMergeQueueTestingDetails HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 94

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "testRunId": "text",
  "targetBranch": "text"
}

{
  "requiredStatuses": [
    "text"
  ],
  "requiredStatusesSource": "TRUNK_CONFIG",
  "testBranch": "text",
  "testBranchSha": "text",
  "createdAt": "text",
  "status": "IN_PROGRESS",
  "checkSuites": [
    {
      "checkRuns": [
        {
          "name": "text",
          "url": "text",
          "status": "QUEUED",
          "conclusion": "ACTION_REQUIRED"
        }
      ]
    }
  ],
  "statusChecks": [
    {
      "context": "text",
      "url": "text",
      "state": "ERROR"
    }
  ],
  "testedPullRequests": [
    {
      "prNumber": 1,
      "prUrl": "text",
      "title": "text"
    }
  ],
  "impactedTargets": [
    "text"
  ],
  "impactedTargetsForTestedPrs": [
    "text"
  ],
  "dependentPrs": [
    1
  ]
}

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

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

modestring · enumOptionalPossible values:

concurrencyinteger · min: 1 · max: 4294967295Optional

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/createQueue

HTTPcURLJavaScriptPython

POST /v1/createQueue HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 107

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "targetBranch": "text",
  "mode": "single",
  "concurrency": 1
}

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

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/deleteQueue

HTTPcURLJavaScriptPython

POST /v1/deleteQueue HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "targetBranch": "text"
}

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

Get the merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

statestring · enumOptionalPossible values:

branchstringRequired

concurrencynumberRequired

testingTimeoutMinsnumberRequired

modestring · enumOptionalPossible values:

canOptimisticallyMergebooleanRequired

pendingFailureDepthnumberRequired

isBatchingbooleanRequired

batchingMaxWaitTimeMinsnumberRequired

batchingMinSizenumberRequired

createPrsForTestingBranchesbooleanRequired

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/getQueue

HTTPcURLJavaScriptPython

POST /v1/getQueue HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "targetBranch": "text"
}

{
  "state": "RUNNING",
  "branch": "text",
  "concurrency": 1,
  "testingTimeoutMins": 1,
  "mode": "SINGLE",
  "canOptimisticallyMerge": true,
  "pendingFailureDepth": 1,
  "isBatching": true,
  "batchingMaxWaitTimeMins": 1,
  "batchingMinSize": 1,
  "createPrsForTestingBranches": true,
  "enqueuedPullRequests": [
    {
      "id": "text",
      "state": "NOT_READY",
      "stateChangedAt": "text",
      "priorityValue": 1,
      "priorityName": "text",
      "usedDefaultPriorityName": "text",
      "skipTheLine": true,
      "noBatch": true,
      "prNumber": 1,
      "prTitle": "text",
      "prSha": "text",
      "prBaseBranch": "text",
      "prAuthor": "text"
    }
  ]
}

Update the merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

The branch that the merge queue is targeting.

statestring · enumOptional

The desired state of the merge queue. Valid values: RUNNING, PAUSED, DRAINING.

Possible values:

concurrencyinteger · min: 1 · max: 4294967295Optional

The number of PRs or batches of PRs the queue can test at once.

bisectionConcurrencyinteger · min: 1 · max: 4294967295Optional

The number of tests the merge queue can run when bisecting a batch to figure out what PR in the batch failed.

testingTimeoutMinutesinteger · min: 1 · max: 4294967295Optional

The maximum number of minutes the merge queue will wait for tests to complete before timing out.

pendingFailureDepthinteger · min: 1 · max: 4294967295Optional

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.

canOptimisticallyMergebooleanOptional

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.

batchbooleanOptional

Enable or disable batching. When enabled, the merge queue will group PRs into batches for testing.

batchingMaxWaitTimeMinutesinteger · min: 1 · max: 4294967295Optional

The maximum number of minutes the merge queue will wait to collect PRs into a batch before starting tests.

batchingMinSizeinteger · min: 1 · max: 4294967295Optional

The minimum number of PRs required to form a batch.

modestring · enumOptional

The queue mode. 'single' processes PRs one at a time. 'parallel' processes multiple PRs concurrently.

Possible values:

commentsEnabledbooleanOptional

Whether or not Merge Queue will post GitHub comments on PRs.

commandsEnabledbooleanOptional

Whether or not users are allowed to submit PRs to the merge queue by commenting /trunk merge.

createPrsForTestingBranchesbooleanOptional

Whether or not the merge queue will create PRs for its testing branches, allowing CI to run on them.

directMergeModestring · enumOptional

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.

Possible values:

optimizationModestring · enumOptional

The optimization strategy for the merge queue. 'OFF' disables optimizations. 'BISECTION_SKIP_REDUNDANT_TESTS' uses bisection and skips redundant tests.

Possible values:

mergeMethodstring · enumOptional

The Git merge method used when merging PRs into the target branch. Valid values: MERGE_COMMIT, SQUASH, REBASE.

Possible values:

statusCheckEnabledbooleanOptional

Post a GitHub status check on PRs with the status of the PR in the merge queue.

requiredStatusesstring[]Optional

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.

deleteRequiredStatusesbooleanOptional

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.

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/updateQueue

HTTPcURLJavaScriptPython

POST /v1/updateQueue HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 537

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "targetBranch": "text",
  "state": "RUNNING",
  "concurrency": 1,
  "bisectionConcurrency": 1,
  "testingTimeoutMinutes": 1,
  "pendingFailureDepth": 1,
  "canOptimisticallyMerge": true,
  "batch": true,
  "batchingMaxWaitTimeMinutes": 1,
  "batchingMinSize": 1,
  "mode": "single",
  "commentsEnabled": true,
  "commandsEnabled": true,
  "createPrsForTestingBranches": true,
  "directMergeMode": "OFF",
  "optimizationMode": "OFF",
  "mergeMethod": "MERGE_COMMIT",
  "statusCheckEnabled": true,
  "requiredStatuses": [
    "text"
  ],
  "deleteRequiredStatuses": true
}

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