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.

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

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

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

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

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:

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"
    }
  ]
}

Queue Endpoints

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

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,
      "prNumber": 1,
      "prTitle": "text",
      "prSha": "text",
      "prBaseBranch": "text",
      "prAuthor": "text"
    }
  ]
}

Update the merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

statestring · enumOptionalPossible values:

concurrencyinteger · min: 1 · max: 4294967295Optional

bisectionConcurrencyinteger · min: 1 · max: 4294967295Optional

testingTimeoutMinutesinteger · min: 1 · max: 4294967295Optional

pendingFailureDepthinteger · min: 1 · max: 4294967295Optional

canOptimisticallyMergebooleanOptional

batchbooleanOptional

batchingMaxWaitTimeMinutesinteger · min: 1 · max: 4294967295Optional

batchingMinSizeinteger · 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

/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: 278

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