- List groups
- List a group’s subgroups
- List a group’s descendant groups
- List a group’s projects
- List a group’s shared projects
- Details of a group
- New group
- New Subgroup
- Transfer project to group
- Transfer a group to a new parent group / Turn a subgroup to a top-level group
- Update group
- Remove group
- Restore group marked for deletion
- Search for group
- List provisioned users
- Hooks
- Group Audit Events
- Sync group with LDAP
- Group members
- LDAP Group Links
- Namespaces in groups
- Group badges
- Group Import/Export
- Share Groups with Groups
- Push Rules
Groups API
List groups
Get a list of visible groups for the authenticated user. When accessed without authentication, only public groups are returned.
By default, this request returns 20 results at a time because the API results are paginated.
When accessed without authentication, this endpoint also supports keyset pagination:
- When requesting consecutive pages of results, we recommend you use keyset pagination.
- Beyond a specific offset limit (specified by max offset allowed by the REST API for offset-based pagination), offset pagination is unavailable.
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
skip_groups |
array of integers | no | Skip the group IDs passed |
all_available |
boolean | no | Show all the groups you have access to (defaults to false for authenticated users, true for administrators); Attributes owned and min_access_level have precedence |
search |
string | no | Return the list of authorized groups matching the search criteria |
order_by |
string | no | Order groups by name , path , id , or similarity (if searching, introduced in GitLab 14.1). Default is name
|
sort |
string | no | Order groups in asc or desc order. Default is asc
|
statistics |
boolean | no | Include group statistics (administrators only) |
with_custom_attributes |
boolean | no | Include custom attributes in response (administrators only) |
owned |
boolean | no | Limit to groups explicitly owned by the current user |
min_access_level |
integer | no | Limit to groups where current user has at least this access level |
top_level_only |
boolean | no | Limit to top level groups, excluding all subgroups |
GET /groups
[
{
"id": 1,
"name": "Foobar Group",
"path": "foo-bar",
"description": "An interesting group",
"visibility": "public",
"share_with_group_lock": false,
"require_two_factor_authentication": false,
"two_factor_grace_period": 48,
"project_creation_level": "developer",
"auto_devops_enabled": null,
"subgroup_creation_level": "owner",
"emails_disabled": null,
"mentions_disabled": null,
"lfs_enabled": true,
"default_branch_protection": 2,
"avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
"web_url": "http://localhost:3000/groups/foo-bar",
"request_access_enabled": false,
"full_name": "Foobar Group",
"full_path": "foo-bar",
"file_template_project_id": 1,
"parent_id": null,
"created_at": "2020-01-15T12:36:29.590Z"
}
]
When adding the parameter statistics=true
and the authenticated user is an administrator, additional group statistics are returned.
GET /groups?statistics=true
[
{
"id": 1,
"name": "Foobar Group",
"path": "foo-bar",
"description": "An interesting group",
"visibility": "public",
"share_with_group_lock": false,
"require_two_factor_authentication": false,
"two_factor_grace_period": 48,
"project_creation_level": "developer",
"auto_devops_enabled": null,
"subgroup_creation_level": "owner",
"emails_disabled": null,
"mentions_disabled": null,
"lfs_enabled": true,
"default_branch_protection": 2,
"avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
"web_url": "http://localhost:3000/groups/foo-bar",
"request_access_enabled": false,
"full_name": "Foobar Group",
"full_path": "foo-bar",
"file_template_project_id": 1,
"parent_id": null,
"created_at": "2020-01-15T12:36:29.590Z",
"statistics": {
"storage_size": 363,
"repository_size": 33,
"wiki_size": 100,
"lfs_objects_size": 123,
"job_artifacts_size": 57,
"pipeline_artifacts_size": 0,
"packages_size": 0,
"snippets_size": 50,
"uploads_size": 0
}
}
]
You can search for groups by name or path, see below.
You can filter by custom attributes with:
GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value
List a group’s subgroups
Introduced in GitLab 10.3.
Get a list of visible direct subgroups in this group. When accessed without authentication, only public groups are returned.
By default, this request returns 20 results at a time because the API results are paginated.
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group of the immediate parent group |
skip_groups |
array of integers | no | Skip the group IDs passed |
all_available |
boolean | no | Show all the groups you have access to (defaults to false for authenticated users, true for administrators); Attributes owned and min_access_level have precedence |
search |
string | no | Return the list of authorized groups matching the search criteria. Only subgroup short paths are searched (not full paths) |
order_by |
string | no | Order groups by name , path or id . Default is name
|
sort |
string | no | Order groups in asc or desc order. Default is asc
|
statistics |
boolean | no | Include group statistics (administrators only) |
with_custom_attributes |
boolean | no | Include custom attributes in response (administrators only) |
owned |
boolean | no | Limit to groups explicitly owned by the current user |
min_access_level |
integer | no | Limit to groups where current user has at least this access level |
GET /groups/:id/subgroups
[
{
"id": 1,
"name": "Foobar Group",
"path": "foo-bar",
"description": "An interesting group",
"visibility": "public",
"share_with_group_lock": false,
"require_two_factor_authentication": false,
"two_factor_grace_period": 48,
"project_creation_level": "developer",
"auto_devops_enabled": null,
"subgroup_creation_level"