diff options
Diffstat (limited to 'doc/api/groups.md')
-rw-r--r-- | doc/api/groups.md | 85 |
1 files changed, 84 insertions, 1 deletions
diff --git a/doc/api/groups.md b/doc/api/groups.md index ae3300e24fb..a74bb64816a 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -167,6 +167,89 @@ GET /groups/:id/subgroups ] ``` +## List a group's descendant groups + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217115) in GitLab 13.5 + +Get a list of visible descendant groups of 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](README.md#pagination). + +Parameters: + +| Attribute | Type | Required | Description | +| ------------------------ | ----------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) 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 admin). 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`, or `id`. Default is `name` | +| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | +| `statistics` | boolean | no | Include group statistics (admins only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins 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](members.md#valid-access-levels) | + +```plaintext +GET /groups/:id/descendant_groups +``` + +```json +[ + { + "id": 2, + "name": "Bar Group", + "path": "foo/bar", + "description": "A subgroup of Foo 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://gitlab.example.com/uploads/group/avatar/1/bar.jpg", + "web_url": "http://gitlab.example.com/groups/foo/bar", + "request_access_enabled": false, + "full_name": "Bar Group", + "full_path": "foo/bar", + "file_template_project_id": 1, + "parent_id": 123, + "created_at": "2020-01-15T12:36:29.590Z" + }, + { + "id": 3, + "name": "Baz Group", + "path": "foo/bar/baz", + "description": "A subgroup of Bar 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://gitlab.example.com/uploads/group/avatar/1/baz.jpg", + "web_url": "http://gitlab.example.com/groups/foo/bar/baz", + "request_access_enabled": false, + "full_name": "Baz Group", + "full_path": "foo/bar/baz", + "file_template_project_id": 1, + "parent_id": 123, + "created_at": "2020-01-15T12:36:29.590Z" + } +] +``` + ## List a group's projects Get a list of projects in this group. When accessed without authentication, only public projects are returned. @@ -696,7 +779,7 @@ This is similar to creating a [New group](#new-group). You'll need the `parent_i ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ - --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> } \ + --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \ "https://gitlab.example.com/api/v4/groups/" ``` |