Use this API to manage merge request approvals and the group and project approval settings that govern them. All endpoints require authentication.
Endpoints to approve, unapprove, reset approvals, and retrieve approval state are available on all tiers, including Free. All other endpoints require Premium or Ultimate, and each one shows its tier.
The merge_request_iid and id path parameters must each be a single value.
Passing multiple space-separated values (for example, 451 454 458) is not
supported and returns 400 Bad Request. To act on multiple merge requests,
make one request per merge request IID.
Retrieve approval state for a merge request
GET /api/v4/projects/{id}/merge_requests/{merge_request_iid}/approvals
Retrieves the approval state for a specified merge request. In the response, approved_by contains information about all approvers of the merge request, regardless of whether those approvals satisfy any approval rule.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
merge_Path, | Integer | The IID of a merge request |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not found | — |
Approve merge request
POST /api/v4/projects/{id}/merge_requests/{merge_request_iid}/approve
Approves a specified merge request. The currently authenticated user must be an eligible approver. The sha parameter ensures you are approving the current version of the merge request. If defined, the value must match the merge request’s HEAD commit SHA. A mismatch returns a 409 Conflict response.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
merge_Path, | Integer | The IID of a merge request |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
publish_ | Boolean | When true submits pending review comments |
sha | String | When present, |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Reset approvals for a merge request
PUT /api/v4/projects/{id}/merge_requests/{merge_request_iid}/reset_approvals
Resets all approvals for a specified merge request. Available only to bot users with a valid project or group token. Human users receive a 401 Unauthorized response.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
merge_Path, | Integer | The IID of a merge request |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Unapprove a merge request
POST /api/v4/projects/{id}/merge_requests/{merge_request_iid}/unapprove
Unapproves a merge request. Removes the approval for the currently authenticated user from a specified merge request.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
merge_Path, | Integer | The IID of a merge request |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesApprovals
| Property | Type | Description |
|---|---|---|
approved_ | String (date- | Example:2025- |
user | APIEntities | — |
APIEntitiesCustomAttribute
| Property | Type | Description |
|---|---|---|
key | String | Example:foo |
value | String | Example:bar |
APIEntitiesMergeRequestApprovals
| Property | Type | Description |
|---|---|---|
approved | Boolean | — |
approved_ | APIEntities | — |
user_ | Boolean | — |
user_ | Boolean | — |
APIEntitiesUserBasic
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:/ |
avatar_ | String | Example:https: |
custom_ | Array of APIEntities | — |
id | Integer (int64) | Example:1 |
locked | Boolean | — |
name | String | Example:Administrator |
public_ | String | Example:john@example. |
state | String | Example:active |
username | String | Example:admin |
web_ | String | Example:https: |