---
title: API Usage
description: Learn how to authenticate and work with the Mergify REST API.
---

import { Image } from "astro:assets"
import applicationKeysCreate from "../../images/api-intro/application_keys.png"
import applicationKeysToken from "../../images/api-intro/application_keys_token.png"
import applicationKeysDelete from "../../images/api-intro/application_keys_delete.png"

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](/api).

## Authentication

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

### Creating an Application Key

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

1. Navigate to your [dashboard](https://dashboard.mergify.com).
2. Proceed to create an Application.

<Image src={applicationKeysCreate} alt="Create application keys" />

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

<Image src={applicationKeysToken} alt="Application key token" />

### Application Key Scopes

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.

### Using the API Key

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:

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

Response:

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

### Using a GitHub Personal Access Token

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](/stacks).

You must have logged in to
the [Mergify dashboard](https://dashboard.mergify.com) 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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)
- `github_pat_*` — [fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)

Example:

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

:::note
  The PAT is used solely for identity verification. The token's GitHub
  scopes do not affect what you can access in the Mergify API — permissions
  are determined by your Mergify user account and its associated
  organizations.
:::

:::caution
  A small number of endpoints only accept application keys (e.g.,
  CI-specific endpoints). See the [API Reference](/api) for
  details on each endpoint's supported authentication methods.
:::

### Revoking an Application Key

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

1. Head to the [dashboard](https://dashboard.mergify.com).
2. Simply delete the corresponding application.

<Image src={applicationKeysDelete} alt="Delete application key" />

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

## Pagination

Endpoints that return lists of items use cursor-based pagination. Paginated
responses include a `Link` header
([RFC 5988](https://www.rfc-editor.org/rfc/rfc5988)) 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:**

```http
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.

## Error Handling

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. |
| `403` | Forbidden | Authentication is valid but you do not have permission to access 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. |