canonical: https://jentic.com/apis/mergify.com/mergify # Mergify API The Mergify API controls the Mergify merge queue for GitHub repositories and reports on the CI runs behind it. It reads the live queue status for a branch, dequeues a pull request after previewing the impact, pauses or resumes the queue, and schedules merge freezes with a start, end, and timezone. It also exposes CI Insights: search tests, read a test's failures, executions, and health transitions, and quarantine flaky tests so they stop blocking merges. ## For AI agents Check and steer the Mergify merge queue for a GitHub repository: read queue status, dequeue or pause, schedule freezes, and quarantine flaky tests found through CI Insights. ## Scope Does not host repositories, run CI jobs, or review code. Use for controlling the Mergify merge queue and CI Insights test data only. ## Capabilities - Read the current merge queue status for a branch and inspect a single queued pull request by pr_number - Preview the dequeue impact of a pull request, then remove it from the merge queue - Pause the merge queue with a required reason and resume it when the incident is over - Schedule a merge freeze with reason, start, end, and timezone, then update or delete it - Search CI tests in a repository and read a test's failures, executions, and health transitions - Quarantine a flaky test by test_name and reason, optionally with unquarantine_when_healthy - Pull merge queue statistics such as queue size, failure rate, batch size, and average CI runtime ## Use cases ### Agent-driven merge queue triage through Jentic A coding agent watching a GitHub repository finds that merges have stalled. Through Jentic it calls the Mergify merge-queue status operation for the affected branch, reads the queued pull request that is failing, previews the dequeue impact, and removes it so the rest of the queue can proceed. The Mergify token stays on your own Jentic One instance, and your rules decide whether dequeue is one of the operations the agent may call. Example prompt: Call GET `/repos/acme/web/merge-queue/status` with branch 'main', pick the failing pull request, call GET `/repos/acme/web/merge-queue/pull/412/dequeue-impact`, then POST `/repos/acme/web/merge-queue/pull/412/dequeue` ### Release and holiday merge freezes Teams that stop merging during a release window or holiday can create a scheduled freeze instead of asking everyone to hold off. The create operation requires a reason, a start time, and a timezone, with an optional end and matching_conditions or exclude_conditions to let hotfixes through. Freezes can be listed, updated by freeze_id, and deleted when plans change. Example prompt: POST `/repos/acme/web/scheduled_freeze` with reason 'Q4 release', start '2026-12-20T00:00:00', end '2026-12-27T00:00:00', timezone 'Europe/Dublin' ### Flaky test quarantine Flaky tests make merge queue runs fail for reasons unrelated to the change. With CI Insights an agent searches tests in a repository, reads a suspect test's failures and health transitions, and marks it quarantined with test_name and reason. Setting unquarantine_when_healthy lets the test come back once it stabilises, and the quarantine can be removed by quarantine_id. Example prompt: Call GET `/ci/acme/repositories/web/search/tests` with a test_name filter, read GET `/ci/acme/repositories/web/tests/{test_id}/failures`, then POST `/ci/acme/repositories/web/quarantines` with a test_name filter and reason 'flaky on retry' ### Merge queue health reporting Engineering leads tracking delivery speed can pull merge queue statistics per repository: queue size, failure rate, batch size, checks retries, idle and total queue time, and the CI runs the queue started and wasted. Each statistic accepts base_ref and queue_name filters so a report can isolate one branch or queue. Example prompt: Call GET `/repos/acme/web/stats/failure_rate` and GET `/repos/acme/web/stats/average_ci_runtime` with base_ref 'main' and summarise both for the weekly report ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/repos/{owner}/{repository}/merge-queue/status` | Get the current merge queue status | | POST | `/repos/{owner}/{repository}/merge-queue/pull/{pr_number}/dequeue` | Dequeue a pull request | | PUT | `/repos/{owner}/{repository}/merge-queue/pause` | Pause the merge queue | | POST | `/repos/{owner}/{repository}/scheduled_freeze` | Create a scheduled freeze | | GET | `/ci/{owner}/repositories/{repository}/search/tests` | Search CI tests | | POST | `/ci/{owner}/repositories/{repository}/quarantines` | Quarantine a test | | GET | `/repos/{owner}/{repository}/stats/failure_rate` | Get the queue failure rate | ## Key resources - **Merge queue** — Read status and branches, inspect or dequeue a pull request, and pause or resume the queue - **Scheduled freezes** — Create, list, update, and delete time-boxed merge freezes - **CI Insights tests** — Search tests and read failures, executions, stats, and health transitions - **Quarantines** — Quarantine flaky tests and remove them from quarantine - **Statistics** — Queue size, failure rate, batch size, CI runtime, and queue time metrics ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 62 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 73 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 43 / 100 - Agent Usability: 92 / 100 - Security: 60 / 100 - AI Discoverability: 70 / 100 - **View full report:** https://jentic.com/apis/mergify.com/mergify/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring Mergify by hand means choosing between four bearer credentials (admin key, ci key, Mergify user token, GitHub token) per operation and tracking which queue endpoints are deprecated. Through Jentic you install once, import Mergify from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Mergify puts the owner and repository in the URL path (`/repos/{owner}/{repository}/...`), so a rule can pin your agent to one repository and the operations you pick. You choose the operations it may call, so actions like dequeue, queue pause, or freeze deletion are not included unless you add them. - **Credential handling:** Your Mergify token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'check the merge queue status' or 'quarantine a flaky test', and Jentic returns the matching Mergify operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **GitHub REST API** — The repositories and pull requests Mergify queues live on GitHub - **CircleCI API** — CI pipelines whose checks gate the Mergify merge queue - **Buildkite API** — CI builds and agents that report checks into a merge queue - **GitLab API** — GitLab offers merge trains for repositories hosted on GitLab ## FAQ ### What authentication does the Mergify API use? Per its OpenAPI spec, the Mergify API uses bearer tokens in the Authorization header, with four declared schemes: a Mergify application key with the admin scope (AdminApplicationKey), an application key with the ci scope (CIApplicationKey), a Mergify user token (MergifyTokenBearerAuth, mut_ prefix), and a GitHub user access token (GitHubTokenBearerAuth). Each operation lists which it accepts: most merge queue and CI Insights operations take an admin key, user token, or GitHub token, while the scope-setting operations take the ci key. Through Jentic the token is stored encrypted by your own Jentic One instance and injected when the agent calls. ### Can I quarantine a flaky test with the Mergify API? Yes. POST `/ci/{owner}/repositories/{repository}/quarantines` takes a required test_name and reason, plus optional branch and unquarantine_when_healthy. You can list quarantined tests, read one by quarantine_id, and remove it with DELETE on the same quarantine_id path. ### How do I pause the merge queue through Jentic? Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import the Mergify API from the directory, and store your Mergify token. Your agent then searches 'pause the Mergify merge queue', gets PUT `/repos/{owner}/{repository}/merge-queue/pause` with its schema, and sends the required reason. DELETE on the same path resumes the queue. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the Mergify API? Yes. For example, write a rule that allows GET `/repos/acme/web/merge-queue/status` and the CI Insights test reads under `/ci/acme/repositories/web`, so the agent can diagnose a stalled queue in that one repository but cannot dequeue, pause, or quarantine anything. Add the dequeue operation later if you want it to act, and every call it makes is logged. ### Is there a Mergify MCP server? You don't need an MCP server to give your agent Mergify. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Operations are discovered on demand, so no extra tool definitions sit in the agent's context. ### What are the rate limits for the Mergify API? The OpenAPI spec does not specify rate limits. Check the Mergify API documentation at https://docs.mergify.com/api/usage for current limits. ### Which pause endpoint should I use, queue/pause or merge-queue/pause? Use `/repos/{owner}/{repository}/merge-queue/pause.` The older `/queue/pause` operations are marked deprecated in the spec, as are several older queue and stats endpoints, so new integrations should target the merge-queue paths.