Skip to main content
Video tutorial · 1:01

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:

AreaWhat you can do
Merge requestsList merge requests, read one with its policy, decision, change approval and votes, read its timeline, vote, re-scan and resync it
ProjectsList repositories, watch them or put them under change management, run bulk operations, start and read project analyses, export an SBOM
Change policies and approver poolsRead, create, change, reorder and simulate policies; manage approver pools
Config changesRead the control changes that wait for four-eyes review
Companies, people, connectionsRead and change company settings, read the people directory and the connections
VCS operationsMembers, 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)
TrackerProjects, issues, boards and comments of the built-in tracker
AuditThe audit log, the inbound webhook log and the compliance report
InsightsDashboard, DORA metrics, cycle time, bottlenecks, My work, the vulnerability inventory and its exceptions, direct changes, the monitoring report
Delegations, notification deliveries, jobs, healthStand-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:

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 Authorization header, 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 curl requests 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 →

Automate with the API and Service TokensYouTube ↗