Submit a pull request to a merge queue

curl --request POST \
  --url https://api.trunk.io/v2/merge-queues/{id}/pull-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": 123,
  "allowBatching": true,
  "priorityValue": 16383,
  "priorityName": "<string>",
  "direct": true
}
'

import requests

url = "https://api.trunk.io/v2/merge-queues/{id}/pull-requests"

payload = {
    "number": 123,
    "allowBatching": True,
    "priorityValue": 16383,
    "priorityName": "<string>",
    "direct": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    number: 123,
    allowBatching: true,
    priorityValue: 16383,
    priorityName: '<string>',
    direct: true
  })
};

fetch('https://api.trunk.io/v2/merge-queues/{id}/pull-requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trunk.io/v2/merge-queues/{id}/pull-requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'number' => 123,
    'allowBatching' => true,
    'priorityValue' => 16383,
    'priorityName' => '<string>',
    'direct' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trunk.io/v2/merge-queues/{id}/pull-requests"

	payload := strings.NewReader("{\n  \"number\": 123,\n  \"allowBatching\": true,\n  \"priorityValue\": 16383,\n  \"priorityName\": \"<string>\",\n  \"direct\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trunk.io/v2/merge-queues/{id}/pull-requests")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"number\": 123,\n  \"allowBatching\": true,\n  \"priorityValue\": 16383,\n  \"priorityName\": \"<string>\",\n  \"direct\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trunk.io/v2/merge-queues/{id}/pull-requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"number\": 123,\n  \"allowBatching\": true,\n  \"priorityValue\": 16383,\n  \"priorityName\": \"<string>\",\n  \"direct\": true\n}"

response = http.request(request)
puts response.read_body

{
  "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "repositoryId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "number": 4901,
  "title": "feat: terminate /v2 at the gateway",
  "branch": "phil/implement-remaining-apis",
  "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
  "baseBranch": "main",
  "author": "octocat",
  "isCurrentlySubmittedToQueue": true,
  "createdAt": "2026-07-28T10:55:00.000Z",
  "url": "https://github.com/acme/widgets/pull/4901",
  "state": "open",
  "queueEntry": {
    "id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "mergeQueueId": "xK9mP2nQ",
    "state": "testing",
    "stateChangedAt": "2026-07-28T11:40:02.000Z",
    "skipsTheLine": false,
    "allowBatching": true,
    "direct": false,
    "readiness": {
      "requiresImpactedTargets": true,
      "doesBaseBranchMatch": true,
      "mergeability": "mergeable",
      "hasImpactedTargets": true,
      "mergeabilityDetails": {
        "provider": "github",
        "reasons": [
          {
            "code": "reviewRequired",
            "message": "needs 1 more approving review",
            "have": 0,
            "need": 1
          }
        ]
      }
    },
    "createdAt": "2026-07-28T11:02:31.000Z",
    "updatedAt": "2026-07-28T11:40:02.000Z",
    "priorityValue": 100,
    "priorityName": "high",
    "usedDefaultPriorityName": "medium",
    "verifiedByVerificationRunId": "a1b2c3d4-e5f6-4718-9a0b-1c2d3e4f5061"
  },
  "htmlUrl": "https://app.trunk.io/acme/pull/4901?repo=1a2b3c4d",
  "viewerIsAuthor": true,
  "ci": {
    "headSha": "a0de7a77e8d758a346f83ed19209a5a25814bb17",
    "observedAt": "2026-09-29T15:12:25.000Z",
    "pollAfterSeconds": 10,
    "jobs": {
      "total": 209,
      "queued": 0,
      "running": 0,
      "passed": 110,
      "failed": 2,
      "cancelled": 0,
      "skipped": 97,
      "abandoned": 0
    },
    "jobsUrl": "/v2/ci-jobs?pullRequestId=0f8fad5b-d9cb-469f-a165-70867728950e&commitSha=a0de7a77e8d758a346f83ed19209a5a25814bb17",
    "workflowRunsUrl": "/v2/ci-workflow-runs?pullRequestId=0f8fad5b-d9cb-469f-a165-70867728950e&commitSha=a0de7a77e8d758a346f83ed19209a5a25814bb17"
  }
}

Pull requests

Submit a pull request to a merge queue

Enqueues a pull request. A pull request already enqueued in this queue is refused with PR_ALREADY_ENQUEUED rather than having its priority rewritten — change a live entry through POST /v2/pull-requests/{id}/reprioritize or PATCH /v2/pull-requests/{id}/queue-entry. readiness.hasImpactedTargets may be absent on the 201 if the post-write lookup failed; the enqueue still landed, so read the pull request again rather than retrying.

Idempotency-Key is not honored. If a request times out, resolve the pull request by repository and number and inspect its queue entry before retrying.

POST

merge-queues

{id}

pull-requests

Submit a pull request to a merge queue

curl --request POST \
  --url https://api.trunk.io/v2/merge-queues/{id}/pull-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": 123,
  "allowBatching": true,
  "priorityValue": 16383,
  "priorityName": "<string>",
  "direct": true
}
'

import requests

url = "https://api.trunk.io/v2/merge-queues/{id}/pull-requests"

payload = {
    "number": 123,
    "allowBatching": True,
    "priorityValue": 16383,
    "priorityName": "<string>",
    "direct": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    number: 123,
    allowBatching: true,
    priorityValue: 16383,
    priorityName: '<string>',
    direct: true
  })
};

fetch('https://api.trunk.io/v2/merge-queues/{id}/pull-requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trunk.io/v2/merge-queues/{id}/pull-requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'number' => 123,
    'allowBatching' => true,
    'priorityValue' => 16383,
    'priorityName' => '<string>',
    'direct' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trunk.io/v2/merge-queues/{id}/pull-requests"

	payload := strings.NewReader("{\n  \"number\": 123,\n  \"allowBatching\": true,\n  \"priorityValue\": 16383,\n  \"priorityName\": \"<string>\",\n  \"direct\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trunk.io/v2/merge-queues/{id}/pull-requests")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"number\": 123,\n  \"allowBatching\": true,\n  \"priorityValue\": 16383,\n  \"priorityName\": \"<string>\",\n  \"direct\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trunk.io/v2/merge-queues/{id}/pull-requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"number\": 123,\n  \"allowBatching\": true,\n  \"priorityValue\": 16383,\n  \"priorityName\": \"<string>\",\n  \"direct\": true\n}"

response = http.request(request)
puts response.read_body

{
  "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "repositoryId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "number": 4901,
  "title": "feat: terminate /v2 at the gateway",
  "branch": "phil/implement-remaining-apis",
  "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
  "baseBranch": "main",
  "author": "octocat",
  "isCurrentlySubmittedToQueue": true,
  "createdAt": "2026-07-28T10:55:00.000Z",
  "url": "https://github.com/acme/widgets/pull/4901",
  "state": "open",
  "queueEntry": {
    "id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "mergeQueueId": "xK9mP2nQ",
    "state": "testing",
    "stateChangedAt": "2026-07-28T11:40:02.000Z",
    "skipsTheLine": false,
    "allowBatching": true,
    "direct": false,
    "readiness": {
      "requiresImpactedTargets": true,
      "doesBaseBranchMatch": true,
      "mergeability": "mergeable",
      "hasImpactedTargets": true,
      "mergeabilityDetails": {
        "provider": "github",
        "reasons": [
          {
            "code": "reviewRequired",
            "message": "needs 1 more approving review",
            "have": 0,
            "need": 1
          }
        ]
      }
    },
    "createdAt": "2026-07-28T11:02:31.000Z",
    "updatedAt": "2026-07-28T11:40:02.000Z",
    "priorityValue": 100,
    "priorityName": "high",
    "usedDefaultPriorityName": "medium",
    "verifiedByVerificationRunId": "a1b2c3d4-e5f6-4718-9a0b-1c2d3e4f5061"
  },
  "htmlUrl": "https://app.trunk.io/acme/pull/4901?repo=1a2b3c4d",
  "viewerIsAuthor": true,
  "ci": {
    "headSha": "a0de7a77e8d758a346f83ed19209a5a25814bb17",
    "observedAt": "2026-09-29T15:12:25.000Z",
    "pollAfterSeconds": 10,
    "jobs": {
      "total": 209,
      "queued": 0,
      "running": 0,
      "passed": 110,
      "failed": 2,
      "cancelled": 0,
      "skipped": 97,
      "abandoned": 0
    },
    "jobsUrl": "/v2/ci-jobs?pullRequestId=0f8fad5b-d9cb-469f-a165-70867728950e&commitSha=a0de7a77e8d758a346f83ed19209a5a25814bb17",
    "workflowRunsUrl": "/v2/ci-workflow-runs?pullRequestId=0f8fad5b-d9cb-469f-a165-70867728950e&commitSha=a0de7a77e8d758a346f83ed19209a5a25814bb17"
  }
}

Authorizations

Authorization

string

header

required

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 merge-queue permissions it holds; a key with none can read merge queues but change nothing. Those permissions scope merge queue only: every key can use the Flaky Tests and Dynamic CI endpoints, including their writes, whatever permissions it holds.

Path Parameters

string

required

The merge queue's id.

Example:

"xK9mP2nQ"

Body

application/json

Omitting allowBatching allows batching. priorityValue and priorityName are mutually exclusive; priorityValue: 0 skips the line. direct sends the pull request directly to the queue past unmet branch protection / failing required checks, merging via Trunk's bypass app (it does not skip the queue's own tests); it needs the Merge PRs with direct to queue permission, and a signed-in user also needs repository-admin permission.

number

integer

required

Required range: x <= 10000000

allowBatching

boolean

priorityValue

integer

Required range: 0 <= x <= 32767

priorityName

string

Minimum string length: 1

direct

boolean

Response

The enqueued pull request

A pull request Trunk has indexed. There is no nested repository object — resolve repositoryId with GET /v2/repositories/{id}.

string

required

Example:

"0f8fad5b-d9cb-469f-a165-70867728950e"

repositoryId

string

required

Example:

"7c9e6679-7425-40de-944b-e07fc1f90ae7"

number

integer

required

Example:

4901

title

string

required

Example:

"feat: terminate /v2 at the gateway"

branch

string

required

Example:

"phil/implement-remaining-apis"

sha

string

required

The head commit of the pull request as Trunk last indexed it. Compare against a verification run's testedPullRequests[].sha to tell whether a run tested the current head or a superseded one — a mismatch means the branch moved after that run started.

Example:

"9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f"

baseBranch

string

required

The branch this pull request targets. Must match the queue's targetBranch to be enqueueable — readiness.doesBaseBranchMatch reports that check.

Example:

"main"

author

string

required

Example:

"octocat"

isCurrentlySubmittedToQueue

boolean

required

True when this pull request's queue entry is non-terminal.

Example:

true

createdAt

string<date-time>

required

Example:

"2026-07-28T10:55:00.000Z"

url

string

Omitted until the provider sync has populated it.

Example:

"https://github.com/acme/widgets/pull/4901"

state

enum<string>

The pull request's state at the provider, as Trunk last indexed it — not its queue state, which is QueueEntry.state.

Available options:

open,

closed,

merged

Example:

"open"

queueEntry

object

A pull request's queue membership. There is at most one ever — re-submitting the same pull request mutates this record rather than adding another.

Show child attributes

htmlUrl

string

The pull request's page in the Trunk web app. Absent when the repository has no keyed organization.

Example:

"https://app.trunk.io/acme/pull/4901?repo=1a2b3c4d"

viewerIsAuthor

boolean

Whether the authenticated user authored this pull request. Provided on the queue pull-request list (GET /merge-queues/{id}/pull-requests); absent elsewhere and when the caller is not a signed-in user.

Example:

true

object | null

CI on the head commit. Null when the repository has no CI data. Absent from lists, from a lookup of more than one pull request, and when the CI read failed.

Show child attributes