API examples
These examples show common tasks with curl. Answers are trimmed to the fields that matter; the reference lists every field. IDs, names and dates are made up.
Every example uses two shell variables:
export MP=https://merge-pilot.example.com/api/v1 # your Merge Pilot host + /api/v1
export TOKEN=mpt_... # an API token
Make the token as described in API tokens. Each example says which role it needs; how tokens, roles and companies work is in Authentication.
List merge requests
Any role. The open merge requests, most recently updated first, 50 per page:
curl -s -H "Authorization: Bearer $TOKEN" \
"$MP/merge-requests?state=opened&sort=-updated_at&page_size=50"
{
"success": true,
"data": [
{
"id": "6718f2c4e1a9b3d5f7a10042",
"repo_id": "17",
"mr_number": "42",
"title": "Add rate limiting to the payment API",
"source_branch": "feature/rate-limit",
"target_branch": "main",
"author": "alice",
"state": "opened",
"web_url": "https://gitlab.example.com/acme/payments/-/merge_requests/42",
"policy": { "id": "6718f2c4e1a9b3d5f7a10003", "name": "Production changes", "version": 4, "change_type": "normal" },
"decision": { "gate": "pending", "head_sha": "9f2c1e7a…", "evaluated_at": "2026-10-26T09:10:44.120Z" },
"updated_at": "2026-10-26T09:10:44.120Z"
}
],
"meta": { "page": 1, "page_size": 50, "total": 7 }
}
Other filters: attention=true (only those that cannot move until someone acts), change_type (standard, normal, emergency), repo_id, watched and q. See List merge requests and Merge requests → API.
Read a merge request's decision
Any role. A CI job usually knows the repository's ID on the VCS and the merge request's number, not Merge Pilot's ID. Look the ID up first, then read the merge request:
ID=$(curl -s -H "Authorization: Bearer $TOKEN" \
"$MP/merge-requests/lookup?repo_id=17&mr_number=42" | jq -r .data.id)
curl -s -H "Authorization: Bearer $TOKEN" "$MP/merge-requests/$ID"
The lookup answers {"success": true, "data": {"id": "6718f2c4e1a9b3d5f7a10042"}}, or 404 when Merge Pilot does not know the merge request. Repository IDs are unique per VCS connection only: when your company has several, add connection_id.
{
"success": true,
"data": {
"id": "6718f2c4e1a9b3d5f7a10042",
"state": "opened",
"head_sha": "9f2c1e7a…",
"policy": { "name": "Production changes", "version": 4, "change_type": "normal" },
"decision": {
"head_sha": "9f2c1e7a…",
"target_branch": "main",
"gate": "pending",
"controls": [
{ "control": "ci", "status": "passed", "blocking": true },
{ "control": "secret_scan", "status": "passed", "blocking": true },
{ "control": "approval", "status": "pending", "blocking": true }
],
"evaluated_at": "2026-10-26T09:10:44.120Z",
"needs_change_approval": true
},
"issue_tracker": {
"change_approval_key": "CM-118",
"change_approval_status": "open",
"change_approval_assignee": "bob"
},
"approval": {
"groups": [
{ "requirements": [ { "name": "CAB", "required": 2, "approvers": [] } ], "met": false }
],
"approved": false
}
}
}
decision.gateis the merge gate:approved,pendingorblocked.decision.controls[]has one entry per control (work_items,code_review,ci,secret_scan,sca,licenses,package_health,sources,workflows,signatures,images,iac,risk,freeze,approvalandpolicy), eachpassed,pending,failedorskipped, with thereasonwhen there is one. A control withblocking: falseonly reports.issue_trackeris the change approval,approvalits approval groups and votes.
The decision is for decision.head_sha: when it differs from the merge request's head_sha, a newer commit has not been evaluated yet.
Vote on a change approval
Voting acts as a person, so it needs a personal token (a service token is answered 403, see What a service token may not do). The person must be allowed to vote on this change: an approver under the policy, not the author, with their account on the merge request's VCS linked in My profile (see Who may vote).
curl -s -X POST -H "Authorization: Bearer $PERSONAL_TOKEN" -H "Content-Type: application/json" \
-d '{"decision": "approve", "comment": "Rollout plan reviewed"}' \
"$MP/merge-requests/$ID/votes"
decision is approve or reject. A rejection needs a comment of at least 5 characters; a comment is at most 2,000 characters. The answer is the merge request after the vote:
{
"success": true,
"data": {
"id": "6718f2c4e1a9b3d5f7a10042",
"approval": {
"votes": [
{
"voter": "carol",
"user_id": "6718f2c4e1a9b3d5f7a10077",
"source": "merge_pilot",
"decision": "approve",
"comment": "Rollout plan reviewed",
"change_approval_key": "CM-118",
"at": "2026-10-26T09:31:02.481Z"
}
],
"approved": false
}
}
}
When the votes fill the approvals needed (or someone rejects), the change approval is decided and the merge request is evaluated again. Refusals:
| Status | When |
|---|---|
400 | decision is neither approve nor reject, or a rejection's comment is too short |
403 | A service token or an auditor; no linked VCS account; the voter wrote the change or is not an approver; separation of duties does not let them approve |
409 | No change approval to vote on, the merge request is closed, or the change approval is already decided |
Each vote is audited as change_approval_vote. See Approving and rejecting for how votes are counted.
Export the compliance report
Company admins and auditors (a service token with one of these roles). The report as CSV for October 2026, by merge date:
curl -s -H "Authorization: Bearer $TOKEN" -D headers.txt -o compliance.csv \
"$MP/compliance/report?format=csv&from=2026-10-01&to=2026-10-31"
| Parameter | Values |
|---|---|
format | csv (default) or pdf |
from, to | A day (2026-10-01) in the company's time zone, or an RFC 3339 time. to includes that whole day. Default: the last 30 days |
date_basis | merged_at (default) or opened_at: which date of a merge request puts it in the period |
The answer is the file, with headers that tell whether a section was cut at its limit:
HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="compliance-report-acme-2026-10-01-to-2026-10-31.csv"
X-Report-Truncated:
X-Report-Total-MRs: 412
X-Report-Returned-MRs: 412
X-Report-Total-Audit-Entries: 3180
X-Report-Returned-Audit-Entries: 3180
X-Report-Total-Direct-Changes: 3
X-Report-Returned-Direct-Changes: 3
X-Report-Truncated names the sections that were cut (merge_requests, audit_entries, direct_changes), empty when none was. If it is not empty, export shorter periods. The export is audited as compliance_export. The file's contents and limits are described in Compliance report.
List vulnerabilities
Company admins, policy managers and auditors. The inventory is per company, so first read your company's ID (a token sees only its own company):
COMPANY=$(curl -s -H "Authorization: Bearer $TOKEN" "$MP/companies" | jq -r '.data[0].id')
curl -s -H "Authorization: Bearer $TOKEN" \
"$MP/companies/$COMPANY/vulnerabilities?severity=high&kev=true&sort=-epss"
This lists open findings of severity high or critical that are known to be exploited (CISA KEV), the most likely to be exploited first:
{
"success": true,
"data": [
{
"id": "6718f2c4e1a9b3d5f7a10120",
"project_id": "6718f2c4e1a9b3d5f7a10010",
"project_path": "acme/payments",
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20",
"manifests": ["package-lock.json"],
"direct": true,
"advisory": {
"id": "GHSA-35jh-r3h4-6jhm",
"aliases": ["CVE-2021-23337"],
"severity": "high",
"fixed_in": "4.17.21",
"kev": true,
"epss": 0.012
},
"has_fix": true,
"status": "open",
"source": "analysis",
"first_seen_at": "2026-10-02T07:41:10.000Z",
"last_seen_at": "2026-10-26T06:00:12.000Z"
}
],
"meta": { "page": 1, "page_size": 20, "total": 1 }
}
status defaults to open (open without an exception); excepted, fixed and all are the others. More filters: project_id, ecosystem, scope, direct, has_fix, malicious, introduced_by, from_merge, new, source, since, until and q. The same list as a file is GET /companies/{id}/vulnerabilities.csv. See Vulnerability inventory → API.
Start a project analysis
Company admins. Find the project's Merge Pilot ID, start the analysis, then read it until it has finished:
PROJECT=$(curl -s -H "Authorization: Bearer $TOKEN" "$MP/projects?q=payments" | jq -r '.data[0].id')
curl -s -X POST -H "Authorization: Bearer $TOKEN" "$MP/projects/$PROJECT/analysis"
The analysis runs in the background. The answer is 202 with it:
{
"success": true,
"data": {
"id": "6718f2c4e1a9b3d5f7a10200",
"project_id": "6718f2c4e1a9b3d5f7a10010",
"status": "running",
"triggered_by": "token:nightly-scan",
"started_at": null,
"created_at": "2026-10-26T10:02:11.904Z"
}
}
Read the latest analysis until status is completed or failed:
curl -s -H "Authorization: Bearer $TOKEN" "$MP/projects/$PROJECT/analysis" \
| jq '.data | {status, total_deps, total_vulns, new_findings, fixed_findings, error, error_code}'
{ "status": "completed", "total_deps": 812, "total_vulns": 5, "new_findings": 1, "fixed_findings": 2, "error": null, "error_code": null }
A new analysis is refused with 429 while one runs and for 5 minutes after the last one ended, unless it failed with error_code: TRANSIENT; 409 means another request started one at the same moment. Starting one is audited as analysis_triggered. See Project analysis.
Receive and verify an outbound webhook
A notification route with the Webhook channel sends events to your endpoint as signed JSON POST requests. Setting one up, the payload fields and the events are described in Outbound webhooks. A request looks like this:
POST /merge-pilot-events HTTP/1.1
Content-Type: application/json
User-Agent: Merge-Pilot-Webhook
X-MergePilot-Event: mr_merged_without_approval
X-MergePilot-Delivery: 6718f2c4e1a9b3d5f7a10300
X-MergePilot-Timestamp: 1793006043
X-MergePilot-Signature: sha256=5d0c3f…
{"company_id":"6718f2c4e1a9b3d5f7a10001","data":{"actor":"alice","company":"acme","message":"MR !42 (acme/payments) was merged by alice without change-management approval","mr_id":"6718f2c4e1a9b3d5f7a10003","mr_number":"42","project":"acme/payments","repo_id":"17","title":"MR merged without approval","url":"https://merge-pilot.example.com/merge-requests/6718f2c4e1a9b3d5f7a10003","vcs_connection_id":"6718f2c4e1a9b3d5f7a10002"},"event":"mr_merged_without_approval","occurred_at":"2026-10-26T09:14:03.512345Z"}
The signature is the HMAC-SHA256, keyed with the route's signing secret, of the timestamp header, a dot and the raw body. To check a saved request from the shell (the body saved byte for byte as body.json):
TS=1793006043 # the X-MergePilot-Timestamp header
SECRET='the route signing secret'
echo "sha256=$( { printf '%s.' "$TS"; cat body.json; } | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')"
The output must equal the X-MergePilot-Signature header. In your endpoint:
- Compute the signature over the raw body before parsing the JSON, and compare it in constant time.
- Refuse a timestamp more than a few minutes away from your clock.
- Use
X-MergePilot-Deliveryto ignore a delivery you have already handled: it stays the same on every retry. - Answer any
2xxwithin 10 seconds. Anything else is retried.
A Python version and the full rules are in Outbound webhooks → Verifying a request.
Related pages
- REST API and the reference.
- Authentication: tokens, what they may not do, the company.
- Conventions: envelope, pagination, errors, rate limits.