API Usage

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.

The Mergify API supports two authentication methods, both using Bearer tokens: Application Keys (generated from your dashboard) and GitHub Personal Access Tokens.

To start with the API, you’ll first need to create an application associated with your organization:

1. Navigate to your dashboard.
2. Proceed to create an Application.

Upon successful creation, the dashboard will provide you with an API key.

Application keys have different scopes that determine what they can access:

• admin: Full access to all API endpoints, including administrative functions.
• ci: Limited to CI-related operations, such as uploading test results and accessing CI Insights data.

When creating an application key, select the appropriate scope based on your needs. For CI Insights, use a key with the ci scope.

With the provided API key, you’re set to make authenticated requests against the Mergify API. For example, to validate the authenticity of your token, you can retrieve your application’s information:

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

Response:

{
    "id": 123,
    "name": "my application",
    "github_account": {
        "id": 123,
        "login": "Mergify",
        "type": "Organization"
    }
}

As an alternative to application keys, you can authenticate to the Mergify API using a GitHub Personal Access Token (PAT) as a Bearer token. This is useful when integrating with tools that already have a GitHub token available, such as CI environments or the Mergify CLI.

You must have logged in to the Mergify dashboard at least once using GitHub OAuth before using this method. The PAT is only used to verify your GitHub identity — all permissions are based on your Mergify account, not the PAT’s scopes.

Accepted token formats:

• ghp_* — classic personal access tokens
• github_pat_* — fine-grained personal access tokens

Example:

curl -H "Accept: application/json" \
     -H "Authorization: Bearer <github-personal-access-token>" \
     https://api.mergify.com/v1/application

If, for any reason, you need to revoke an application key:

1. Head to the dashboard.
2. Simply delete the corresponding application.

By doing so, the application and its key will be removed, revoking any access provided by that key.

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 (1–100, default: 10)
• cursor — Opaque cursor for the current page. Extract this from the Link header; do not construct it manually.

Link header example:

Link: <https://api.mergify.com/v1/repos/Mergifyio/my-repo/logs?cursor=abc&per_page=20>; rel="next",
  <https://api.mergify.com/v1/repos/Mergifyio/my-repo/logs?cursor=xyz&per_page=20>; rel="last",
  <https://api.mergify.com/v1/repos/Mergifyio/my-repo/logs?cursor=def&per_page=20>; rel="first"

The Link header may include the following relations:

• next — The next page of results
• prev — The previous page of results
• first — The first page of results
• last — The last page of results

To iterate through all pages, follow the rel="next" link until it is no longer present in the response.

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