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.
Authentication
Section titled AuthenticationAuthenticate 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).
Using an application key
Section titled Using an application keyTo check that a key works and see what it may do, retrieve the application’s information. Any key can call this:
curl -H "Accept: application/json" \ -H "Authorization: Bearer <your-application-key>" \ https://api.mergify.com/v1/applicationResponse:
{ "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.
Using a Mergify user token
Section titled Using a Mergify user tokenMergify 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.
Pagination
Section titled PaginationEndpoints 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 passper_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 theLinkheader; do not construct it manually.
Link header example:
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 resultsprev: 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.
Error handling
Section titled Error handlingThe 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?
Thanks for your feedback!