Groups API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to view and manage GitLab groups. For more information, see groups.

Endpoint responses might vary based on the permissions of the authenticated user in the group.

Retrieve a group

Retrieve details of a group. This endpoint can be accessed without authentication if the group is publicly accessible. If the requesting user is an administrator, additional information is returned. With authentication, it returns the runners_token and enabled_git_access_protocol for the group if the user is an administrator or has the Owner role.

GET /groups/:id

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group.
`with_custom_attributes`	boolean	no	Include custom attributes in response (administrators only).
`with_projects`	boolean	no	Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, scheduled for removal in API v5. To get the details of all projects in a group, use the list a group’s projects endpoint.)

The projects and shared_projects attributes in the response are deprecated and scheduled for removal in API v5. To get the details of all projects within a group, use either the list a group’s projects or the list a group’s shared projects endpoint.

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4"

This endpoint returns a maximum of 100 projects and shared projects. To get the details of all projects within a group, use the list a group’s projects endpoint instead.

Example response:

json
{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "runners_token": "ba324ca7b1c77fc20bb9",
  "file_template_project_id": 1,
  "parent_id": null,
  "enabled_git_access_protocol": "all",
  "created_at": "2020-01-15T12:36:29.590Z",
  "shared_with_groups": [
    {
      "group_id": 28,
      "group_name": "H5bp",
      "group_full_path": "h5bp",
      "group_access_level": 20,
      "expires_at": null
    }
  ],
  "prevent_sharing_groups_outside_hierarchy": false,
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "public",
      "ssh_url_to_repo": "[email protected]:twitter/typeahead-js.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git",
      "web_url": "https://gitlab.example.com/twitter/typeahead-js",
      "name": "Typeahead.Js",
      "name_with_namespace": "Twitter / Typeahead.Js",
      "path": "typeahead-js",
      "path_with_namespace": "twitter/typeahead-js",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:25.578Z",
      "last_activity_at": "2016-06-17T07:47:25.881Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "[email protected]:twitter/flight.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git",
      "web_url": "https://gitlab.example.com/twitter/flight",
      "name": "Flight",
      "name_with_namespace": "Twitter / Flight",
      "path": "flight",
      "path_with_namespace": "twitter/flight",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:24.661Z",
      "last_activity_at": "2016-06-17T07:47:24.838Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "shared_projects": [ // Deprecated and will be removed in API v5
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "private",
      "ssh_url_to_repo": "[email protected]:h5bp/html5-boilerplate.git",
      "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "H5bp / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:27.089Z",
      "last_activity_at": "2016-06-17T07:47:27.310Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "H5bp",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
      "public_jobs": true,
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
          "group_full_path": "twitter",
          "group_access_level": 30,
          "expires_at": null
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
          "group_full_path": "gitlab-org",
          "group_access_level": 10,
          "expires_at": "2018-08-14"
        }
      ]
    }
  ],
  "ip_restriction_ranges": null,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "require_sha_for_merge": false,
  "lock_require_sha_for_merge": false
}

The prevent_sharing_groups_outside_hierarchy attribute is present only on top-level groups.

Users of GitLab Premium or Ultimate also see the attributes:

shared_runners_minutes_limit
extra_shared_runners_minutes_limit
marked_for_deletion_on
membership_lock
wiki_access_level
duo_features_enabled
lock_duo_features_enabled
duo_availability
experiment_features_enabled

Additional response attributes:

json
{
  "id": 4,
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "marked_for_deletion_on": "2020-04-03",
  "membership_lock": false,
  "wiki_access_level": "disabled",
  "duo_features_enabled": true,
  "lock_duo_features_enabled": false,
  "duo_availability": "default_on",
  "experiment_features_enabled": false,
  "ai_settings": {
    "duo_agent_platform_enabled": true,
    "duo_workflow_mcp_enabled": false,
    "foundational_agents_default_enabled": true,
    "ai_catalog_restricted_to_group_hierarchy": false,
    "ai_usage_data_collection_enabled": false,
    "prompt_injection_protection_level": "no_checks",
    "web_search_enabled": false,
    "include_recommended_allowed": false,
    "allow_all_unix_sockets": false,
    "allow_project_extension": true,
    "minimum_access_level_execute": "developer",
    "minimum_access_level_execute_async": "developer",
    "minimum_access_level_manage": "maintainer",
    "minimum_access_level_enable_on_projects": "maintainer"
  },
  ...
}

The ai_settings object contains the AI-related settings for the group. For details, see Response attributes for ai_settings.

Response attributes for `ai_settings`

The ai_settings object is included in the response for users who can read the group, when GitLab Duo Agent Platform is available for the group. The object contains the following attributes:

Attribute	Type	Description
`ai_catalog_restricted_to_group_hierarchy`	boolean	When `true`, the AI Catalog is restricted to items in this top-level group hierarchy. Premium and Ultimate only.
`ai_usage_data_collection_enabled`	boolean	When `true`, AI usage data collection is enabled for this group. GitLab.com only.
`allow_all_unix_sockets`	boolean	When `true`, all Unix sockets are allowed for GitLab Duo Agent Platform.
`allow_project_extension`	boolean	When `true`, projects can extend the network access domain allowlist for GitLab Duo Agent Platform.
`duo_agent_platform_enabled`	boolean	When `true`, GitLab Duo Agent Platform features are enabled for this group. Premium and Ultimate. Also available on the Free tier on GitLab.com with GitLab Credits.
`duo_workflow_mcp_enabled`	boolean	When `true`, MCP support for GitLab Duo Agent Platform is enabled. Premium and Ultimate. Also available on the Free tier on GitLab.com with GitLab Credits.
`foundational_agents_default_enabled`	boolean	When `true`, new foundational agents are enabled by default for this group. Premium and Ultimate. Also available on the Free tier on GitLab.com with GitLab Credits.
`include_recommended_allowed`	boolean	When `true`, recommended domains are included in the network access allowlist for GitLab Duo Agent Platform.
`minimum_access_level_enable_on_projects`	string	The minimum access level required to enable GitLab Duo Agent Platform on projects. One of `developer`, `maintainer`, or `owner`. Returned when the `dap_group_customizable_permissions` feature flag is enabled.
`minimum_access_level_execute`	string	The minimum access level required for users to interact with GitLab Duo Agent Platform features. One of `guest`, `planner`, `reporter`, `developer`, `maintainer`, or `owner`. Returned when the `dap_group_customizable_permissions` feature flag is enabled.
`minimum_access_level_execute_async`	string	The minimum access level required to execute GitLab Duo Agent Platform features in CI/CD. One of `developer`, `maintainer`, or `owner`. Returned when the `dap_group_customizable_permissions` feature flag is enabled.
`minimum_access_level_manage`	string	The minimum access level required to manage GitLab Duo Agent Platform. One of `developer`, `maintainer`, or `owner`. Returned when the `dap_group_customizable_permissions` feature flag is enabled.
`prompt_injection_protection_level`	string	The prompt injection protection level. One of `no_checks`, `log_only`, or `interrupt`.
`web_search_enabled`	boolean	When `true`, web search is enabled in GitLab Duo Chat for this group.

When adding the parameter with_projects=false, projects aren’t returned.

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4?with_projects=false"

Example response:

json
{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "file_template_project_id": 1,
  "parent_id": null
}

List groups

List all groups

List 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, you should 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	When `true`, returns all accessible groups. When `false`, returns only groups where the user is a member. Defaults to `false` for users, `true` for administrators. Unauthenticated requests always return all public groups. The `owned` and `min_access_level` attributes take 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`. Default is `name`.
`sort`	string	no	Order groups in `asc` or `desc` order. Default is `asc`.
`statistics`	boolean	no	Include group statistics (administrators only). For top-level groups, the response returns the full `root_storage_statistics` data displayed in the UI. Introduced in GitLab 17.4.
`visibility`	string	no	Limit to groups with `public`, `internal`, or `private` visibility.
`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 the specified access level. Possible values: `10` (Guest), `15` (Planner), `20` (Reporter), `25` (Security Manager), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`top_level_only`	boolean	no	Limit to top-level groups, excluding all subgroups.
`repository_storage`	string	no	Filter by repository storage used by the group (administrators only). Premium and Ultimate only.
`marked_for_deletion_on`	date	no	Filter by date when group was marked for deletion. Introduced in GitLab 17.1. Premium and Ultimate only.
`active`	boolean	no	Limit by groups that are not archived and not marked for deletion.
`archived`	boolean	no	Limit by groups that are archived. Introduced in GitLab 18.2.

GET /groups

json
[
  {
    "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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "ip_restriction_ranges": null
  }
]

When adding the parameter statistics=true and the authenticated user is an administrator, additional group statistics are returned. For top-level groups, root_storage_statistics are added as well.

GET /groups?statistics=true

When the parameter statistics=true is used and the authenticated user is an administrator, the response includes information about container registry storage size:

container_registry_size: Total storage size in bytes used by all container repositories in the group and its subgroups. Calculated as the sum of all repository sizes within the group’s projects and subgroups. Available only when the container registry metadata database is enabled.
container_registry_size_is_estimated: Indicates whether the size is an exact calculation based on actual data from all repositories (false) or estimated due to performance constraints (true).

For GitLab Self-Managed instances, the container registry metadata database must be enabled to include the container registry size attributes.

json
[
  {
    "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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "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
    },
    "root_storage_statistics": {
      "build_artifacts_size": 0,
      "container_registry_size": 0,
      "container_registry_size_is_estimated": false,
      "dependency_proxy_size": 0,
      "lfs_objects_size": 0,
      "packages_size": 0,
      "pipeline_artifacts_size": 0,
      "repository_size": 0,
      "snippets_size": 0,
      "storage_size": 0,
      "uploads_size": 0,
      "wiki_size": 0
  },
    "wiki_access_level": "private",
    "duo_features_enabled": true,
    "lock_duo_features_enabled": false,
    "duo_availability": "default_on",
    "experiment_features_enabled": false,
  }
]

Users of GitLab Premium or Ultimate also see the wiki_access_level, duo_features_enabled, lock_duo_features_enabled, duo_availability, and experiment_features_enabled attributes.

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

Group pagination

By default, only 20 groups are displayed at a time because the API results are paginated.

To get more (up to 100), pass the following as an argument to the API call:

/groups?per_page=100

And to switch pages add:

/groups?per_page=100&page=2

Search for a group

Search for groups that match a string in their name or path.

GET /groups?search=foobar

json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]

List group details

List projects

List projects in a group. When accessed without authentication, only public projects are returned.

By default, this request returns 20 results at a time because the API results are paginated.

GET /groups/:id/projects

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group.
`active`	boolean	no	Limit by project status. When `true`, returns active projects. When `false`, returns projects that are archived or marked for deletion. Introduced in GitLab 18.8.
`archived`	boolean	no	Limit by archived status.
`visibility`	string	no	Limit by visibility `public`, `internal`, or `private`.
`order_by`	string	no	Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity`¹, `star_count` or `last_activity_at` fields. Default is `created_at`.
`sort`	string	no	Return projects sorted in `asc` or `desc` order. Default is `desc`.
`search`	string	no	Return list of authorized projects matching the search criteria.
`simple`	boolean	no	Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned.
`owned`	boolean	no	Limit by projects owned by the current user.
`starred`	boolean	no	Limit by projects starred by the current user.
`topic`	string	no	Return projects matching the topic.
`with_issues_enabled`	boolean	no	Limit by projects with issues feature enabled. Default is `false`.
`with_merge_requests_enabled`	boolean	no	Limit by projects with merge requests feature enabled. Default is `false`.
`with_shared`	boolean	no	Include projects shared to this group. Default is `true`.
`include_subgroups`	boolean	no	Include projects in subgroups of this group. Default is `false`.
`min_access_level`	integer	no	Limit to projects where current user has at least the specified access level. Possible values: `10` (Guest), `15` (Planner), `20` (Reporter), `25` (Security Manager), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`with_custom_attributes`	boolean	no	Include custom attributes in response (administrators only).
`with_security_reports`	boolean	no	Return only projects that have security reports artifacts present in any of their builds. This means “projects with security reports enabled”. Default is `false`. Ultimate only.

Example response:

json
[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "main",
    "tag_list": [], //deprecated, use `topics` instead
    "topics": [],
    "archived": false,
    "visibility": "internal",
    "ssh_url_to_repo": "[email protected]/html5-boilerplate.git",
    "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
    "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
    "name": "Html5 Boilerplate",
    "name_with_namespace": "Experimental / Html5 Boilerplate",
    "path": "html5-boilerplate",
    "path_with_namespace": "h5bp/html5-boilerplate",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
    "jobs_enabled": true,
    "snippets_enabled": true,
    "created_at": "2016-04-05T21:40:50.169Z",
    "last_activity_at": "2016-04-06T16:52:08.432Z",
    "shared_runners_enabled": true,
    "creator_id": 1,
    "namespace": {
      "id": 5,
      "name": "Experimental",
      "path": "h5bp",
      "kind": "group"
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
    "public_jobs": true,
    "shared_with_groups": [],
    "request_access_enabled": false
  }
]

To distinguish between a project in the group and a project shared to the group, the namespace attribute can be used. When a project has been shared to the group, its namespace differs from the group the request is being made for.

List shared projects

List projects shared to a group. When accessed without authentication, only public shared projects are returned.

By default, this request returns 20 results at a time because the API results are paginated.

GET /groups/:id/projects/shared

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group.
`archived`	boolean	no	Limit by archived status.
`visibility`	string	no	Limit by visibility `public`, `internal`, or `private`.
`order_by`	string	no	Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `star_count` or `last_activity_at` fields. Default is `created_at`.
`sort`	string	no	Return projects sorted in `asc` or `desc` order. Default is `desc`.
`search`	string	no	Return list of authorized projects matching the search criteria.
`simple`	boolean	no	Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned.
`starred`	boolean	no	Limit by projects starred by the current user.
`with_issues_enabled`	boolean	no	Limit by projects with issues feature enabled. Default is `false`.
`with_merge_requests_enabled`	boolean	no	Limit by projects with merge requests feature enabled. Default is `false`.
`min_access_level`	integer	no	Limit to projects where current user has at least the specified access level. Possible values: `10` (Guest), `15` (Planner), `20` (Reporter), `25` (Security Manager), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`with_custom_attributes`	boolean	no	Include custom attributes in response (administrators only).

Example response:

json
[
   {
      "id":8,
      "description":"Shared project for Html5 Boilerplate",
      "name":"Html5 Boilerplate",
      "name_with_namespace":"H5bp / Html5 Boilerplate",
      "path":"html5-boilerplate",
      "path_with_namespace":"h5bp/html5-boilerplate",
      "created_at":"2020-04-27T06:13:22.642Z",
      "default_branch":"main",
      "tag_list":[], //deprecated, use `topics` instead
      "topics":[],
      "ssh_url_to_repo":"ssh://[email protected]/h5bp/html5-boilerplate.git",
      "http_url_to_repo":"https://gitlab.com/h5bp/html5-boilerplate.git",
      "web_url":"https://gitlab.com/h5bp/html5-boilerplate",
      "readme_url":"https://gitlab.com/h5bp/html5-boilerplate/-/blob/main/README.md",
      "avatar_url":null,
      "star_count":0,
      "forks_count":4,
      "last_activity_at":"2020-04-27T06:13:22.642Z",
      "namespace":{
         "id":28,
         "name":"H5bp",
         "path":"h5bp",
         "kind":"group",
         "full_path":"h5bp",
         "parent_id":null,
         "avatar_url":null,
         "web_url":"https://gitlab.com/groups/h5bp"
      },
      "_links":{
         "self":"https://gitlab.com/api/v4/projects/8",
         "issues":"https://gitlab.com/api/v4/projects/8/issues",
         "merge_requests":"https://gitlab.com/api/v4/projects/8/merge_requests",
         "repo_branches":"https://gitlab.com/api/v4/projects/8/repository/branches",
         "labels":"https://gitlab.com/api/v4/projects/8/labels",
         "events":"https://gitlab.com/api/v4/projects/8/events",
         "members":"https://gitlab.com/api/v4/projects/8/members"
      },
      "empty_repo":false,
      "archived":false,
      "visibility":"public",
      "resolve_outdated_diff_discussions":false,
      "container_registry_enabled":true,
      "container_expiration_policy":{
         "cadence":"7d",
         "enabled":true,
         "keep_n":null,
         "older_than":null,
         "name_regex":null,
         "name_regex_keep":null,
         "next_run_at":"2020-05-04T06:13:22.654Z"
      },
      "issues_enabled":true,
      "merge_requests_enabled":true,
      "wiki_enabled":true,
      "jobs_enabled":true,
      "snippets_enabled":true,
      "can_create_merge_request_in":true,
      "issues_access_level":"enabled",
      "repository_access_level":"enabled",
      "merge_requests_access_level":"enabled",
      "forking_access_level":"enabled",
      "wiki_access_level":"enabled",
      "builds_access_level":"enabled",
      "snippets_access_level":"enabled",
      "pages_access_level":"enabled",
      "security_and_compliance_access_level":"enabled",
      "emails_disabled":null,
      "emails_enabled": null,
      "shared_runners_enabled":true,
      "lfs_enabled":true,
      "creator_id":1,
      "import_status":"failed",
      "open_issues_count":10,
      "ci_default_git_depth":50,
      "ci_forward_deployment_enabled":true,
      "ci_forward_deployment_rollback_allowed": true,
      "ci_allow_fork_pipelines_to_run_in_parent_project":true,
      "public_jobs":true,
      "build_timeout":3600,
      "auto_cancel_pending_pipelines":"enabled",
      "ci_config_path":null,
      "shared_with_groups":[
         {
            "group_id":24,
            "group_name":"Commit451",
            "group_full_path":"Commit451",
            "group_access_level":30,
            "expires_at":null
         }
      ],
      "only_allow_merge_if_pipeline_succeeds":false,
      "request_access_enabled":true,
      "only_allow_merge_if_all_discussions_are_resolved":false,
      "remove_source_branch_after_merge":true,
      "printing_merge_request_link_enabled":true,
      "merge_method":"merge",
      "suggestion_commit_message":null,
      "auto_devops_enabled":true,
      "auto_devops_deploy_strategy":"continuous",
      "autoclose_referenced_issues":true,
      "repository_storage":"default"
   }
]

Delete a shared project

Delete a project shared to a group. Requires the Owner role for the group.

DELETE /groups/:id/shared_projects/:project_id

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group.
`project_id`	integer	yes	The ID of the project.

If successful, returns 204 No Content.

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/shared_projects/2"

List all SAML users

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Lists all SAML users for a given top-level group.

Use the page and per_page pagination parameters to filter the results.

GET /groups/:id/saml_users

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	yes	ID or URL-encoded path of a top-level group.
`username`	string	no	Return a user with a given username.
`search`	string	no	Return users with a matching name, email, or username. Use partial values to increase results.
`active`	boolean	no	Return only active users.
`blocked`	boolean	no	Return only blocked users.
`created_after`	datetime	no	Return users created after the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
`created_before`	datetime	no	Return users created before the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).

Example request:

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/saml_users"

Example response:

json
[
  {
    "id": 66,
    "username": "user22",
    "name": "Sidney Jones22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "[email protected]",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [
      {
        "provider": "group_saml",
        "extern_uid": "2435223452345",
        "saml_provider_id": 1
      }
    ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "[email protected]",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null,
    "scim_identities": [
      {
        "extern_uid": "2435223452345",
        "group_id": 1,
        "active": true
      }
    ]
  },
  ...
]

List provisioned users

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

List users provisioned by a group. Does not include subgroups.

Requires the Maintainer or Owner role on the group.

GET /groups/:id/provisioned_users

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	ID or URL-encoded path of the group.
`username`	string	no	Return single user with a specific username.
`search`	string	no	Search users by name, email, username.
`active`	boolean	no	Return only active users.
`blocked`	boolean	no	Return only blocked users.
`created_after`	datetime	no	Return users created after the specified time.
`created_before`	datetime	no	Return users created before the specified time.

Example response:

json
[
  {
    "id": 66,
    "username": "user22",
    "name": "John Doe22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "[email protected]",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [ ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "[email protected]",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null
  },
  ...
]

List subgroups

List visible direct subgroups in a group.

By default, this request returns 20 results at a time because the API results are paginated.

If you request this list as:

An unauthenticated user, the response returns only public groups.
An authenticated user, the response returns only the groups you’re a member of and does not include public groups.

Parameters:

Attribute	Type	Required	Description
`id`	integer or 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 the specified access level. Possible values: `10` (Guest), `15` (Planner), `20` (Reporter), `25` (Security Manager), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`all_available`	boolean	no	When `true`, returns all accessible groups. When `false`, returns only groups where the user is a member. Defaults to `false` for users, `true` for administrators. Unauthenticated requests always return all public groups. The `owned` and `min_access_level` attributes take precedence.
`active`	boolean	no	Limit by groups that are not archived and not marked for deletion.

GET /groups/:id/subgroups

json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": 

Groups API

Retrieve a group

Response attributes for ai_settings

List groups

List all groups

Group pagination

Search for a group

List group details

List projects

List shared projects

Delete a shared project

List all SAML users

List provisioned users

List subgroups

Response attributes for `ai_settings`