From 91ad13dc2c132e6ebd719de2693db7c5b34e6ae0 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 13:56:55 -0800 Subject: [PATCH 1/2] Improve Merge Queue API reference with examples and cross-links Rewrites the API reference with better structure, common request fields docs, descriptive section intros, and practical curl examples for all endpoint categories. Adds cross-references between API reference, settings page, and submit/cancel page. Co-Authored-By: Claude Opus 4.6 --- merge-queue/reference/merge.md | 237 ++++++++++++++++++++++- merge-queue/using-the-queue/reference.md | 2 + setup-and-administration/apis/README.md | 2 +- 3 files changed, 230 insertions(+), 11 deletions(-) diff --git a/merge-queue/reference/merge.md b/merge-queue/reference/merge.md index caad570b..078b6408 100644 --- a/merge-queue/reference/merge.md +++ b/merge-queue/reference/merge.md @@ -4,11 +4,36 @@ description: Public Trunk Merge Queue API. All requests should be authenticated. # API reference -The Trunk Merge Queue API provides access to submit PRs for testing and merging, canceling PRs, and providing extra information to optimize the queue. The API is an HTTP REST API, returns JSON from all requests, and uses standard HTTP response codes. +The Trunk Merge Queue API provides programmatic access to manage your merge queues and the pull requests within them. Use these endpoints to submit and cancel PRs, configure queue settings, and build custom automation on top of Trunk Merge Queue. + +The API is an HTTP REST API. All endpoints accept and return JSON, use standard HTTP response codes, and are hosted at `https://api.trunk.io/v1`. All requests must be [authenticated](../../setup-and-administration/apis/#authentication) by providing the `x-api-token` header. -## Pull Request Endpoints +## Common request fields + +Most endpoints require a `repo` object and a `targetBranch` to identify which merge queue to operate on: + +```json +{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "targetBranch": "main" +} +``` + +*** + +## Pull request endpoints + +Use these endpoints to submit PRs to the queue, cancel them, check their status, restart tests, and provide impacted target information for parallel mode. + +{% openapi-operation spec="trunk-api" path="/submitPullRequest" method="post" %} +[OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) +{% endopenapi-operation %} {% openapi-operation spec="trunk-api" path="/cancelPullRequest" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) @@ -26,28 +51,220 @@ All requests must be [authenticated](../../setup-and-administration/apis/#authen [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} -{% openapi-operation spec="trunk-api" path="/submitPullRequest" method="post" %} -[OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) -{% endopenapi-operation %} - {% openapi-operation spec="trunk-api" path="/getMergeQueueTestingDetails" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} -## Queue Endpoints +
+ +Example: 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: YOUR_API_TOKEN" \ + -d '{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "targetBranch": "main", + "prNumber": 1234 + }' +``` + +
+ +
+ +Example: Cancel a PR in the queue + +```bash +curl -X POST https://api.trunk.io/v1/cancelPullRequest \ + -H "Content-Type: application/json" \ + -H "x-api-token: YOUR_API_TOKEN" \ + -d '{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "targetBranch": "main", + "prNumber": 1234 + }' +``` + +
+ +*** + +## Queue management endpoints + +Use these endpoints to create, configure, inspect, and delete merge queues programmatically. This is useful for automating queue management across multiple repositories, scripting queue configuration as part of infrastructure-as-code workflows, or building custom tooling on top of Trunk Merge Queue. + +{% hint style="info" %} +Queue management endpoints perform the same operations available in the Trunk web app under **Settings > Repositories > Merge Queue**. See [Settings and configurations](../administration/advanced-settings.md) for details on each setting. +{% endhint %} {% openapi-operation spec="trunk-api" path="/createQueue" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} -{% openapi-operation spec="trunk-api" path="/deleteQueue" method="post" %} +{% openapi-operation spec="trunk-api" path="/getQueue" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} -{% openapi-operation spec="trunk-api" path="/getQueue" method="post" %} +{% openapi-operation spec="trunk-api" path="/updateQueue" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} -{% openapi-operation spec="trunk-api" path="/updateQueue" method="post" %} +{% openapi-operation spec="trunk-api" path="/deleteQueue" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} + +
+ +Example: Create a new queue + +```bash +curl -X POST https://api.trunk.io/v1/createQueue \ + -H "Content-Type: application/json" \ + -H "x-api-token: YOUR_API_TOKEN" \ + -d '{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "targetBranch": "main", + "mode": "single", + "concurrency": 5 + }' +``` + +
+ +
+ +Example: Get current queue status and enqueued PRs + +```bash +curl -X POST https://api.trunk.io/v1/getQueue \ + -H "Content-Type: application/json" \ + -H "x-api-token: YOUR_API_TOKEN" \ + -d '{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "targetBranch": "main" + }' +``` + +The response includes the queue configuration and a list of all enqueued PRs with their current state: + +```json +{ + "state": "RUNNING", + "branch": "main", + "concurrency": 5, + "testingTimeoutMins": 300, + "mode": "SINGLE", + "canOptimisticallyMerge": false, + "pendingFailureDepth": 0, + "isBatching": false, + "batchingMaxWaitTimeMins": 0, + "batchingMinSize": 0, + "createPrsForTestingBranches": true, + "enqueuedPullRequests": [ + { + "state": "TESTING", + "stateChangedAt": "2025-01-15T10:30:00Z", + "priorityValue": 100, + "priorityName": "default", + "skipTheLine": false, + "prNumber": 1234, + "prTitle": "Add user authentication", + "prSha": "abc123", + "prBaseBranch": "main", + "prAuthor": "octocat" + } + ] +} +``` + +
+ +
+ +Example: Pause the queue (e.g., during a CI outage) + +```bash +curl -X POST https://api.trunk.io/v1/updateQueue \ + -H "Content-Type: application/json" \ + -H "x-api-token: YOUR_API_TOKEN" \ + -d '{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "targetBranch": "main", + "state": "PAUSED" + }' +``` + +
+ +
+ +Example: Update queue settings (concurrency, batching, timeouts) + +```bash +curl -X POST https://api.trunk.io/v1/updateQueue \ + -H "Content-Type: application/json" \ + -H "x-api-token: YOUR_API_TOKEN" \ + -d '{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "targetBranch": "main", + "concurrency": 10, + "testingTimeoutMinutes": 120, + "pendingFailureDepth": 2, + "canOptimisticallyMerge": true, + "batch": true, + "batchingMinSize": 3, + "batchingMaxWaitTimeMinutes": 15 + }' +``` + +
+ +
+ +Example: Delete a queue + +{% hint style="warning" %} +The queue must be empty before it can be deleted. Any queued merge requests will not be merged and all data will be lost. +{% endhint %} + +```bash +curl -X POST https://api.trunk.io/v1/deleteQueue \ + -H "Content-Type: application/json" \ + -H "x-api-token: YOUR_API_TOKEN" \ + -d '{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "targetBranch": "main" + }' +``` + +
diff --git a/merge-queue/using-the-queue/reference.md b/merge-queue/using-the-queue/reference.md index e9544698..14608237 100644 --- a/merge-queue/using-the-queue/reference.md +++ b/merge-queue/using-the-queue/reference.md @@ -20,6 +20,8 @@ trunk login trunk merge ``` +* Using the [Merge Queue API](../reference/merge.md#pull-request-endpoints) to submit PRs programmatically from custom tooling or CI scripts. + We offer similar commands for cancellation. * Posting a GitHub comment `/trunk cancel` on a pull request. diff --git a/setup-and-administration/apis/README.md b/setup-and-administration/apis/README.md index fe45dad4..ee05c54d 100644 --- a/setup-and-administration/apis/README.md +++ b/setup-and-administration/apis/README.md @@ -11,7 +11,7 @@ Trunk provides HTTP REST APIs for each of our features. The APIs use status code ## Available APIs * [Flaky Tests](../../flaky-tests/flaky-tests.md): for accessing information like quarantined tests in your repo. -* [Merge API](../../merge-queue/reference/merge.md) : for controlling the Trunk Merge Queue. +* [Merge API](../../merge-queue/reference/merge.md): for submitting and managing PRs in the merge queue, and for creating, configuring, and deleting merge queues programmatically. ## Authentication From 2f379064c227704bec70e14b97ceddebdab5c64d Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 20:09:06 -0800 Subject: [PATCH 2/2] Add endpoint summary table, common use cases, and auth docs to API reference Enhances the Merge Queue API reference page with a quick-reference endpoint summary table, common use cases section, forked PR authentication guidance, additional curl examples for PR status checks, and a related resources section linking to CLI reference, parallel queues, webhooks, and settings docs. Co-Authored-By: Claude Opus 4.6 --- merge-queue/reference/merge.md | 133 ++++++++++++++++++++++++++++++--- 1 file changed, 122 insertions(+), 11 deletions(-) diff --git a/merge-queue/reference/merge.md b/merge-queue/reference/merge.md index 078b6408..14b93a1e 100644 --- a/merge-queue/reference/merge.md +++ b/merge-queue/reference/merge.md @@ -8,7 +8,7 @@ The Trunk Merge Queue API provides programmatic access to manage your merge queu The API is an HTTP REST API. All endpoints accept and return JSON, use standard HTTP response codes, and are hosted at `https://api.trunk.io/v1`. -All requests must be [authenticated](../../setup-and-administration/apis/#authentication) by providing the `x-api-token` header. +All requests must be [authenticated](../../setup-and-administration/apis/#authentication) by providing the `x-api-token` header. You can also manage your queue using the [CLI](merge-queue-cli-reference.md) or the [Trunk App](https://app.trunk.io). ## Common request fields @@ -25,32 +25,92 @@ Most endpoints require a `repo` object and a `targetBranch` to identify which me } ``` +## Endpoint summary + +### Pull request endpoints + +| Endpoint | Description | +| --- | --- | +| [POST /submitPullRequest](#submit-a-pull-request) | Submit a PR to the merge queue | +| [POST /cancelPullRequest](#cancel-a-pull-request) | Cancel a PR in the merge queue | +| [POST /getSubmittedPullRequest](#get-a-submitted-pull-request) | Get the status of a submitted PR | +| [POST /restartTestsOnPullRequest](#restart-tests-on-a-pull-request) | Restart tests on a PR in the queue | +| [POST /setImpactedTargets](#set-impacted-targets) | Set impacted targets for parallel queues | +| [POST /getMergeQueueTestingDetails](#get-merge-queue-testing-details) | Get testing run details and check statuses | + +### Queue management endpoints + +| Endpoint | Description | +| --- | --- | +| [POST /getQueue](#get-the-queue) | Get queue configuration and enqueued PRs | +| [POST /createQueue](#create-a-queue) | Create a new merge queue | +| [POST /updateQueue](#update-the-queue) | Update queue settings (pause, resume, configure) | +| [POST /deleteQueue](#delete-a-queue) | Delete an empty merge queue | + +## Common use cases + +**CI/CD automation** — Use `/submitPullRequest` and `/cancelPullRequest` to integrate merge queue operations into your CI pipelines or custom merge bots. + +**Monitoring dashboards** — Use `/getQueue` and `/getSubmittedPullRequest` to build real-time visibility into queue health and individual PR status. + +**Queue state management** — Use `/updateQueue` with the `state` field to pause, resume, or drain your queue during incidents, deployments, or maintenance windows. Supported states: `RUNNING`, `PAUSED`, `DRAINING`. See [queue states](../administration/advanced-settings.md) for details. + +**Parallel queue configuration** — Use `/setImpactedTargets` to define which targets a PR affects so the queue can test non-overlapping changes simultaneously. See [parallel queues](../optimizations/parallel-queues/) for setup details. + +**Test monitoring** — Use `/getMergeQueueTestingDetails` to inspect which checks are running, their current status, and which PRs are being tested together in a batch. + +## Authentication + +All requests require an API token passed in the `x-api-token` header. Find your token in the [Trunk App](https://app.trunk.io). See the [authentication guide](../../setup-and-administration/apis/#authentication) for full details. + +{% hint style="info" %} +**Forked pull requests:** Workflows from forked PRs may not have access to your organization's API token. In this case, pass the GitHub Actions run ID as the `x-forked-workflow-run-id` header instead of `x-api-token`. Trunk verifies the run ID belongs to a currently running workflow from a forked PR. See the [parallel queues API guide](../optimizations/parallel-queues/api.md) for details. +{% endhint %} + *** ## Pull request endpoints Use these endpoints to submit PRs to the queue, cancel them, check their status, restart tests, and provide impacted target information for parallel mode. +### Submit a pull request + {% openapi-operation spec="trunk-api" path="/submitPullRequest" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} +### Cancel a pull request + {% openapi-operation spec="trunk-api" path="/cancelPullRequest" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} +### Get a submitted pull request + +Use this endpoint to check whether a PR is currently in the queue, its testing state, readiness status, and priority. + {% openapi-operation spec="trunk-api" path="/getSubmittedPullRequest" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} +### Restart tests on a pull request + {% openapi-operation spec="trunk-api" path="/restartTestsOnPullRequest" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} +### Set impacted targets + +Used with [parallel queues](../optimizations/parallel-queues/) to specify which targets a PR impacts, enabling non-overlapping PRs to be tested simultaneously. See the [custom build systems guide](../optimizations/parallel-queues/api.md) for implementation details. + {% openapi-operation spec="trunk-api" path="/setImpactedTargets" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} +### Get merge queue testing details + +Returns detailed information about a specific test run, including required status checks, the test branch, check suite results, and which PRs are being tested together. + {% openapi-operation spec="trunk-api" path="/getMergeQueueTestingDetails" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} @@ -69,8 +129,10 @@ curl -X POST https://api.trunk.io/v1/submitPullRequest \ "owner": "your-org", "name": "your-repo" }, - "targetBranch": "main", - "prNumber": 1234 + "pr": { + "number": 1234 + }, + "targetBranch": "main" }' ``` @@ -78,6 +140,31 @@ curl -X POST https://api.trunk.io/v1/submitPullRequest \
+Example: Check PR status in the queue + +```bash +curl -X POST https://api.trunk.io/v1/getSubmittedPullRequest \ + -H "Content-Type: application/json" \ + -H "x-api-token: YOUR_API_TOKEN" \ + -d '{ + "repo": { + "host": "github.com", + "owner": "your-org", + "name": "your-repo" + }, + "pr": { + "number": 1234 + }, + "targetBranch": "main" + }' +``` + +The response includes the PR state (`NOT_READY`, `PENDING`, `TESTING`, `TESTS_PASSED`, `MERGED`, `FAILED`, `CANCELLED`, `PENDING_FAILURE`), readiness information, and priority details. + +
+ +
+ Example: Cancel a PR in the queue ```bash @@ -90,8 +177,10 @@ curl -X POST https://api.trunk.io/v1/cancelPullRequest \ "owner": "your-org", "name": "your-repo" }, - "targetBranch": "main", - "prNumber": 1234 + "pr": { + "number": 1234 + }, + "targetBranch": "main" }' ``` @@ -107,18 +196,34 @@ Use these endpoints to create, configure, inspect, and delete merge queues progr Queue management endpoints perform the same operations available in the Trunk web app under **Settings > Repositories > Merge Queue**. See [Settings and configurations](../administration/advanced-settings.md) for details on each setting. {% endhint %} -{% openapi-operation spec="trunk-api" path="/createQueue" method="post" %} +### Get the queue + +Returns the queue configuration and all currently enqueued pull requests with their states. + +{% openapi-operation spec="trunk-api" path="/getQueue" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} -{% openapi-operation spec="trunk-api" path="/getQueue" method="post" %} +### Create a queue + +{% openapi-operation spec="trunk-api" path="/createQueue" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} +### Update the queue + +Use this endpoint to change queue configuration or manage queue state. To pause the queue, set `state` to `PAUSED`. To resume, set it to `RUNNING`. To drain (finish current PRs but accept no new ones), set it to `DRAINING`. + {% openapi-operation spec="trunk-api" path="/updateQueue" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} +### Delete a queue + +{% hint style="warning" %} +The queue must be empty before it can be deleted. Any queued merge requests will not be merged and all data will be lost. +{% endhint %} + {% openapi-operation spec="trunk-api" path="/deleteQueue" method="post" %} [OpenAPI trunk-api](https://static.trunk.io/docs/openapi.json) {% endopenapi-operation %} @@ -249,10 +354,6 @@ curl -X POST https://api.trunk.io/v1/updateQueue \ Example: Delete a queue -{% hint style="warning" %} -The queue must be empty before it can be deleted. Any queued merge requests will not be merged and all data will be lost. -{% endhint %} - ```bash curl -X POST https://api.trunk.io/v1/deleteQueue \ -H "Content-Type: application/json" \ @@ -268,3 +369,13 @@ curl -X POST https://api.trunk.io/v1/deleteQueue \ ```
+ +*** + +## Related resources + +- [CLI reference](merge-queue-cli-reference.md) — Manage the queue from the command line +- [Parallel queues API](../optimizations/parallel-queues/api.md) — Impacted targets setup for custom build systems +- [Webhooks](../webhooks.md) — Subscribe to merge queue events +- [Queue settings](../administration/advanced-settings.md) — Configure queue behavior in the Trunk App +- [Authentication](../../setup-and-administration/apis/) — API token setup and management