Skip to main content

Merge Pilot REST API reference

Every endpoint of the Merge Pilot REST API, with its parameters, request and response schemas and examples. Programs authenticate with an API token sent as a bearer token. Start with the overview, authentication, conventions and examples, or download the OpenAPI document.

Authentication

  • GET /auth/me — The signed-in account
  • PUT /auth/me — Change own display name or language
  • GET /auth/me/sso — My identity providers

Merge requests

  • GET /merge-requests — List merge requests
  • POST /merge-requests/fetch — Process a merge request by its number
  • GET /merge-requests/lookup — Find a merge request's ID by repository and number
  • POST /merge-requests/sync-states — Queue a background re-read of the open merge requests' state from the VCS
  • GET /merge-requests/{id} — Get a merge request with its decision and approval state
  • GET /merge-requests/{id}/timeline — Jobs and audit entries of a merge request, newest first
  • POST /merge-requests/{id}/votes — Approve or reject the merge request's change approval
  • POST /merge-requests/{id}/rejection/withdraw — Withdraw a rejection of the change approval
  • POST /merge-requests/{id}/freeze-release — Let one held change go ahead during a change freeze
  • POST /merge-requests/{id}/risk-allow — Accept the risk of a risk-blocked merge request
  • POST /merge-requests/{id}/rescan — Run a scan of the merge request again
  • POST /merge-requests/{id}/resync — Re-read CI and change approval state and process the merge request again
  • POST /merge-requests/{id}/assign-me — Take the change approval
  • POST /merge-requests/{id}/work-items/{key}/reset-usage — Restart a work item's usage count

Projects

  • GET /projects — List registered projects
  • GET /projects/search — Search the connection's VCS for repositories to put under change management
  • GET /projects/by-repo-id/{repo_id} — Get a project by VCS repository ID
  • GET /projects/{id} — Get a project
  • GET /projects/summary — How many projects the filters match, per connection and mode
  • POST /projects/cm-setup — Put a repository under change management, or set it up again
  • POST /projects/cm-remove — Take a repository out of change management
  • GET /projects/cm-status — Whether each agreed setup step is in place, read live from the VCS
  • GET /projects/bulk — The company's recent bulk operations
  • POST /projects/bulk — Start a bulk operation on a connection's repositories
  • GET /projects/bulk/{op} — A bulk operation and a page of its repositories
  • POST /projects/bulk/{op}/cancel — Cancel a bulk operation
  • POST /projects/bulk/{op}/retry-failed — Start an operation over another's failed repositories
  • POST /projects/bulk/{op}/revert-done — Move another operation's done repositories back
  • GET /projects/watchable — List the repositories a connection can watch
  • PUT /projects/{id}/mode — Move a project between watching and change management
  • PUT /projects/{id}/branches — Set the project's target and excluded branches
  • PUT /projects/{id}/push-ignore — Set the logins whose pushes to the project are not recorded
  • POST /projects/{id}/unwatch — Stop watching a project
  • POST /projects/{id}/forget — Take a repository out of Merge Pilot without touching the VCS
  • POST /projects/{id}/import-history — Import a watched project's past merge requests again
  • GET /projects/{id}/mode-impact — The open merge requests and what change management would decide for them
  • PUT /projects/{id}/sca-exclude — Set the manifest paths the project's analysis skips
  • GET /projects/{id}/analysis — The project's latest analysis
  • POST /projects/{id}/analysis — Analyse the project's default branch now
  • GET /projects/{id}/analysis/history — The project's analyses, newest first
  • GET /projects/{id}/analysis/{aid} — One of the project's analyses
  • GET /projects/{id}/analysis/{aid}/details — What an analysis found - dependencies, vulnerabilities, licenses
  • GET /projects/{id}/analysis/{aid}/diff — The vulnerabilities an analysis found new or fixed
  • GET /projects/{id}/sbom — The project's software bill of materials
  • PUT /projects/{id}/tracker-override — Set the project's own change approval project key, issue type and link type
  • PUT /projects/{id}/vcs-settings — Set the project's own approver roles
  • POST /projects/evidence — What was recorded while projects were watched
  • GET /projects/background — What the company's background work has still to do

Change policies

  • GET /policy-templates — Built-in policy templates
  • GET /companies/{id}/policies — List a VCS connection's policies, in order
  • POST /companies/{id}/policies — Create a policy
  • POST /companies/{id}/policies/match — Which policy applies to a described change, and why the ones above it do not
  • GET /companies/{id}/policies/reevaluation — Open merge requests still to be evaluated under changed policies
  • GET /companies/{id}/policies/warnings — Policies that are never reached, or that match on the diff
  • POST /companies/{id}/policies/simulate — Evaluate a merge request against the stored or a draft policy set
  • PUT /companies/{id}/policies/reorder — Reorder a connection's policies
  • POST /companies/{id}/policies/templates/{key} — Apply a policy template to a connection
  • PUT /companies/{id}/policies/{policyId} — Update a policy
  • DELETE /companies/{id}/policies/{policyId} — Delete a policy
  • GET /companies/{id}/policies/{policyId}/versions — A policy's saved versions

Approver pools

  • GET /companies/{id}/approver-pools — List approver pools
  • POST /companies/{id}/approver-pools — Create an approver pool
  • PUT /companies/{id}/approver-pools/{poolId} — Update an approver pool
  • DELETE /companies/{id}/approver-pools/{poolId} — Delete an approver pool
  • GET /companies/{id}/approver-pools/{poolId}/versions — A pool's saved versions

Config changes

  • GET /governance/topics — What waits for a second administrator when control changes are reviewed
  • GET /companies/{id}/config-changes — List control changes waiting for (or decided by) review

Companies

  • GET /companies/{id}/setup-status — How far the company is set up (the setup checklist)
  • GET /companies — List companies
  • GET /companies/{id} — Get a company
  • PUT /companies/{id} — Update company settings
  • GET /companies/{id}/risk-config/versions — Saved versions of the company's risk settings
  • GET /companies/{id}/sca-results/{resultId} — Full dependency scan result
  • GET /companies/{id}/image-scan-results/{resultId} — Full container image scan result

People

  • GET /users/directory — The company's people (for picking pool members)

Connections

  • GET /connections — List connections
  • POST /connections — Create a connection
  • PUT /connections/{id}/vcs-usage — Save a VCS connection's tracker link, approver settings and permissions together
  • GET /connections/{id}/cm-steps — What putting a repository under change management writes, for this connection
  • GET /connections/metadata — Supported providers, deployment types, VCS vocabulary and roles
  • GET /connections/{id} — Get a connection
  • PUT /connections/{id} — Update a connection
  • DELETE /connections/{id} — Delete a connection
  • POST /connections/{id}/test — Test a connection
  • PUT /connections/{id}/link-tracker — Link a tracker to a VCS connection
  • PUT /connections/{id}/vcs-settings — Set a VCS connection's approver settings
  • PUT /connections/{id}/vcs-permissions — Set what people may do through a VCS connection
  • PUT /connections/{id}/tracker-settings — Set a tracker connection's change approval settings
  • POST /connections/{id}/tracker-settings/check — Check tracker settings against the tracker
  • GET /connections/{id}/tracker-options — What tracker settings can name
  • GET /connections/{id}/people-check — Which tracker account each person maps to
  • POST /connections/{id}/github/manifest — Start registering the connection's GitHub App
  • POST /connections/{id}/github/installations/sync — Read the GitHub App's installations again
  • DELETE /connections/{id}/github/app — Forget the connection's GitHub App

VCS operations

  • GET /vcs-ops/projects/{pid} — Read a repository from the VCS
  • GET /vcs-ops/projects/{pid}/my-access — What the caller may do on a repository, per operation
  • GET /vcs-ops/projects/{pid}/membership — The caller's membership of a repository
  • POST /vcs-ops/projects/{pid}/join — Add the caller to a repository
  • POST /vcs-ops/projects/{pid}/leave — Remove the caller from a repository
  • GET /vcs-ops/groups — Groups that hold the company's repositories
  • GET /vcs-ops/groups/{gid}/membership — The caller's membership of a group
  • POST /vcs-ops/groups/{gid}/join — Add the caller to a group
  • POST /vcs-ops/groups/{gid}/leave — Remove the caller from a group
  • GET /vcs-ops/projects/{pid}/variables — A repository's CI/CD variables and secrets
  • POST /vcs-ops/projects/{pid}/variables — Create a CI/CD variable or secret on a repository
  • PUT /vcs-ops/projects/{pid}/variables/{key} — Change a repository's CI/CD variable or secret
  • DELETE /vcs-ops/projects/{pid}/variables/{key} — Delete a repository's CI/CD variable or secret
  • GET /vcs-ops/projects/{pid}/environments — A repository's deployment environments (GitHub)
  • GET /vcs-ops/projects/{pid}/group — The group (GitHub organization) a repository belongs to
  • GET /vcs-ops/groups/{gid}/variables — A group's CI/CD variables and secrets
  • POST /vcs-ops/groups/{gid}/variables — Create a CI/CD variable or secret on a group
  • PUT /vcs-ops/groups/{gid}/variables/{key} — Change a group's CI/CD variable or secret
  • DELETE /vcs-ops/groups/{gid}/variables/{key} — Delete a group's CI/CD variable or secret
  • GET /vcs-ops/projects/{pid}/branches — A repository's branches
  • GET /vcs-ops/projects/{pid}/protected-branches — A repository's protected branches
  • POST /vcs-ops/projects/{pid}/protected-branches — Protect a branch
  • DELETE /vcs-ops/projects/{pid}/protected-branches/{name} — Remove a branch's protection
  • PATCH /vcs-ops/projects/{pid}/protected-branches/{name}/force-push — Allow or forbid force pushes to a protected branch
  • GET /vcs-ops/projects/{pid}/tokens — Tokens Merge Pilot created on a repository (GitLab)
  • POST /vcs-ops/projects/{pid}/access-tokens — Create a GitLab project access token
  • POST /vcs-ops/projects/{pid}/deploy-tokens — Create a GitLab deploy token
  • DELETE /vcs-ops/projects/{pid}/tokens/{token_id} — Revoke a token Merge Pilot created
  • GET /companies/{id}/vcs-access-grants — Repository and group access people got through Merge Pilot
  • DELETE /companies/{id}/vcs-access-grants/{grant_id} — Dismiss a released access record
  • GET /companies/{id}/vcs-issued-tokens — Released tokens that may still work
  • POST /companies/{id}/vcs-issued-tokens/{token_id}/revoke — Revoke a released token
  • DELETE /companies/{id}/vcs-issued-tokens/{token_id} — Dismiss a released token's record

Tracker

  • GET /mptracker/projects — List tracker projects
  • POST /mptracker/projects — Create a tracker project
  • GET /mptracker/projects/{id} — Get a tracker project
  • PUT /mptracker/projects/{id} — Update a tracker project
  • DELETE /mptracker/projects/{id} — Archive a tracker project
  • GET /mptracker/projects/{id}/issues — List a project's issues
  • POST /mptracker/projects/{id}/issues — Create an issue (manual-mode projects)
  • GET /mptracker/projects/{id}/board — Issues grouped by state (kanban board)
  • GET /mptracker/issues/{id} — Get an issue
  • PUT /mptracker/issues/{id} — Update an issue's summary, description, type or custom fields
  • GET /mptracker/issues/by-key/{key} — Get an issue by key (e.g. a change approval key)
  • POST /mptracker/issues/{id}/transition — Move an issue to another state
  • POST /mptracker/issues/{id}/assign — Assign an issue
  • GET /mptracker/issues/{id}/comments — List an issue's comments
  • POST /mptracker/issues/{id}/comments — Comment on an issue
  • GET /mptracker/users — Search the company's active users by prefix (for assignee pickers)

Audit

  • GET /audit-logs — Search the audit log
  • GET /webhook-logs — Inbound webhook log (VCS and tracker events received)
  • GET /compliance/report — Export the compliance report (CSV or PDF)

Insights

  • GET /companies/{id}/vulnerabilities — The vulnerability inventory of the company's default branches
  • GET /companies/{id}/vulnerabilities/feeds — When the CISA KEV and FIRST EPSS feeds were last read
  • GET /companies/{id}/vulnerabilities/summary — The inventory at a glance
  • GET /companies/{id}/vulnerabilities.csv — The filtered inventory as CSV
  • GET /companies/{id}/direct-changes — Changes made to watched branches without a merge request
  • GET /companies/{id}/direct-changes/summary — The last 30 days' direct changes at a glance
  • GET /companies/{id}/direct-changes.csv — The filtered direct changes as CSV
  • GET /companies/{id}/iac-findings — The infrastructure findings of the company's default branches
  • GET /companies/{id}/iac-findings/summary — The infrastructure inventory at a glance
  • GET /companies/{id}/vulnerability-exceptions — The company's vulnerability exceptions
  • POST /companies/{id}/vulnerability-exceptions — Accept an advisory, or mark it not affecting
  • DELETE /companies/{id}/vulnerability-exceptions/{eid} — Revoke an exception
  • GET /companies/{id}/monitoring/report — What change management would have done with watched repositories' merge requests
  • POST /companies/{id}/monitoring/report — The monitoring report with a draft policy set
  • GET /companies/{id}/monitoring/report.csv — The monitoring report's merge requests as CSV
  • GET /dashboard — Dashboard overview
  • GET /dashboard/stats — Dashboard counters
  • GET /dashboard/cycle-time — Cycle time summary
  • GET /dashboard/change-calendar — Changes per day of a month
  • GET /dora — DORA metrics
  • GET /analytics/cycle-time — Cycle time analytics
  • GET /analytics/bottlenecks — Where merge requests wait
  • GET /my-work — The caller's open work (authored MRs, change approvals to decide)

Delegations

  • GET /delegations — Current and future delegations
  • POST /delegations — Hand an approver's votes to someone else for a while
  • GET /delegations/people — People who can be chosen as delegate
  • DELETE /delegations/{id} — End a delegation

Notification deliveries

  • GET /companies/{id}/notification-deliveries — The delivery log
  • GET /companies/{id}/notification-deliveries/failures — Deliveries that failed for good
  • POST /companies/{id}/notification-deliveries/{did}/redeliver — Send a delivery again now
  • GET /companies/{id}/notification-routes/inactive-recipients — Route addresses of deactivated people

Notifications

  • GET /auth/me/notification-preferences — Own personal notification emails
  • PUT /auth/me/notification-preferences — Turn personal notification emails on or off
  • POST /notifications/unsubscribe — Unsubscribe (one click)
  • GET /notifications/unsubscribe/details — What an unsubscribe link turns off

Jobs

  • GET /jobs — List background jobs
  • GET /jobs/stats — Job counts by status
  • GET /jobs/{id} — Get a job
  • POST /jobs/{id}/retry — Queue a job again

Health

  • GET /health-checks — Recorded health checks of the services Merge Pilot calls
  • GET /health-checks/summary — Latest state per connection
  • GET /health-checks/notifications — Companies with failed notification deliveries
  • GET /scanner/rules — Secret scanner rules
  • GET /healthz — Liveness probe (outside /api/v1)
  • GET /readyz — Readiness probe (outside /api/v1)
  • GET /version — The running release
  • GET /instances — The running instances

Platform

  • GET /settings/urls — The addresses Merge Pilot is reached at
  • GET /license/status — License state (any signed-in account)

Diagnostics

  • GET /debug/mr/{id}/flow — A merge request's event flow
  • POST /debug/webhooks/{id}/replay — Replay a received webhook
  • GET /api-calls — Calls Merge Pilot made to the VCS and the tracker