[Skip to main content](https://docs.gitlab.com/api/merge_request_approvals/#skipTarget) [Go to GitLab Docs homepage](https://docs.gitlab.com/)
`/`
[What's new?](https://about.gitlab.com/releases/whats-new/)
English
  * Language
  * English
  * 日本語


v18.10
  *     * [18.10 (not yet released)](https://docs.gitlab.com/api/merge_request_approvals/)
  *     * [18.9 (recently released)](https://docs.gitlab.com/18.9/api/merge_request_approvals/)
    * [18.8](https://docs.gitlab.com/18.8/api/merge_request_approvals/)
    * [18.7](https://archives.docs.gitlab.com/18.7/api/merge_request_approvals/)
  *     * [17.11](https://archives.docs.gitlab.com/17.11/api/merge_request_approvals/)
    * [16.11](https://archives.docs.gitlab.com/16.11/ee/api/merge_request_approvals.html)
  *     * [Archives](https://docs.gitlab.com/archives)


Select theme and layout
  * Light mode
  * Dark mode
  * Auto


  * Fixed width
  * Fluid width


[What's new?](https://about.gitlab.com/releases/whats-new/) [Get free trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com&amp;glm_content=navigation-cta-docs)
Toggle menu
  * [Use GitLab](https://docs.gitlab.com/user/)
  * [GitLab Duo](https://docs.gitlab.com/user/gitlab_duo/)
  * [Extend](https://docs.gitlab.com/api/)
  * [Install](https://docs.gitlab.com/install/)
  * [Administer](https://docs.gitlab.com/administration/)
  * [Subscribe](https://docs.gitlab.com/subscriptions/)
  * [Contribute](https://docs.gitlab.com/development/)
  * [Solutions](https://docs.gitlab.com/solutions/)


Select a topicUse GitLab GitLab Duo Extend Install Administer Subscribe Contribute Solutions
[Getting started](https://docs.gitlab.com/api/get_started/get_started_extending/)
[Tutorials](https://docs.gitlab.com/tutorials/develop/)
[Integrations](https://docs.gitlab.com/integration/)
[Webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/)
[REST API](https://docs.gitlab.com/api/rest/)
[Resources](https://docs.gitlab.com/api/api_resources/)
[.gitignore (templates)](https://docs.gitlab.com/api/templates/gitignores/)
[.gitlab-ci.yml (templates)](https://docs.gitlab.com/api/templates/gitlab_ci_ymls/)
[Access requests](https://docs.gitlab.com/api/access_requests/)
[Agent for Kubernetes](https://docs.gitlab.com/api/cluster_agents/)
[AI Catalog admin](https://docs.gitlab.com/api/admin/ai_catalog/)
[Alert management](https://docs.gitlab.com/api/alert_management_alerts/)
[Application appearance](https://docs.gitlab.com/api/appearance/)
[Application settings](https://docs.gitlab.com/api/settings/)
[Application statistics](https://docs.gitlab.com/api/statistics/)
[Applications](https://docs.gitlab.com/api/applications/)
[Attestations](https://docs.gitlab.com/api/attestations/)
[Audit events](https://docs.gitlab.com/api/audit_events/)
[Avatar](https://docs.gitlab.com/api/avatar/)
[Branches](https://docs.gitlab.com/api/branches/)
[Broadcast messages](https://docs.gitlab.com/api/broadcast_messages/)
[Cluster discovery (certificate-based) (deprecated)](https://docs.gitlab.com/api/cluster_discovery/)
[Code Suggestions](https://docs.gitlab.com/api/code_suggestions/)
[Commits](https://docs.gitlab.com/api/commits/)
[Compliance and policy settings](https://docs.gitlab.com/api/compliance_policy_settings/)
[Composer](https://docs.gitlab.com/api/packages/composer/)
[Conan v1](https://docs.gitlab.com/api/packages/conan_v1/)
[Conan v2](https://docs.gitlab.com/api/packages/conan_v2/)
[Container registry](https://docs.gitlab.com/api/container_registry/)
[Container repository protection rules](https://docs.gitlab.com/api/container_repository_protection_rules/)
[Container registry protection tag rules](https://docs.gitlab.com/api/container_registry_protection_tag_rules/)
[Container virtual registry](https://docs.gitlab.com/api/container_virtual_registries/)
[Custom attributes](https://docs.gitlab.com/api/custom_attributes/)
[Database migrations](https://docs.gitlab.com/api/database_migrations/)
[Data management](https://docs.gitlab.com/api/admin/data_management/)
[Debian](https://docs.gitlab.com/api/packages/debian/)
[Debian group distributions](https://docs.gitlab.com/api/packages/debian_group_distributions/)
[Debian project distributions](https://docs.gitlab.com/api/packages/debian_project_distributions/)
[Dependencies](https://docs.gitlab.com/api/dependencies/)
[Dependency list export](https://docs.gitlab.com/api/dependency_list_export/)
[Dependency Proxy](https://docs.gitlab.com/api/dependency_proxy/)
[Deploy keys](https://docs.gitlab.com/api/deploy_keys/)
[Deploy tokens](https://docs.gitlab.com/api/deploy_tokens/)
[Deployments](https://docs.gitlab.com/api/deployments/)
[Discussions](https://docs.gitlab.com/api/discussions/)
[Dockerfile (templates)](https://docs.gitlab.com/api/templates/dockerfiles/)
[DORA4 metrics](https://docs.gitlab.com/api/dora/metrics/)
[Emoji reactions](https://docs.gitlab.com/api/emoji_reactions/)
[Environments](https://docs.gitlab.com/api/environments/)
[Epics (deprecated)](https://docs.gitlab.com/api/epics/)
[Error tracking](https://docs.gitlab.com/api/error_tracking/)
[Events](https://docs.gitlab.com/api/events/)
[Experiments](https://docs.gitlab.com/api/experiments/)
[External status checks](https://docs.gitlab.com/api/status_checks/)
[Feature flags](https://docs.gitlab.com/api/feature_flags/)
[Feature flag user lists](https://docs.gitlab.com/api/feature_flag_user_lists/)
[Freeze periods](https://docs.gitlab.com/api/freeze_periods/)
[Geo nodes (deprecated)](https://docs.gitlab.com/api/geo_nodes/)
[Geo sites](https://docs.gitlab.com/api/geo_sites/)
[GitLab Duo Chat completions](https://docs.gitlab.com/api/chat/)
[GitLab Pages](https://docs.gitlab.com/api/pages/)
[GLQL](https://docs.gitlab.com/api/glql/)
[Go Proxy](https://docs.gitlab.com/api/packages/go_proxy/)
[Google Cloud integration](https://docs.gitlab.com/api/google_cloud_integration/)
[Groups](https://docs.gitlab.com/api/groups/)
[Helm](https://docs.gitlab.com/api/packages/helm/)
[Import](https://docs.gitlab.com/api/import/)
[Instance CI/CD variables](https://docs.gitlab.com/api/instance_level_ci_variables/)
[Invitations](https://docs.gitlab.com/api/invitations/)
[Issues](https://docs.gitlab.com/api/issues/)
[Issues (epic) (deprecated)](https://docs.gitlab.com/api/epic_issues/)
[Issues statistics](https://docs.gitlab.com/api/issues_statistics/)
[Jobs](https://docs.gitlab.com/api/jobs/)
[Job artifacts](https://docs.gitlab.com/api/job_artifacts/)
[Job token scopes](https://docs.gitlab.com/api/project_job_token_scopes/)
[Keys](https://docs.gitlab.com/api/keys/)
[License](https://docs.gitlab.com/api/license/)
[Licenses (templates)](https://docs.gitlab.com/api/templates/licenses/)
[Linked epics (deprecated)](https://docs.gitlab.com/api/linked_epics/)
[Links (issue)](https://docs.gitlab.com/api/issue_links/)
[Links (epic) (deprecated)](https://docs.gitlab.com/api/epic_links/)
[Lint .gitlab-ci.yml](https://docs.gitlab.com/api/lint/)
[Markdown](https://docs.gitlab.com/api/markdown/)
[Maven](https://docs.gitlab.com/api/packages/maven/)
[Maven virtual registry](https://docs.gitlab.com/api/maven_virtual_registries/)
[Member roles](https://docs.gitlab.com/api/member_roles/)
[Merge request approvals](https://docs.gitlab.com/api/merge_request_approvals/)
[Merge request approval settings](https://docs.gitlab.com/api/merge_request_approval_settings/)
[Merge request context commits](https://docs.gitlab.com/api/merge_request_context_commits/)
[Merge requests](https://docs.gitlab.com/api/merge_requests/)
[Merge trains](https://docs.gitlab.com/api/merge_trains/)
[Metadata](https://docs.gitlab.com/api/metadata/)
[Model registry](https://docs.gitlab.com/api/model_registry/)
[Namespaces](https://docs.gitlab.com/api/namespaces/)
[Notes (comments)](https://docs.gitlab.com/api/notes/)
[Notification settings](https://docs.gitlab.com/api/notification_settings/)
[npm](https://docs.gitlab.com/api/packages/npm/)
[NuGet](https://docs.gitlab.com/api/packages/nuget/)
[Organizations](https://docs.gitlab.com/api/organizations/)
[Packages](https://docs.gitlab.com/api/packages/)
[Pages domains](https://docs.gitlab.com/api/pages_domains/)
[Personal access tokens](https://docs.gitlab.com/api/personal_access_tokens/)
[Pipeline schedules](https://docs.gitlab.com/api/pipeline_schedules/)
[Pipeline trigger tokens](https://docs.gitlab.com/api/pipeline_triggers/)
[Pipelines](https://docs.gitlab.com/api/pipelines/)
[Plan limits](https://docs.gitlab.com/api/plan_limits/)
[Product analytics](https://docs.gitlab.com/api/product_analytics/)
[Projects](https://docs.gitlab.com/api/projects/)
[PyPI](https://docs.gitlab.com/api/packages/pypi/)
[Repositories](https://docs.gitlab.com/api/repositories/)
[Repository files](https://docs.gitlab.com/api/repository_files/)
[Repository submodules](https://docs.gitlab.com/api/repository_submodules/)
[Resource group](https://docs.gitlab.com/api/resource_groups/)
[Resource iteration events](https://docs.gitlab.com/api/resource_iteration_events/)
[Resource label events](https://docs.gitlab.com/api/resource_label_events/)
[Resource milestone events](https://docs.gitlab.com/api/resource_milestone_events/)
[Resource state events](https://docs.gitlab.com/api/resource_state_events/)
[Resource weight events](https://docs.gitlab.com/api/resource_weight_events/)
[Ruby gems](https://docs.gitlab.com/api/packages/rubygems/)
[Runners](https://docs.gitlab.com/api/runners/)
[Runner controllers](https://docs.gitlab.com/api/runner_controllers/)
[Runner controller tokens](https://docs.gitlab.com/api/runner_controller_tokens/)
[Search](https://docs.gitlab.com/api/search/)
[Search migrations](https://docs.gitlab.com/api/search_admin/)
[Secure files](https://docs.gitlab.com/api/secure_files/)
[Service accounts](https://docs.gitlab.com/api/service_accounts/)
[Service Ping](https://docs.gitlab.com/api/usage_data/)
[Sidekiq metrics](https://docs.gitlab.com/api/sidekiq_metrics/)
[Sidekiq queues](https://docs.gitlab.com/api/admin_sidekiq_queues/)
[Snippet repository storage moves](https://docs.gitlab.com/api/snippet_repository_storage_moves/)
[Snippets](https://docs.gitlab.com/api/snippets/)
[Suggestions](https://docs.gitlab.com/api/suggestions/)
[System hooks](https://docs.gitlab.com/api/system_hooks/)
[Tags](https://docs.gitlab.com/api/tags/)
[Terraform registry](https://docs.gitlab.com/api/packages/terraform-modules/)
[To-Do List](https://docs.gitlab.com/api/todos/)
[Token information](https://docs.gitlab.com/api/admin/token/)
[Topics](https://docs.gitlab.com/api/topics/)
[Users](https://docs.gitlab.com/api/users/)
[Version](https://docs.gitlab.com/api/version/)
[Virtual registries cleanup policies](https://docs.gitlab.com/api/virtual_registries_cleanup_policies/)
[Vulnerabilities](https://docs.gitlab.com/api/vulnerabilities/)
[Vulnerability archive export](https://docs.gitlab.com/api/vulnerability_archive_exports/)
[Vulnerability export](https://docs.gitlab.com/api/vulnerability_exports/)
[Vulnerability findings](https://docs.gitlab.com/api/vulnerability_findings/)
[Web commits](https://docs.gitlab.com/api/web_commits/)
[Authentication](https://docs.gitlab.com/api/rest/authentication/)
[Third-party clients](https://docs.gitlab.com/api/rest/third_party_clients/)
[Deprecations and removals](https://docs.gitlab.com/api/rest/deprecations/)
[OpenAPI](https://docs.gitlab.com/api/openapi/openapi_interactive/)
[Automate storage management](https://docs.gitlab.com/user/storage_management_automation/)
[Troubleshooting](https://docs.gitlab.com/api/rest/troubleshooting/)
[GraphQL API](https://docs.gitlab.com/api/graphql/)
[OAuth 2.0 identity provider API](https://docs.gitlab.com/api/oauth2/)
[GitLab Duo CLI (duo)](https://docs.gitlab.com/user/gitlab_duo_cli/)
[GitLab CLI (glab)](https://docs.gitlab.com/cli/)
[Editor and IDE extensions](https://docs.gitlab.com/editor_extensions/)
/
  1. [GitLab Docs](https://docs.gitlab.com/)
  2. [Extend](https://docs.gitlab.com/api/)
  3. [REST API](https://docs.gitlab.com/api/rest/)
  4. [Resources](https://docs.gitlab.com/api/api_resources/)
  5. [Merge request approvals](https://docs.gitlab.com/api/merge_request_approvals/)


* * *
# Merge request approvals API
  * Tier: Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


History
  * Endpoint `/approvals` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0.


Use this API to manage [merge request approvals](https://docs.gitlab.com/user/project/merge_requests/approvals/).
All endpoints require authentication.
## Approve merge request[](https://docs.gitlab.com/api/merge_request_approvals/#approve-merge-request "Permalink")
Approves the specified merge request. The currently authenticated user must be an [eligible approver](https://docs.gitlab.com/user/project/merge_requests/approvals/rules/#eligible-approvers).
The `sha` parameter ensures you’re 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. This matches the behavior [accepting a merge request](https://docs.gitlab.com/api/merge_requests/#merge-a-merge-request).
```
POST /projects/:id/merge_requests/:merge_request_iid/approve
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approval_password` | string | No | Current user’s password. Required if [**Require user re-authentication to approve**](https://docs.gitlab.com/user/project/merge_requests/approvals/settings/#require-user-re-authentication-to-approve) is enabled in the project settings. Always fails if the group or GitLab Self-Managed instance is configured to force SAML authentication.
`merge_request_iid` | integer | Yes | The IID of the merge request.
`sha` | string | No | The `HEAD` of the merge request.
json
```
{
  "id": 5,
  "iid": 5,
  "project_id": 1,
  "title": "Approvals API",
  "description": "Test",
  "state": "opened",
  "created_at": "2016-06-08T00:19:52.638Z",
  "updated_at": "2016-06-09T21:32:14.105Z",
  "merge_status": "can_be_merged",
  "approvals_required": 2,
  "approvals_left": 0,
  "approved_by": [
    {
      "user": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
        "web_url": "http://localhost:3000/root"
      },
      "approved_at": "2016-06-10T04:21:41.050Z"
    },
    {
      "user": {
        "name": "Nico Cartwright",
        "username": "ryley",
        "id": 2,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/cf7ad14b34162a76d593e3affca2adca?s=80\u0026d=identicon",
        "web_url": "http://localhost:3000/ryley"
      },
      "approved_at": "2016-06-10T09:17:13.520Z"
    }
  ]
}
```

### Prevent approval resets in automated merge requests[](https://docs.gitlab.com/api/merge_request_approvals/#prevent-approval-resets-in-automated-merge-requests "Permalink")
If you use the API to create and immediately approve a merge request, your automation might approve the merge request before the commit is fully processed. By default, adding a new commit to a merge request [resets any existing approvals](https://docs.gitlab.com/user/project/merge_requests/approvals/settings/#remove-all-approvals-when-commits-are-added-to-the-source-branch). When this happens, the **Activity** area of the merge request shows a sequence of messages like this:
  * `(botname)` approved this merge request 5 minutes ago
  * `(botname)` added 1 commit 5 minutes ago
  * `(botname)` reset approvals from `(botname)` by pushing to the branch 5 minutes ago


To ensure automated approvals are not applied before commit processing is complete, your automation should add a wait (or `sleep`) function until:
  * The `detailed_merge_status` attribute is not in either the `checking` or `approvals_syncing` states.
  * The merge request diff contains a `patch_id_sha` that is not NULL.


## Unapprove a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#unapprove-a-merge-request "Permalink")
Removes the approval for the currently authenticated user from a specified merge request.
```
POST /projects/:id/merge_requests/:merge_request_iid/unapprove
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`merge_request_iid` | integer | Yes | The IID of a merge request.
## Reset approvals for a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#reset-approvals-for-a-merge-request "Permalink")
Resets all approvals for a specified merge request.
Available only to [bot users](https://docs.gitlab.com/user/project/settings/project_access_tokens/#bot-users-for-projects) with a valid project or group token. Human users receive a `401 Unauthorized` response.
```
PUT /projects/:id/merge_requests/:merge_request_iid/reset_approvals
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the project.
`merge_request_iid` | integer | Yes | The internal ID of the merge request.
shell
```
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/reset_approvals"
```

## Approval rules for projects[](https://docs.gitlab.com/api/merge_request_approvals/#approval-rules-for-projects "Permalink")
These endpoints apply to projects and their approval rules. All endpoints require authentication.
### Retrieve approval configuration for a project[](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-configuration-for-a-project "Permalink")
Retrieves the approval configuration for a project.
```
GET /projects/:id/approvals
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
json
```
{
  "approvers": [], // Deprecated in GitLab 12.3, always returns empty
  "approver_groups": [], // Deprecated in GitLab 12.3, always returns empty
  "approvals_before_merge": 2, // Deprecated in GitLab 12.3, use Approval Rules instead
  "reset_approvals_on_push": true,
  "selective_code_owner_removals": false,
  "disable_overriding_approvers_per_merge_request": false,
  "merge_requests_author_approval": true,
  "merge_requests_disable_committers_approval": false,
  "require_password_to_approve": true, // Deprecated in 16.9, use require_reauthentication_to_approve instead
  "require_reauthentication_to_approve": true
}
```

### Update approval configuration for a project[](https://docs.gitlab.com/api/merge_request_approvals/#update-approval-configuration-for-a-project "Permalink")
Updates the approval configuration for a project. The currently authenticated user must be an [eligible approver](https://docs.gitlab.com/user/project/merge_requests/approvals/rules/#eligible-approvers).
```
POST /projects/:id/approvals
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approvals_before_merge` (deprecated) | integer | No | The number of required approvals before a merge request can merge. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3. [Create an approval rule](https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-project) instead.
`disable_overriding_approvers_per_merge_request` | boolean | No | If `true`, prevents overrides of approvers in a merge request.
`merge_requests_author_approval` | boolean | No | If `true`, authors can self-approve their own merge requests.
`merge_requests_disable_committers_approval` | boolean | No | If `true`, users who commit on a merge request cannot approve it.
`require_password_to_approve` (deprecated) | boolean | No | If `true`, require approvers to authenticate with a password before adding the approval. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/431346) in GitLab 16.9. Use `require_reauthentication_to_approve` instead.
`require_reauthentication_to_approve` | boolean | No | If `true`, requires approver to authenticate before adding the approval. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431346) in GitLab 17.1.
`reset_approvals_on_push` | boolean | No | If `true`, approvals are reset on push.
`selective_code_owner_removals` | boolean | No | If `true`, resets approvals from Code Owners if their files change. To use this field, `reset_approvals_on_push` must be `false`.
json
```
{
  "approvals_before_merge": 2, // Use Approval Rules instead
  "reset_approvals_on_push": true,
  "selective_code_owner_removals": false,
  "disable_overriding_approvers_per_merge_request": false,
  "merge_requests_author_approval": false,
  "merge_requests_disable_committers_approval": false,
  "require_password_to_approve": true,
  "require_reauthentication_to_approve": true
}
```

### List all approval rules for a project[](https://docs.gitlab.com/api/merge_request_approvals/#list-all-approval-rules-for-a-project "Permalink")
Lists all approval rules and any associated details for a specified project.
```
GET /projects/:id/approval_rules
```

To restrict the list of approval rules, use the `page` and `per_page` [pagination](https://docs.gitlab.com/api/rest/#offset-based-pagination) parameters.
Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
json
```
[
  {
    "id": 1,
    "name": "security",
    "rule_type": "regular",
    "report_type": null,
    "eligible_approvers": [
      {
        "id": 5,
        "name": "John Doe",
        "username": "jdoe",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/jdoe"
      },
      {
        "id": 50,
        "name": "Group Member 1",
        "username": "group_member_1",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/group_member_1"
      }
    ],
    "approvals_required": 3,
    "users": [
      {
        "id": 5,
        "name": "John Doe",
        "username": "jdoe",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/jdoe"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "group1",
        "path": "group1",
        "description": "",
        "visibility": "public",
        "lfs_enabled": false,
        "avatar_url": null,
        "web_url": "http://localhost/groups/group1",
        "request_access_enabled": false,
        "full_name": "group1",
        "full_path": "group1",
        "parent_id": null,
        "ldap_cn": null,
        "ldap_access": null
      }
    ],
    "applies_to_all_protected_branches": false,
    "protected_branches": [
      {
        "id": 1,
        "name": "main",
        "push_access_levels": [
          {
            "access_level": 30,
            "access_level_description": "Developers + Maintainers"
          }
        ],
        "merge_access_levels": [
          {
            "access_level": 30,
            "access_level_description": "Developers + Maintainers"
          }
        ],
        "unprotect_access_levels": [
          {
            "access_level": 40,
            "access_level_description": "Maintainers"
          }
        ],
        "code_owner_approval_required": "false"
      }
    ],
    "contains_hidden_groups": false,
  },
  {
    "id": 2,
    "name": "Coverage-Check",
    "rule_type": "report_approver",
    "report_type": "code_coverage",
    "eligible_approvers": [
      {
        "id": 5,
        "name": "John Doe",
        "username": "jdoe",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/jdoe"
      },
      {
        "id": 50,
        "name": "Group Member 1",
        "username": "group_member_1",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/group_member_1"
      }
    ],
    "approvals_required": 3,
    "users": [
      {
        "id": 5,
        "name": "John Doe",
        "username": "jdoe",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/jdoe"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "group1",
        "path": "group1",
        "description": "",
        "visibility": "public",
        "lfs_enabled": false,
        "avatar_url": null,
        "web_url": "http://localhost/groups/group1",
        "request_access_enabled": false,
        "full_name": "group1",
        "full_path": "group1",
        "parent_id": null,
        "ldap_cn": null,
        "ldap_access": null
      }
    ],
    "applies_to_all_protected_branches": false,
    "protected_branches": [
      {
        "id": 1,
        "name": "main",
        "push_access_levels": [
          {
            "access_level": 30,
            "access_level_description": "Developers + Maintainers"
          }
        ],
        "merge_access_levels": [
          {
            "access_level": 30,
            "access_level_description": "Developers + Maintainers"
          }
        ],
        "unprotect_access_levels": [
          {
            "access_level": 40,
            "access_level_description": "Maintainers"
          }
        ],
        "code_owner_approval_required": "false"
      }
    ],
    "contains_hidden_groups": false,
  }
]
```

### Retrieve an approval rule for a project[](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-an-approval-rule-for-a-project "Permalink")
Retrieves information about a specified approval rule for a project.
```
GET /projects/:id/approval_rules/:approval_rule_id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approval_rule_id` | integer | Yes | The ID of a approval rule.
json
```
{
  "id": 1,
  "name": "security",
  "rule_type": "regular",
  "report_type": null,
  "eligible_approvers": [
    {
      "id": 5,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    },
    {
      "id": 50,
      "name": "Group Member 1",
      "username": "group_member_1",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/group_member_1"
    }
  ],
  "approvals_required": 3,
  "users": [
    {
      "id": 5,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    }
  ],
  "groups": [
    {
      "id": 5,
      "name": "group1",
      "path": "group1",
      "description": "",
      "visibility": "public",
      "lfs_enabled": false,
      "avatar_url": null,
      "web_url": "http://localhost/groups/group1",
      "request_access_enabled": false,
      "full_name": "group1",
      "full_path": "group1",
      "parent_id": null,
      "ldap_cn": null,
      "ldap_access": null
    }
  ],
  "applies_to_all_protected_branches": false,
  "protected_branches": [
    {
      "id": 1,
      "name": "main",
      "push_access_levels": [
        {
          "access_level": 30,
          "access_level_description": "Developers + Maintainers"
        }
      ],
      "merge_access_levels": [
        {
          "access_level": 30,
          "access_level_description": "Developers + Maintainers"
        }
      ],
      "unprotect_access_levels": [
        {
          "access_level": 40,
          "access_level_description": "Maintainers"
        }
      ],
      "code_owner_approval_required": "false"
    }
  ],
  "contains_hidden_groups": false
}
```

### Create an approval rule for a project[](https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-project "Permalink")
Creates an approval rule for a project.
The `rule_type` field supports these rule types:
  * `any_approver`: A pre-configured default rule with `approvals_required` set to `0`.
  * `regular`: Used for regular [merge request approval rules](https://docs.gitlab.com/user/project/merge_requests/approvals/rules/).
  * `report_approver`: Used when GitLab creates an approval rule from configured and enabled [merge request approval policies](https://docs.gitlab.com/user/application_security/policies/merge_request_approval_policies/). Do not use this value when creating approval rules with this API.


```
POST /projects/:id/approval_rules
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approvals_required` | integer | Yes | The number of required approvals for this rule.
`name` | string | Yes | The name of the approval rule. Limited to 1024 characters.
`applies_to_all_protected_branches` | boolean | No | If `true`, applies the rule to all protected branches and ignores the `protected_branch_ids` attribute.
`group_ids` | Array | No | The IDs of groups as approvers.
`protected_branch_ids` | Array | No | The IDs of protected branches to scope the rule by. To identify the ID, use the [List protected branches](https://docs.gitlab.com/api/protected_branches/#list-protected-branches) API.
`report_type` | string | No | The report type. Required when the rule type is `report_approver`. The supported report types are `license_scanning` [(Deprecated in GitLab 15.9)](https://docs.gitlab.com/update/deprecations/#license-check-and-the-policies-tab-on-the-license-compliance-page) and `code_coverage`.
`rule_type` | string | No | The rule type. Supported values include `any_approver`, `regular`, and `report_approver`.
`user_ids` | Array | No | The IDs of users as approvers. If used with `usernames`, adds both lists of users.
`usernames` | string array | No | The usernames of approvers. If used with `user_ids`, adds both lists of users.
json
```
{
  "id": 1,
  "name": "security",
  "rule_type": "regular",
  "eligible_approvers": [
    {
      "id": 2,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    },
    {
      "id": 50,
      "name": "Group Member 1",
      "username": "group_member_1",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/group_member_1"
    }
  ],
  "approvals_required": 1,
  "users": [
    {
      "id": 2,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    }
  ],
  "groups": [
    {
      "id": 5,
      "name": "group1",
      "path": "group1",
      "description": "",
      "visibility": "public",
      "lfs_enabled": false,
      "avatar_url": null,
      "web_url": "http://localhost/groups/group1",
      "request_access_enabled": false,
      "full_name": "group1",
      "full_path": "group1",
      "parent_id": null,
      "ldap_cn": null,
      "ldap_access": null
    }
  ],
  "applies_to_all_protected_branches": false,
  "protected_branches": [
    {
      "id": 1,
      "name": "main",
      "push_access_levels": [
        {
          "access_level": 30,
          "access_level_description": "Developers + Maintainers"
        }
      ],
      "merge_access_levels": [
        {
          "access_level": 30,
          "access_level_description": "Developers + Maintainers"
        }
      ],
      "unprotect_access_levels": [
        {
          "access_level": 40,
          "access_level_description": "Maintainers"
        }
      ],
      "code_owner_approval_required": "false"
    }
  ],
  "contains_hidden_groups": false
}
```

To increase the default number of 0 required approvers:
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header 'Content-Type: application/json' \
  --data '{"name": "Any name", "rule_type": "any_approver", "approvals_required": 2}' \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/approval_rules"
```

Another example is to create a user-specific rule:
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header 'Content-Type: application/json' \
  --data '{"name": "Name of your rule", "approvals_required": 3, "user_ids": [123, 456, 789]}' \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/approval_rules"
```

### Update an approval rule for a project[](https://docs.gitlab.com/api/merge_request_approvals/#update-an-approval-rule-for-a-project "Permalink")
Updates a specified approval rule for a project. This endpoint removes any approvers and groups not defined in the `group_ids`, `user_ids`, or `usernames` attributes.
Hidden groups (private groups the user doesn’t have permission to view) that are not in the `users` or `groups` parameters are preserved by default. To remove them, set `remove_hidden_groups` to `true`. This ensures hidden groups are not removed unintentionally when a user updates an approval rule.
```
PUT /projects/:id/approval_rules/:approval_rule_id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`approval_rule_id` | integer | Yes | The ID of a approval rule.
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`applies_to_all_protected_branches` | boolean | No | If `true`, applies the rule to all protected branches and ignores the `protected_branch_ids` attribute.
`approvals_required` | integer | No | The number of required approvals for this rule.
`group_ids` | Array | No | The IDs of groups as approvers.
`name` | string | No | The name of the approval rule. Limited to 1024 characters.
`protected_branch_ids` | Array | No | The IDs of protected branches to scope the rule by. To identify the ID, use the [List protected branches](https://docs.gitlab.com/api/protected_branches/#list-protected-branches) API.
`remove_hidden_groups` | boolean | No | If `true`, removes hidden groups from the approval rule.
`user_ids` | Array | No | The IDs of users as approvers. If used with `usernames`, adds both lists of users.
`usernames` | string array | No | The usernames of approvers. If used with `user_ids`, adds both lists of users.
json
```
{
  "id": 1,
  "name": "security",
  "rule_type": "regular",
  "eligible_approvers": [
    {
      "id": 2,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    },
    {
      "id": 50,
      "name": "Group Member 1",
      "username": "group_member_1",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/group_member_1"
    }
  ],
  "approvals_required": 1,
  "users": [
    {
      "id": 2,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    }
  ],
  "groups": [
    {
      "id": 5,
      "name": "group1",
      "path": "group1",
      "description": "",
      "visibility": "public",
      "lfs_enabled": false,
      "avatar_url": null,
      "web_url": "http://localhost/groups/group1",
      "request_access_enabled": false,
      "full_name": "group1",
      "full_path": "group1",
      "parent_id": null,
      "ldap_cn": null,
      "ldap_access": null
    }
  ],
  "applies_to_all_protected_branches": false,
  "protected_branches": [
    {
      "id": 1,
      "name": "main",
      "push_access_levels": [
        {
          "access_level": 30,
          "access_level_description": "Developers + Maintainers"
        }
      ],
      "merge_access_levels": [
        {
          "access_level": 30,
          "access_level_description": "Developers + Maintainers"
        }
      ],
      "unprotect_access_levels": [
        {
          "access_level": 40,
          "access_level_description": "Maintainers"
        }
      ],
      "code_owner_approval_required": "false"
    }
  ],
  "contains_hidden_groups": false
}
```

### Delete an approval rule for a project[](https://docs.gitlab.com/api/merge_request_approvals/#delete-an-approval-rule-for-a-project "Permalink")
Deletes an approval rule for a specified project.
```
DELETE /projects/:id/approval_rules/:approval_rule_id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approval_rule_id` | integer | Yes | The ID of a approval rule.
## Approval rules for a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#approval-rules-for-a-merge-request "Permalink")
These endpoints apply to individual merge requests. All endpoints require authentication.
### Retrieve approval state for a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-state-for-a-merge-request "Permalink")
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. For more detailed information about the approval rules in a merge request, and whether the approvals received satisfy those rules, see the [`/approval_state` endpoint](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-details-for-a-merge-request).
```
GET /projects/:id/merge_requests/:merge_request_iid/approvals
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`merge_request_iid` | integer | Yes | The IID of the merge request.
json
```
{
  "id": 5,
  "iid": 5,
  "project_id": 1,
  "title": "Approvals API",
  "description": "Test",
  "state": "opened",
  "created_at": "2016-06-08T00:19:52.638Z",
  "updated_at": "2016-06-08T21:20:42.470Z",
  "merge_status": "cannot_be_merged",
  "approvals_required": 2,
  "approvals_left": 1,
  "approved_by": [
    {
      "user": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
        "web_url": "http://localhost:3000/root"
      },
      "approved_at": "2016-06-09T01:45:21.720Z"
    }
  ]
}
```

### Retrieve approval details for a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-details-for-a-merge-request "Permalink")
Retrieves approval details for a specified merge request.
If a user has modified the approval rules for the merge request, the response includes:
  * `approval_rules_overwritten`: If `true`, indicates the default approval rules were modified.
  * `approved`: If `true`, indicates that the associated approval rule was approved.
  * `approved_by`: If defined, indicates the details of the user that approved the associated approval rule. Users not matching an approval rule are not returned. To return all approving users, see the [`/approvals` endpoint](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-state-for-a-merge-request).


```
GET /projects/:id/merge_requests/:merge_request_iid/approval_state
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`merge_request_iid` | integer | Yes | The IID of the merge request.
json
```
{
  "approval_rules_overwritten": true,
  "rules": [
    {
      "id": 1,
      "name": "Ruby",
      "rule_type": "regular",
      "eligible_approvers": [
        {
          "id": 4,
          "name": "John Doe",
          "username": "jdoe",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
          "web_url": "http://localhost/jdoe"
        }
      ],
      "approvals_required": 2,
      "users": [
        {
          "id": 4,
          "name": "John Doe",
          "username": "jdoe",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
          "web_url": "http://localhost/jdoe"
        }
      ],
      "groups": [],
      "contains_hidden_groups": false,
      "approved_by": [
        {
          "id": 4,
          "name": "John Doe",
          "username": "jdoe",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
          "web_url": "http://localhost/jdoe"
        }
      ],
      "source_rule": null,
      "approved": true,
      "overridden": false
    }
  ]
}
```

### List all approval rules for a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#list-all-approval-rules-for-a-merge-request "Permalink")
Lists all approval rules and any associated details for a specified merge request.
Use the `page` and `per_page` [pagination](https://docs.gitlab.com/api/rest/#offset-based-pagination) parameters to restrict the list of approval rules.
```
GET /projects/:id/merge_requests/:merge_request_iid/approval_rules
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`merge_request_iid` | integer | Yes | The IID of the merge request.
json
```
[
  {
    "id": 1,
    "name": "security",
    "rule_type": "regular",
    "report_type": null,
    "eligible_approvers": [
      {
        "id": 5,
        "name": "John Doe",
        "username": "jdoe",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/jdoe"
      },
      {
        "id": 50,
        "name": "Group Member 1",
        "username": "group_member_1",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/group_member_1"
      }
    ],
    "approvals_required": 3,
    "source_rule": null,
    "users": [
      {
        "id": 5,
        "name": "John Doe",
        "username": "jdoe",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/jdoe"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "group1",
        "path": "group1",
        "description": "",
        "visibility": "public",
        "lfs_enabled": false,
        "avatar_url": null,
        "web_url": "http://localhost/groups/group1",
        "request_access_enabled": false,
        "full_name": "group1",
        "full_path": "group1",
        "parent_id": null,
        "ldap_cn": null,
        "ldap_access": null
      }
    ],
    "contains_hidden_groups": false,
    "overridden": false
  },
  {
    "id": 2,
    "name": "Coverage-Check",
    "rule_type": "report_approver",
    "report_type": "code_coverage",
    "eligible_approvers": [
      {
        "id": 5,
        "name": "John Doe",
        "username": "jdoe",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/jdoe"
      },
      {
        "id": 50,
        "name": "Group Member 1",
        "username": "group_member_1",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/group_member_1"
      }
    ],
    "approvals_required": 3,
    "source_rule": null,
    "users": [
      {
        "id": 5,
        "name": "John Doe",
        "username": "jdoe",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
        "web_url": "http://localhost/jdoe"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "group1",
        "path": "group1",
        "description": "",
        "visibility": "public",
        "lfs_enabled": false,
        "avatar_url": null,
        "web_url": "http://localhost/groups/group1",
        "request_access_enabled": false,
        "full_name": "group1",
        "full_path": "group1",
        "parent_id": null,
        "ldap_cn": null,
        "ldap_access": null
      }
    ],
    "contains_hidden_groups": false,
    "overridden": false
  }
]
```

### Retrieve an approval rule for a specific merge request[](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-an-approval-rule-for-a-specific-merge-request "Permalink")
Retrieves information about an approval rule for a specific merge request.
```
GET /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approval_rule_id` | integer | Yes | The ID of an approval rule.
`merge_request_iid` | integer | Yes | The IID of a merge request.
json
```
{
  "id": 1,
  "name": "security",
  "rule_type": "regular",
  "report_type": null,
  "eligible_approvers": [
    {
      "id": 5,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    },
    {
      "id": 50,
      "name": "Group Member 1",
      "username": "group_member_1",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/group_member_1"
    }
  ],
  "approvals_required": 3,
  "source_rule": null,
  "users": [
    {
      "id": 5,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    }
  ],
  "groups": [
    {
      "id": 5,
      "name": "group1",
      "path": "group1",
      "description": "",
      "visibility": "public",
      "lfs_enabled": false,
      "avatar_url": null,
      "web_url": "http://localhost/groups/group1",
      "request_access_enabled": false,
      "full_name": "group1",
      "full_path": "group1",
      "parent_id": null,
      "ldap_cn": null,
      "ldap_access": null
    }
  ],
  "contains_hidden_groups": false,
  "overridden": false
}
```

### Create an approval rule for a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-merge-request "Permalink")
Creates an approval rule for a specific merge request. If `approval_project_rule_id` is set with the ID of an existing approval rule from the project, this endpoint:
  * Copies the values for `name`, `users`, and `groups` from the project’s rule.
  * Uses the `approvals_required` value you specify.


```
POST /projects/:id/merge_requests/:merge_request_iid/approval_rules
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approvals_required` | integer | Yes | The number of required approvals for this rule.
`merge_request_iid` | integer | Yes | The IID of the merge request.
`name` | string | Yes | The name of the approval rule. Limited to 1024 characters.
`approval_project_rule_id` | integer | No | The ID of a project’s approval rule.
`group_ids` | Array | No | The IDs of groups as approvers.
`user_ids` | Array | No | The IDs of users as approvers. If used with `usernames`, adds both lists of users.
`usernames` | string array | No | The usernames of approvers. If used with `user_ids`, adds both lists of users.
json
```
{
  "id": 1,
  "name": "security",
  "rule_type": "regular",
  "eligible_approvers": [
    {
      "id": 2,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    },
    {
      "id": 50,
      "name": "Group Member 1",
      "username": "group_member_1",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/group_member_1"
    }
  ],
  "approvals_required": 1,
  "source_rule": null,
  "users": [
    {
      "id": 2,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    }
  ],
  "groups": [
    {
      "id": 5,
      "name": "group1",
      "path": "group1",
      "description": "",
      "visibility": "public",
      "lfs_enabled": false,
      "avatar_url": null,
      "web_url": "http://localhost/groups/group1",
      "request_access_enabled": false,
      "full_name": "group1",
      "full_path": "group1",
      "parent_id": null,
      "ldap_cn": null,
      "ldap_access": null
    }
  ],
  "contains_hidden_groups": false,
  "overridden": false
}
```

### Update an approval rule for a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#update-an-approval-rule-for-a-merge-request "Permalink")
Updates a specified approval rule for a merge request. This endpoint removes any approvers and groups not included in the `group_ids`, `user_ids`, or `usernames` attributes.
The `report_approver` or `code_owner` rules are system-generated, and you cannot edit them.
```
PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approval_rule_id` | integer | Yes | The ID of an approval rule.
`merge_request_iid` | integer | Yes | The IID of a merge request.
`approvals_required` | integer | No | The number of required approvals for this rule.
`group_ids` | Array | No | The IDs of groups as approvers.
`name` | string | No | The name of the approval rule. Limited to 1024 characters.
`remove_hidden_groups` | boolean | No | If `true`, removes hidden groups.
`user_ids` | Array | No | The IDs of users as approvers. If used with `usernames`, adds both lists of users.
`usernames` | string array | No | The usernames of approvers. If used with `user_ids`, adds both lists of users.
json
```
{
  "id": 1,
  "name": "security",
  "rule_type": "regular",
  "eligible_approvers": [
    {
      "id": 2,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    },
    {
      "id": 50,
      "name": "Group Member 1",
      "username": "group_member_1",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/group_member_1"
    }
  ],
  "approvals_required": 1,
  "source_rule": null,
  "users": [
    {
      "id": 2,
      "name": "John Doe",
      "username": "jdoe",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
      "web_url": "http://localhost/jdoe"
    }
  ],
  "groups": [
    {
      "id": 5,
      "name": "group1",
      "path": "group1",
      "description": "",
      "visibility": "public",
      "lfs_enabled": false,
      "avatar_url": null,
      "web_url": "http://localhost/groups/group1",
      "request_access_enabled": false,
      "full_name": "group1",
      "full_path": "group1",
      "parent_id": null,
      "ldap_cn": null,
      "ldap_access": null
    }
  ],
  "contains_hidden_groups": false,
  "overridden": false
}
```

### Delete an approval rule for a merge request[](https://docs.gitlab.com/api/merge_request_approvals/#delete-an-approval-rule-for-a-merge-request "Permalink")
Deletes an approval rule for a specified merge request.
```
DELETE /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id
```

The `report_approver` or `code_owner` rules are system-generated, and you cannot edit them.
Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
`approval_rule_id` | integer | Yes | The ID of an approval rule.
`merge_request_iid` | integer | Yes | The IID of the merge request.
## Approval rules for groups[](https://docs.gitlab.com/api/merge_request_approvals/#approval-rules-for-groups "Permalink")
  * Status: Experiment


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428051) in GitLab 16.7 [with a flag](https://docs.gitlab.com/administration/feature_flags/) named `approval_group_rules`. Disabled by default. This feature is an [experiment](https://docs.gitlab.com/policy/development_stages_support/).


On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](https://docs.gitlab.com/administration/feature_flags/) named `approval_group_rules`. On GitLab.com and GitLab Dedicated, this feature is not available. This feature is not ready for production use.
Group approval rules apply to all protected branches of projects belonging to the group.
### List all approval rules for a group[](https://docs.gitlab.com/api/merge_request_approvals/#list-all-approval-rules-for-a-group "Permalink")
History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440638) in GitLab 16.10.


Lists all approval rules and any associated details for a specified group. Restricted to group administrators.
Use the `page` and `per_page` [pagination](https://docs.gitlab.com/api/rest/#offset-based-pagination) parameters to restrict the list of approval rules.
```
GET /groups/:id/approval_rules
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a project.
Example request:
shell
```
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/29/approval_rules"
```

Example response:
json
```
[
  {
    "id": 2,
    "name": "rule1",
    "rule_type": "any_approver",
    "report_type": null,
    "eligible_approvers": [],
    "approvals_required": 3,
    "users": [],
    "groups": [],
    "contains_hidden_groups": false,
    "protected_branches": [],
    "applies_to_all_protected_branches": true
  },
  {
    "id": 3,
    "name": "rule2",
    "rule_type": "code_owner",
    "report_type": null,
    "eligible_approvers": [],
    "approvals_required": 2,
    "users": [],
    "groups": [],
    "contains_hidden_groups": false,
    "protected_branches": [],
    "applies_to_all_protected_branches": true
  },
  {
    "id": 4,
    "name": "rule2",
    "rule_type": "report_approver",
    "report_type": "code_coverage",
    "eligible_approvers": [],
    "approvals_required": 2,
    "users": [],
    "groups": [],
    "contains_hidden_groups": false,
    "protected_branches": [],
    "applies_to_all_protected_branches": true
  }
]
```

### Create an approval rule for a group[](https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-group "Permalink")
Creates an approval rule for a group. Restricted to group administrators.
Don’t use the `rule_type` field when building approval rules from the API. The field supports these rule types:
  * `any_approver`: A pre-configured default rule with `approvals_required` set to `0`.
  * `regular`: Used for regular [merge request approval rules](https://docs.gitlab.com/user/project/merge_requests/approvals/rules/).
  * `report_approver`: Used when GitLab creates an approval rule from configured and enabled [merge request approval policies](https://docs.gitlab.com/user/application_security/policies/merge_request_approval_policies/).


```
POST /groups/:id/approval_rules
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of a group](https://docs.gitlab.com/api/rest/#namespaced-paths).
`approvals_required` | integer | Yes | The number of required approvals for this rule.
`name` | string | Yes | The name of the approval rule. Limited to 1024 characters.
`group_ids` | array | No | The IDs of groups as approvers.
`rule_type` | string | No | The rule type. Supported values include `any_approver`, `regular`, and `report_approver`.
`user_ids` | array | No | The IDs of users as approvers.
Example request:
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/29/approval_rules?name=security&approvals_required=2"
```

Example response:
json
```
{
  "id": 5,
  "name": "security",
  "rule_type": "any_approver",
  "eligible_approvers": [],
  "approvals_required": 2,
  "users": [],
  "groups": [],
  "contains_hidden_groups": false,
  "protected_branches": [
    {
      "id": 5,
      "name": "master",
      "push_access_levels": [
        {
          "id": 5,
          "access_level": 40,
          "access_level_description": "Maintainers",
          "deploy_key_id": null,
          "user_id": null,
          "group_id": null
        }
      ],
      "merge_access_levels": [
        {
          "id": 5,
          "access_level": 40,
          "access_level_description": "Maintainers",
          "user_id": null,
          "group_id": null
        }
      ],
      "allow_force_push": false,
      "unprotect_access_levels": [],
      "code_owner_approval_required": false,
      "inherited": false
    }
  ],
  "applies_to_all_protected_branches": true
}
```

### Update an approval rule for a group[](https://docs.gitlab.com/api/merge_request_approvals/#update-an-approval-rule-for-a-group "Permalink")
History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440639) in GitLab 16.10.


Updates an approval rule for a group. Restricted to group administrators.
Don’t use the `rule_type` field when building approval rules from the API. The field supports these rule types:
  * `any_approver`: A pre-configured default rule with `approvals_required` set to `0`.
  * `regular`: Used for regular [merge request approval rules](https://docs.gitlab.com/user/project/merge_requests/approvals/rules/).
  * `report_approver`: Used when GitLab creates an approval rule from configured and enabled [merge request approval policies](https://docs.gitlab.com/user/application_security/policies/merge_request_approval_policies/).


shell
```
PUT /groups/:id/approval_rules/:approval_rule_id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`approval_rule_id` | integer | Yes | The ID of the approval rule.
`id` | integer or string | Yes | The ID or [URL-encoded path of a group](https://docs.gitlab.com/api/rest/#namespaced-paths).
`approvals_required` | string | No | The number of required approvals for this rule.
`group_ids` | integer | No | The IDs of users as approvers.
`name` | string | No | The name of the approval rule. Limited to 1024 characters.
`rule_type` | array | No | The rule type. Supported values include `any_approver`, `regular`, and `report_approver`.
`user_ids` | array | No | The IDs of groups as approvers.
Example request:
shell
```
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/29/approval_rules/5?name=security2&approvals_required=1"
```

Example response:
json
```
{
  "id": 5,
  "name": "security2",
  "rule_type": "any_approver",
  "eligible_approvers": [],
  "approvals_required": 1,
  "users": [],
  "groups": [],
  "contains_hidden_groups": false,
  "protected_branches": [
    {
      "id": 5,
      "name": "master",
      "push_access_levels": [
        {
          "id": 5,
          "access_level": 40,
          "access_level_description": "Maintainers",
          "deploy_key_id": null,
          "user_id": null,
          "group_id": null
        }
      ],
      "merge_access_levels": [
        {
          "id": 5,
          "access_level": 40,
          "access_level_description": "Maintainers",
          "user_id": null,
          "group_id": null
        }
      ],
      "allow_force_push": false,
      "unprotect_access_levels": [],
      "code_owner_approval_required": false,
      "inherited": false
    }
  ],
  "applies_to_all_protected_branches": true
}
```

Was this page helpful?YesNo
Edit this page
  *     * [ Open in Web IDE`.`Quickly and easily edit multiple files. ](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/merge_request_approvals.md)
    * [ View page sourceEdit this file only. ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/merge_request_approvals.md)
    * [ Create an issueSuggest improvements. ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


  * [Approve merge request](https://docs.gitlab.com/api/merge_request_approvals/#approve-merge-request)
  * [Prevent approval resets in automated merge requests](https://docs.gitlab.com/api/merge_request_approvals/#prevent-approval-resets-in-automated-merge-requests)
  * [Unapprove a merge request](https://docs.gitlab.com/api/merge_request_approvals/#unapprove-a-merge-request)
  * [Reset approvals for a merge request](https://docs.gitlab.com/api/merge_request_approvals/#reset-approvals-for-a-merge-request)
  * [Approval rules for projects](https://docs.gitlab.com/api/merge_request_approvals/#approval-rules-for-projects)
  * [Retrieve approval configuration for a project](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-configuration-for-a-project)
  * [Update approval configuration for a project](https://docs.gitlab.com/api/merge_request_approvals/#update-approval-configuration-for-a-project)
  * [List all approval rules for a project](https://docs.gitlab.com/api/merge_request_approvals/#list-all-approval-rules-for-a-project)
  * [Retrieve an approval rule for a project](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-an-approval-rule-for-a-project)
  * [Create an approval rule for a project](https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-project)
  * [Update an approval rule for a project](https://docs.gitlab.com/api/merge_request_approvals/#update-an-approval-rule-for-a-project)
  * [Delete an approval rule for a project](https://docs.gitlab.com/api/merge_request_approvals/#delete-an-approval-rule-for-a-project)
  * [Approval rules for a merge request](https://docs.gitlab.com/api/merge_request_approvals/#approval-rules-for-a-merge-request)
  * [Retrieve approval state for a merge request](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-state-for-a-merge-request)
  * [Retrieve approval details for a merge request](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-details-for-a-merge-request)
  * [List all approval rules for a merge request](https://docs.gitlab.com/api/merge_request_approvals/#list-all-approval-rules-for-a-merge-request)
  * [Retrieve an approval rule for a specific merge request](https://docs.gitlab.com/api/merge_request_approvals/#retrieve-an-approval-rule-for-a-specific-merge-request)
  * [Create an approval rule for a merge request](https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-merge-request)
  * [Update an approval rule for a merge request](https://docs.gitlab.com/api/merge_request_approvals/#update-an-approval-rule-for-a-merge-request)
  * [Delete an approval rule for a merge request](https://docs.gitlab.com/api/merge_request_approvals/#delete-an-approval-rule-for-a-merge-request)
  * [Approval rules for groups](https://docs.gitlab.com/api/merge_request_approvals/#approval-rules-for-groups)
  * [List all approval rules for a group](https://docs.gitlab.com/api/merge_request_approvals/#list-all-approval-rules-for-a-group)
  * [Create an approval rule for a group](https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-group)
  * [Update an approval rule for a group](https://docs.gitlab.com/api/merge_request_approvals/#update-an-approval-rule-for-a-group)


[![GitLab Docs logo](https://docs.gitlab.com/gitlab-logo-footer.svg)](https://docs.gitlab.com/)
  * [Facebook](https://www.facebook.com/gitlab)
  * [LinkedIn](https://www.linkedin.com/company/gitlab-com)
  * [Twitter](https://twitter.com/gitlab)
  * [YouTube](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg)

[![Creative Commons License](https://docs.gitlab.com/by-sa.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
Company
  * [About GitLab](https://about.gitlab.com/company/)
  * [View pricing](https://about.gitlab.com/pricing/)
  * [Try GitLab for free](https://about.gitlab.com/free-trial/)


Feedback
  * [View page source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/merge_request_approvals.md)
  * [Edit in Web IDE](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/merge_request_approvals.md)
  * [Contribute to GitLab](https://about.gitlab.com/community/contribute/)
  * [Suggest updates](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


Help & Community
  * [Get certified](https://university.gitlab.com/pages/certifications)
  * [Get support](https://about.gitlab.com/support/)
  * [Post on the GitLab forum](https://forum.gitlab.com/new-topic?title=topic%20title&body=topic%20body&tags=docs-feedback)


Resources
  * [Terms](https://about.gitlab.com/terms/)
  * [Privacy statement](https://about.gitlab.com/privacy/)
  * [Use of generative AI](https://docs.gitlab.com/legal/use_generative_ai/)
  * [Acceptable use of user licenses](https://docs.gitlab.com/legal/licensing_policy/)
  * Cookie Preferences


![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fmaven_virtual_registries%2F&_biz_t=1772174322809&_biz_i=Maven%20virtual%20registry%20API%20%7C%20GitLab%20Docs&_biz_n=89&rnd=969180&cdn_o=a&_biz_z=1772174322992)![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fmerge_request_approvals%2F&_biz_t=1772174322991&_biz_i=Merge%20request%20approvals%20API%20%7C%20GitLab%20Docs&_biz_n=90&rnd=421628&cdn_o=a&_biz_z=1772174322993)
![Company Logo](https://cdn.cookielaw.org/logos/aa14a5c8-79e3-442a-8177-464ad850b19d/e46c1d0d-1f66-481f-bc06-5427671431da/253e6fee-c4c0-4b60-bc35-79cdae5dda32/gitlab-logo-100.png)
## Privacy Preference Center
## Privacy Preference Center
  * ### Your Privacy
  * ### Strictly Necessary Cookies
  * ### Functionality Cookies
  * ### Performance and Analytics Cookies
  * ### Targeting and Advertising Cookies
  * ### Ad User Data
  * ### Ad Personalization


#### Your Privacy
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
[Cookie Policy](https://about.gitlab.com/privacy/cookies/)
**User ID:** 42fad8d5-ed56-4786-8d74-3c72635252d2
_This User ID will be used as a unique identifier while storing and accessing your preferences for future._
**Timestamp:** --
#### Strictly Necessary Cookies
Always Active
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, enabling you to securely log into the site, filling in forms, or using the customer checkout. GitLab processes any personal data collected through these cookies on the basis of our legitimate interest.
Cookies Details
#### Functionality Cookies
Functionality Cookies
These cookies enable helpful but non-essential website functions that improve your website experience. By recognizing you when you return to our website, they may, for example, allow us to personalize our content for you or remember your preferences. If you do not allow these cookies then some or all of these services may not function properly. GitLab processes any personal data collected through these cookies on the basis of your consent
Cookies Details
#### Performance and Analytics Cookies
Performance and Analytics Cookies
These cookies allow us and our third-party service providers to recognize and count the number of visitors on our websites and to see how visitors move around our websites when they are using it. This helps us improve our products and ensures that users can easily find what they need on our websites. These cookies usually generate aggregate statistics that are not associated with an individual. To the extent any personal data is collected through these cookies, GitLab processes that data on the basis of your consent.
Cookies Details
#### Targeting and Advertising Cookies
Targeting and Advertising Cookies
These cookies enable different advertising related functions. They may allow us to record information about your visit to our websites, such as pages visited, links followed, and videos viewed so we can make our websites and the advertising displayed on it more relevant to your interests. They may be set through our website by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant advertisements on other websites. GitLab processes any personal data collected through these cookies on the basis of your consent.
Cookies Details
#### Ad User Data
Ad User Data
Sets consent for sending user data to Google for advertising purposes.
Cookies Details
#### Ad Personalization
Ad Personalization
Sets consent for personalized advertising.
Cookies Details
Back Button
### Cookie List
Filter Button
Consent Leg.Interest
checkbox label label
checkbox label label
checkbox label label
Clear
  * checkbox label label


Apply Cancel
Confirm My Choices
Allow All
[![Powered by Onetrust](https://cdn.cookielaw.org/logos/static/powered_by_logo.svg)](https://www.onetrust.com/products/cookie-consent/)
