View as Markdown

API Usage

Learn how to authenticate and work with the Mergify REST API.


Mergify provides a RESTful API for integrating with your merge queues, CI Insights, and Workflow Automation.

All API requests should be directed to: https://api.mergify.com/v1

The API is entirely documented in the API Reference.

Authenticate to the Mergify API with Mergify credentials, sent as Bearer tokens: Application Keys (created on your dashboard) and Mergify User Tokens (issued by mergify auth login).

To check that a key works and see what it may do, retrieve the application’s information. Any key can call this:

Terminal windowbash
curl -H "Accept: application/json" \
-H "Authorization: Bearer <your-application-key>" \
https://api.mergify.com/v1/application

Response:

json
{
"id": "e155518c-ca1b-443c-9be9-fe90fdab7345",
"name": "merge queue dashboard",
"scope": "custom",
"account_scope": {
"id": 123456,
"login": "Mergifyio"
},
"permissions": {
"merge_queue": "read",
"merge_queue_statistics": "read"
},
"expires_at": "2027-02-10T09:30:00Z"
}

permissions lists what the key holds, resource by resource, with * standing for Every resource; a resource it leaves out is No access unless * covers it. expires_at is when the key stops working, null when it never does.

scope is admin for a key holding exactly Every resource at Read & write, as do the admin keys created before permissions existed; ci for a CI key; custom for any other. In the API Reference, the Admin Application Key and CI Application Key credentials an operation accepts are the admin and ci keys.

Mergify also issues user tokens of its own, recognizable by their mut_ prefix and obtained through the OAuth 2.0 device authorization grant. Run mergify auth login to get one. Send it as a Bearer token, the same way as an application key.

A user token identifies the person it was issued to. It reaches exactly what its owner’s dashboard session reaches, and nothing on GitHub directly, so holding one grants no access its owner does not already have.

Endpoints that return lists of items use cursor-based pagination. Paginated responses include a Link header (RFC 5988) with URLs for navigating between pages.

Query parameters:

  • per_page: Number of items per page, from 1 to 100. Most paginated endpoints default to 10. On others, pagination is opt-in: they have no default and return the whole list in a single response until you pass per_page. Where pagination is opt-in, the endpoint’s entry in the API Reference says so.

  • cursor: Opaque cursor for the current page. Extract this from the Link header; do not construct it manually.

Link header example:

http
Link: <https://api.mergify.com/v1/repos/<owner>/<repository>/logs?cursor=abc&per_page=20>; rel="next",
<https://api.mergify.com/v1/repos/<owner>/<repository>/logs?cursor=def&per_page=20>; rel="prev"

The Link header may include the following relations:

  • next: The next page of results
  • prev: The previous page of results

Each relation appears only when that page exists: next is absent on the last page, prev on the first. The two are independent, and a middle page carries both. When neither applies — a result set that fits on a single page — the Link header is omitted entirely.

To iterate through all pages, follow the rel="next" link until it is no longer present in the response. To get back to the first page, call the endpoint again without a cursor.

Each link carries the query parameters of the request it came from, so following one keeps the filters you set. On an endpoint whose start and end default to a window ending at the current time, the resolved bounds are pinned into the links too: iterating with rel="next" keeps serving the window the first page was built from, instead of resolving a fresh one against a later clock and dropping the oldest items on the way. A bound you passed yourself is echoed back as you sent it.

The API uses standard HTTP status codes to indicate the success or failure of a request.

Status Code Meaning Description
200 OK The request succeeded.
201 Created The resource was created.
204 No Content The request succeeded and the response has no body.
400 Bad Request A field cannot be changed in the resource’s current state, or the record already exists.
401 Unauthorized The application key has expired.
403 Forbidden The credential was refused, or is valid but lacks permission for this resource.
404 Not Found The requested resource does not exist.
409 Conflict The request conflicts with the current state of the resource.
422 Unprocessable Entity The request body or parameters are invalid.

Was this page helpful?