info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
---
# Group and project members API
# Group and project members API **(FREE)**
## Valid access levels
## Valid access levels
...
@@ -92,7 +92,7 @@ Gets a list of group or project members viewable by the authenticated user, incl
...
@@ -92,7 +92,7 @@ Gets a list of group or project members viewable by the authenticated user, incl
If a user is a member of this group or project and also of one or more ancestor groups,
If a user is a member of this group or project and also of one or more ancestor groups,
only its membership with the highest `access_level` is returned.
only its membership with the highest `access_level` is returned.
([Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56677)] in GitLab 13.11.)
([Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56677) in GitLab 13.11.)
This represents the effective permission of the user.
This represents the effective permission of the user.
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3.
> - Moved to GitLab Premium in 13.9.
> - Moved to GitLab Premium in 13.9.
> - `protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7.
> - `protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.7.
You can request information about a project's approval rules using the following endpoint:
You can request information about a project's approval rules using the following endpoint:
...
@@ -954,7 +954,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve
...
@@ -954,7 +954,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve
| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of the merge request |
| `merge_request_iid` | integer | yes | The IID of the merge request |
| `sha` | string | no | The `HEAD` of the merge request |
| `sha` | string | no | The `HEAD` of the merge request |
| `approval_password`**(PREMIUM)**| string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. |
| `approval_password` | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. |
The `sha` parameter works in the same way as
The `sha` parameter works in the same way as
when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must
when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
the `approvals_before_merge` parameter:
the `approvals_before_merge` parameter:
```json
```json
...
@@ -418,7 +418,7 @@ The `merge_status` field may hold one of the following values:
...
@@ -418,7 +418,7 @@ The `merge_status` field may hold one of the following values:
| `cannot_be_merged` | There are merge conflicts between the source and target branches |
| `cannot_be_merged` | There are merge conflicts between the source and target branches |
| `cannot_be_merged_recheck` | Currently unchecked. Before the current changes, there were conflicts |
| `cannot_be_merged_recheck` | Currently unchecked. Before the current changes, there were conflicts |
Users on GitLab Premium or higher also see
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
the `approvals_before_merge` parameter:
the `approvals_before_merge` parameter:
```json
```json
...
@@ -460,8 +460,8 @@ Parameters:
...
@@ -460,8 +460,8 @@ Parameters:
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. |
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. |
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413).|
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7.|
| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890). |
| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. |
| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
...
@@ -478,7 +478,7 @@ Parameters:
...
@@ -478,7 +478,7 @@ Parameters:
| `source_branch` | string | no | Return merge requests with the given source branch. |
| `source_branch` | string | no | Return merge requests with the given source branch. |
| `target_branch` | string | no | Return merge requests with the given target branch. |
| `target_branch` | string | no | Return merge requests with the given target branch. |
| `search` | string | no | Search merge requests against their `title` and `description`. |
| `search` | string | no | Search merge requests against their `title` and `description`. |
| `non_archived` | boolean | no | Return merge requests from non archived projects only. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23809))_. |
| `non_archived` | boolean | no | Return merge requests from non archived projects only. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23809) in GitLab 12.8)_. |
| `not` | Hash | no | Return merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. |
| `not` | Hash | no | Return merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. |
```json
```json
...
@@ -592,7 +592,7 @@ Parameters:
...
@@ -592,7 +592,7 @@ Parameters:
]
]
```
```
Users on GitLab Premium or higher also see
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
the `approvals_before_merge` parameter:
the `approvals_before_merge` parameter:
```json
```json
...
@@ -764,7 +764,7 @@ Parameters:
...
@@ -764,7 +764,7 @@ Parameters:
}
}
```
```
Users on GitLab Premium also see
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
the `approvals_before_merge` parameter:
the `approvals_before_merge` parameter:
```json
```json
...
@@ -1014,7 +1014,7 @@ The new pipeline can be:
...
@@ -1014,7 +1014,7 @@ The new pipeline can be:
- A detached merge request pipeline.
- A detached merge request pipeline.
- A [pipeline for merged results](../ci/pipelines/pipelines_for_merged_results.md)
- A [pipeline for merged results](../ci/pipelines/pipelines_for_merged_results.md)
if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results).
if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results).**(PREMIUM)**
```plaintext
```plaintext
POST /projects/:id/merge_requests/:merge_request_iid/pipelines
POST /projects/:id/merge_requests/:merge_request_iid/pipelines
...
@@ -1375,7 +1375,7 @@ Must include at least one non-required attribute from above.
...
@@ -1375,7 +1375,7 @@ Must include at least one non-required attribute from above.
}
}
```
```
Users on GitLab Premium or higher also see
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
the `approvals_before_merge` parameter:
the `approvals_before_merge` parameter:
```json
```json
...
@@ -1561,7 +1561,7 @@ Parameters:
...
@@ -1561,7 +1561,7 @@ Parameters:
}
}
```
```
Users on GitLab Premium also see
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
the `approvals_before_merge` parameter:
the `approvals_before_merge` parameter:
```json
```json
...
@@ -1750,7 +1750,7 @@ Parameters:
...
@@ -1750,7 +1750,7 @@ Parameters:
}
}
```
```
Users on GitLab Premium or higher also see
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
the `approvals_before_merge` parameter:
the `approvals_before_merge` parameter:
```json
```json
...
@@ -2051,7 +2051,7 @@ Example response:
...
@@ -2051,7 +2051,7 @@ Example response:
}
}
```
```
Users on GitLab Premium also see
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
the `approvals_before_merge` parameter:
the `approvals_before_merge` parameter:
```json
```json
...
@@ -2211,7 +2211,7 @@ Example response:
...
@@ -2211,7 +2211,7 @@ Example response:
}
}
```
```
Users on GitLab Premium or higher also see
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
| `state` | string | optional | Return only `active` or `closed` milestones |
| `state` | string | optional | Return only `active` or `closed` milestones |
| `title` | string | optional | Return only the milestones having the given `title` |
| `title` | string | optional | Return only the milestones having the given `title` |
| `search` | string | optional | Return only milestones with a title or description matching the provided string |
| `search` | string | optional | Return only milestones with a title or description matching the provided string |
| `include_parent_milestones` | boolean | optional | Include group milestones from parent group and its ancestors. Introduced in [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) |
| `include_parent_milestones` | boolean | optional | Include group milestones from parent group and its ancestors. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) in GitLab 13.4 |