---
title: API Usage
description: Integrate with Mergify using its 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"
import Button from '../../components/Button.astro';

Mergify offers a comprehensive RESTful API that facilitates seamless
integration. This API provides access to data and functionalities that can
enhance your Mergify experience.

## API Endpoint

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

The API is entirely documented in the [API reference](/api).

<Button colorScheme="blue" href='/api'>
  API Reference
</Button>

## Authentication

### 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).

#### Prerequisites

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.