API conventions
The endpoints of the Merge Pilot REST API share one response format, one way to page through lists and one error format. This page describes them; the reference gives each endpoint's own parameters and fields.
Requests
- Send request bodies as JSON with
Content-Type: application/json. - A request body may be at most 10 MB; a larger one is refused.
- Query parameters that switch something on or off take
trueorfalse. - An unknown path, or a method a path does not have, is answered
404with a plain-text body (404 page not found), not with the JSON envelope below.
The response envelope
Every JSON answer has the same envelope:
{
"success": true,
"data": { "id": "6718f2c4e1a9b3d5f7a10042", "title": "Add rate limiting" },
"meta": { "page": 1, "page_size": 20, "total": 134 }
}
| Field | Meaning |
|---|---|
success | true for a successful answer, false for an error |
data | The payload: one object, or an array for lists. May be null, for example when a project has never been analysed |
meta | Present on paginated lists (see Pagination) and on a few other answers, which the reference describes |
error | Present on errors only (see Errors) |
204 No Content answers, such as revoking a token, have no body.
Reports and exports are files, not JSON: the compliance report (text/csv or application/pdf), CSV exports of lists, the SBOM and the monitoring report. They come as attachments with a Content-Disposition file name. Their errors still use the JSON envelope.
Pagination
Lists that can be long are paged with two query parameters:
| Parameter | Default | Allowed values |
|---|---|---|
page | 1 | 1 and up |
page_size | 20 | 1 to 100. A larger value is lowered to 100 |
A value that is not a positive number is ignored and the default is used. The answer's meta tells where the page is:
meta field | Meaning |
|---|---|
page | The page returned |
page_size | The page size used, after the limit |
total | How many items match, on all pages |
total_pages | On some lists only, such as those of the built-in tracker |
To read everything, request pages until page × page_size reaches total.
A few lists have their own default and maximum, shown in the reference: the built-in tracker's lists (default 50, at most 200) and a merge request's timeline (default 100, at most 500), among others.
Sorting and filtering
Lists that can be sorted take sort with a column name, or the name with a leading - for descending order: sort=-updated_at. Each list accepts its own columns (for example, merge requests: title, author, created_at, updated_at, risk) and has its own default order. A column the list does not know is ignored, and the default order is used.
Filters are query parameters named after the field they filter, such as state, repo_id or severity; each endpoint lists its own. Many lists also take q, a case-insensitive search. Where the reference lists a filter's allowed values, a value outside them (for example change_type=urgent) is answered 400 naming the allowed values. A malformed ID in a filter is answered 400 with invalid <parameter>.
Errors
An error answer carries success: false and an error object:
{
"success": false,
"error": { "message": "merge request not found" }
}
| Field | Meaning |
|---|---|
error.message | What went wrong, in English. Messages may change between releases: do not match on them |
error.code | A stable, machine-readable reason, present on only a few errors (below) |
The codes:
error.code | Status | When |
|---|---|---|
password_change_required | 403 | A browser session whose password must be changed before anything else |
link_required | 400 | The request acts on a VCS repository for the caller, who has not linked their GitLab or GitHub account in My profile yet (Link your GitLab account in My profile to use this.) |
sign_in_lockout | 409 | Signed-in session only: a change to the company's sign-in settings or directory would leave the people it names without a way to sign in. Send it again with confirm_lockout: true (see Changes that would lock people out) |
assignee_immutable | 422 | Assigning an issue of the built-in tracker whose assignee cannot be changed. The error also has field_key (assignee) |
session_ended | 401, 403 | Browser sign-in only: a browser session that existed may not continue; the message says why (the sign-in page shows it) |
invalid_state, account_disabled, link_no_company, link_other_company, already_linked, server_error | 400, 403, 409, 500 | Browser sign-in only: an account link from My profile was refused (see Troubleshooting sign-in) |
Status codes
| Status | Meaning |
|---|---|
200 | Done. The answer carries the result |
201 | Created, such as a new policy or token |
202 | Accepted but not yet done: the work runs in the background (a project analysis, a bulk operation), or the change waits for four-eyes review and applies once someone else approves it. A change held for review answers {"pending": true, "change": {...}} |
204 | Done, no body |
400 | Invalid input: bad JSON, a missing or wrong field, a malformed ID, a value out of range, or a value GitLab or GitHub does not accept for an operation Merge Pilot does there (in their own words, such as GitLab answered 400: …) |
401 | Not authenticated, or the token or session is invalid, expired or revoked (see Failed authentication) |
403 | Authenticated, but not allowed: the role does not allow it, an auditor tried to change something, a token was used where a person must sign in or act, or the CSRF header of a browser session is missing |
404 | Not found. Things that belong to another company are answered 404 too |
409 | The request conflicts with the current state: someone changed the same thing in the meantime, the change approval is already decided, an approver pool is still used by a policy, an analysis was started at the same moment, a GitHub App step that needs (or must not have) an App, a license key already activated on as many instances as it allows |
422 | The request is valid but could not be carried out: an approved control change could not be applied, a change management setup step was refused by the VCS (nothing was changed), or a built-in tracker field rule refused it |
429 | Too many requests (see Rate limits), a project analysis asked for while one runs or within 5 minutes of the last one, a webhook replayed again within a minute or more than 10 times, or GitLab's or GitHub's API rate limit reached during an operation on a repository (with Retry-After) |
500 | Merge Pilot could not complete the request. Try again later |
501 | The connection's VCS does not support this operation. On GitHub: the group list, joining and leaving groups, the project tokens list, creating project access tokens and deploy tokens (for company admins: others are refused with 403, since the rules cannot be turned on there), and protected or masked when changing a variable. On GitLab: the environments list, and secret=true when changing or deleting a variable (GitLab has no secrets) |
502 | The VCS, the tracker, GitHub or the license service refused or failed the call Merge Pilot made for the request (a failed Test connection included). When the VCS refuses Merge Pilot's own account: Merge Pilot's account was refused by GitLab; check the connection |
503 | A part of Merge Pilot that the request needs is not available right now. Try again later |
Rate limits
Merge Pilot limits how many requests one client IP address may send:
| Requests | Limit per client IP (defaults) |
|---|---|
| All API requests | 1,200 per minute |
| Signing in, changing one's own password, finding the sign-in method | 30 per minute, on top of the general limit |
| Webhooks from GitLab, GitHub and Jira | 6,000 per minute |
- The limits are per client IP address, not per token: programs and people behind the same address share them.
- The limits are for the whole Merge Pilot installation, however many servers it runs on.
- The API allowance refills evenly over the minute. The sign-in allowance starts again with each minute:
Retry-Aftergives the seconds until then. - Your administrators may have set other limits for your instance, or turned the API limit off when a gateway in front of Merge Pilot limits requests instead.
Over the limit, the request is answered 429 with a Retry-After header, in seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json; charset=utf-8
{"success":false,"error":{"message":"rate limit exceeded, please try again later"}}
Wait at least Retry-After seconds before retrying. A 429 about a project analysis running (analysis already running) has no Retry-After; one within the 5 minutes after the last analysis (the last analysis completed less than 5 minutes ago; run it again in N minutes) has it. See Project analysis → Failures, retry and cooldown.
Concurrent changes and retries
The API has no idempotency keys. Where two changes could overwrite each other, it uses versions instead:
- Change policies: send back the
versionyou read when you change a policy. If someone saved it in the meantime, the answer is409with the policy was changed by someone else; reload and try again. - Built-in tracker issues: changing, moving or assigning an issue needs its current
version. A stale one is answered409with version conflict: issue was modified by another user.
Read the item again, apply your change to it, and send it again. Other requests handle repeats on their own: a second project analysis started while one runs is answered 429 or 409 and starts nothing, and a vote on a change approval that is already decided is answered 409.
IDs, numbers and timestamps
- Merge Pilot's IDs are 24-character lower-case hexadecimal strings, such as
6718f2c4e1a9b3d5f7a10042. - IDs that come from the VCS are strings:
repo_id(the repository's ID on the VCS) andmr_number(the merge request's IID on GitLab, the pull request's number on GitHub). A merge request's Merge Pilotidis different from its number: find it withGET /merge-requests/lookup?repo_id=…&mr_number=…. - Timestamps are RFC 3339 strings with a time zone, usually UTC (
2026-10-26T09:14:03.512Z). Parse them with an RFC 3339 parser. - Query parameters that take a time take RFC 3339, such as
since=2026-10-01T00:00:00Z. The compliance report'sfromandtoalso take a day (2026-10-01), counted in the company's time zone.
Audit of API actions
Changes made with the API are written to the audit log as the same changes made in the interface are:
| Who acted | Shown as (username) |
|---|---|
| A browser session | The person |
| A personal token | The person who made the token |
| A service token | token:<token name> |
Each entry also records the client IP. Reads are not recorded, except exports: the compliance report (compliance_export) and SBOMs (sbom_exported). Making and revoking tokens is recorded as api_token_created and api_token_revoked.
Related pages
- REST API: what the API covers and the base URL.
- Authentication: tokens and company selection.
- Examples: worked requests.