REST API
The Merge Pilot REST API lets programs read and act on what Merge Pilot keeps: CI jobs that read a merge request's decision, scripts that export the compliance report, tools that feed the vulnerability inventory into another system. Programs authenticate with API tokens.
What it covers
The reference groups the endpoints by area:
| Area | What you can do |
|---|---|
| Merge requests | List merge requests, read one with its policy, decision, change approval and votes, read its timeline, vote, re-scan and resync it |
| Projects | List repositories, watch them or put them under change management, run bulk operations, start and read project analyses, export an SBOM |
| Change policies and approver pools | Read, create, change, reorder and simulate policies; manage approver pools |
| Config changes | Read the control changes that wait for four-eyes review |
| Companies, people, connections | Read and change company settings, read the people directory and the connections |
| VCS operations | Members, groups, CI/CD variables, branches and branch protection on the VCS, done through Merge Pilot with the connection's account. CI/CD variables (with secrets, environments and organization variables), joining and leaving repositories, listing branches and branch protection (GitHub: one ruleset per protected branch) on GitLab and GitHub; groups on GitLab (see VCS connection settings) |
| Tracker | Projects, issues, boards and comments of the built-in tracker |
| Audit | The audit log, the inbound webhook log and the compliance report |
| Insights | Dashboard, DORA metrics, cycle time, bottlenecks, My work, the vulnerability inventory and its exceptions, direct changes, the monitoring report |
| Delegations, notification deliveries, jobs, health | Stand-ins, the delivery history of notification routes, background jobs and health checks |
Some requests need a person signed in and refuse API tokens (users, sign-in settings, identity providers, token management and other security settings): see Authentication. They are not in the reference, and neither are the endpoints of the browser sign-in flow: API tokens cannot call them, so an integration has no use for them.
Base URL
Every endpoint is under /api/v1 on your Merge Pilot host:
https://<your-host>/api/v1
For example, https://merge-pilot.example.com/api/v1/merge-requests. Paths in the reference and on these pages are relative to this base URL unless they start with /api/v1 themselves.
Two probes are outside /api/v1 and need no authentication: https://<your-host>/healthz answers 200 while Merge Pilot is running, and https://<your-host>/readyz answers 200 when it is ready to serve requests and 503 when it is not.
The probes do not tell which release is running. GET /api/v1/version does, for any signed-in account or API token.
Versioning
The version is part of the path. v1 is the only version, and every endpoint is under /api/v1. There is no version header and no version in the media type: requests and answers are plain application/json (reports and exports are files, see Conventions).
The reference on this site describes the API of the current Merge Pilot release.
The reference
The API reference lists every endpoint an API token can call, with its parameters, request body, answers and status codes, generated from Merge Pilot's OpenAPI 3.1 description. Start with:
- List merge requests and Get a merge request
- Vote on a merge request
- Export the compliance report
- List vulnerabilities
- The outbound webhook Merge Pilot sends to your endpoint (its payload is under Webhooks in the reference)
Download the OpenAPI description
The OpenAPI 3.1 description is available as one file: openapi.json. It describes the same endpoints as the reference. Open it in any OpenAPI viewer or generate a client from it. Its server URL is https://<your-host>/api/v1: replace <your-host> with your Merge Pilot host.
Next
- Authentication: tokens, the
Authorizationheader, what a token may not do, choosing the company. - Conventions: the response envelope, pagination, sorting, errors and status codes, rate limits, timestamps and IDs.
- Examples: worked
curlrequests with their answers.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →