API reference

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

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.

All requests must be authenticated by providing the x-api-token header.

Submit a pull request to be tested and merged

post

Authorizations

x-api-token

x-api-tokenstringRequired

Trunk API token - see https://docs.trunk.io/apis#authentication

Body

application/json

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

priorityone ofOptional

string · enumOptional

The priority name to assign to the PR when it begins testing in the queue

Default: mediumExample: highPossible values:

or

numberOptional

The priority number (0 - 255, 0 is the highest) to assign to the PR when it begins testing in the queue

Example: 1

Responses

200

OK

No content

401

Unauthorized

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: 124

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "main",
  "priority": "medium"
}

No content

Get information on a pull request that has been submitted to the queue

post

Authorizations

x-api-token

x-api-tokenstringRequired

Trunk API token - see https://docs.trunk.io/apis#authentication

Body

application/json

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

priorityone ofOptional

string · enumOptional

The priority name to assign to the PR when it begins testing in the queue

Default: mediumExample: highPossible values:

or

numberOptional

The priority number (0 - 255, 0 is the highest) to assign to the PR when it begins testing in the queue

Example: 1

Responses

200

Information on the pull request

application/json

401

Unauthorized

404

Pull request with the provided number does not exist or has never been submitted to the specified queue before

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: 124

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "main",
  "priority": "medium"
}

{
  "id": "1234567890abcdef",
  "state": "PENDING",
  "stateChangedAt": "2021-01-01T00:00:00Z",
  "priorityValue": 100,
  "priorityName": "medium",
  "usedDefaultPriorityName": "medium",
  "skipTheLine": false,
  "isCurrentlySubmittedToQueue": true,
  "readiness": {
    "hasImpactedTargets": false,
    "requiresImpactedTargets": false,
    "doesBaseBranchMatch": true,
    "gitHubMergeability": "MERGEABLE"
  },
  "prNumber": 1,
  "prTitle": "Add new feature",
  "prSha": "1234567890abcdef",
  "prBaseBranch": "main",
  "prAuthor": "dependabot"
}

Restarts tests on a PR in the queue without moving its position or causing other PRs to be retested

post

Authorizations

x-api-token

x-api-tokenstringRequired

Trunk API token - see https://docs.trunk.io/apis#authentication

Body

application/json

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

Responses

200

OK

No content

401

Unauthorized

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: 104

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "main"
}

No content

Cancel a pull request already in the queue.

post

Authorizations

x-api-token

x-api-tokenstringRequired

Trunk API token - see https://docs.trunk.io/apis#authentication

Body

application/json

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

Responses

200

OK

No content

401

Unauthorized

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: 104

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "main"
}

No content

Get information on your merge queue and the PRs currently in it

post

Authorizations

x-api-token

x-api-tokenstringRequired

Trunk API token - see https://docs.trunk.io/apis#authentication

Body

application/json

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

Responses

200

Information on the pull request

application/json

401

Unauthorized

404

Pull request with the provided number does not exist or has never been submitted to the specified queue before

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: 86

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "targetBranch": "main"
}

{
  "state": "RUNNING",
  "branch": "main",
  "concurrency": 1,
  "testingTimeoutMins": 60,
  "mode": "SINGLE",
  "canOptimisticallyMerge": true,
  "pendingFailureDepth": 1,
  "batchingMode": "SPECULATIVE",
  "batchingMaxWaitTimeMins": 60,
  "batchingMinSize": 1,
  "createPrsForTestingBranches": true,
  "enqueuedPullRequests": [
    {
      "id": "1234567890abcdef",
      "state": "PENDING",
      "stateChangedAt": "2021-01-01T00:00:00Z",
      "priorityValue": 100,
      "priorityName": "medium",
      "usedDefaultPriorityName": "medium",
      "skipTheLine": false,
      "prNumber": 1,
      "prTitle": "Add new feature",
      "prSha": "1234567890abcdef",
      "prBaseBranch": "main",
      "prAuthor": "dependabot"
    }
  ]
}

Set impacted targets

post

Upload impacted targets for the PR and its current SHA. Used specifically when running the queue in Parallel mode

Authorizations

x-api-token

x-api-tokenstringRequired

Trunk API token - see https://docs.trunk.io/apis#authentication

Body

application/json

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

impactedTargetsone ofOptional

string[]Optional

Name of the target impacted by the changes in the pull request

Example: services_backend

or

string · enumOptional

Special value to indicate that all targets are impacted by the changes in the pull request

Possible values:

Responses

200

OK

No content

401

Unauthorized

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: 188

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1,
    "sha": "1234567890abcdef"
  },
  "targetBranch": "main",
  "impactedTargets": [
    "services_backend",
    "services_frontend"
  ]
}

No content

Update the merge queue. Currently only supports updating the merge queue state.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

statestring · enumRequiredPossible values:

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: 93

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