---
title: "Create a group"
method: POST
path: "/api/v4/groups"
tags: ["groups"]
---

# Create a group

`POST /api/v4/groups`

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/groups`
- Auth: none declared

Creates a project group. Available only for users who can create groups.

## Request body

- PostApiV4Groups: Create a group
  - `name` string, required: The name of the group
  - `path` string, required: The path of the group
  - `parent_id` integer: The parent group id for creating nested group
  - `organization_id` integer: The organization id for the group
  - `description` string: The description of the group
  - `visibility` 'private' | 'internal' | 'public': The visibility of the group
  - `avatar` string, binary: Avatar image for the group
  - `share_with_group_lock` boolean: Prevent sharing a project with another group within this group
  - `require_two_factor_authentication` boolean: Require all users in this group to setup Two-factor authentication
  - `two_factor_grace_period` integer: Time before Two-factor authentication is enforced
  - `project_creation_level` 'noone' | 'owner' | 'maintainer' | 'developer' | 'administrator': Determine if developers can create projects in the group
  - `auto_devops_enabled` boolean: Default to Auto DevOps pipeline for all projects within this group
  - `subgroup_creation_level` 'owner' | 'maintainer': Allowed to create subgroups
  - `emails_disabled` boolean: _(Deprecated)_ Disable email notifications. Use: emails_enabled
  - `emails_enabled` boolean: Enable email notifications
  - `show_diff_preview_in_email` boolean: Include the code diff preview in merge request notification emails
  - `mentions_disabled` boolean: Disable a group from getting mentioned
  - `lfs_enabled` boolean: Enable/disable LFS for the projects in this group
  - `request_access_enabled` boolean: Allow users to request member access
  - `default_branch` string: The default branch of group's projects
  - `default_branch_protection` 0 | 3 | 1 | 2 | 4: Determine if developers can push to default branch
  - `default_branch_protection_defaults` object: Determine if developers can push to default branch
    - `allowed_to_push` object[]: An array of access levels allowed to push
      - `access_level` 30 | 40 | 60 | 0, required: A valid access level
    - `allow_force_push` boolean: Allow force push for all users with push access.
    - `allowed_to_merge` object[]: An array of access levels allowed to merge
      - `access_level` 30 | 40 | 60 | 0, required: A valid access level
    - `code_owner_approval_required` boolean: Require approval from code owners
    - `developer_can_initial_push` boolean: Allow developers to initial push
  - `enabled_git_access_protocol` 'ssh' | 'http' | 'all': Allow only the selected protocols to be used for Git access.
  - `crm_enabled` boolean: Enable Customer Relations Management for this group
  - `resource_access_token_notify_inherited` boolean: Send access token expiry notifications to all inherited members of the group
  - `lock_resource_access_token_notify_inherited` boolean: Prevent subgroups from overriding the access token expiry notification setting
  - `membership_lock` boolean: Prevent adding new members to projects within this group
  - `ldap_cn` string: LDAP Common Name
  - `ldap_access` integer: A valid access level
  - `shared_runners_minutes_limit` integer: (admin-only) compute minutes quota for this group
  - `extra_shared_runners_minutes_limit` integer: (admin-only) Extra compute minutes quota for this group
  - `wiki_access_level` 'disabled' | 'private' | 'enabled': Wiki access level. One of `disabled`, `private` or `enabled`
  - `duo_availability` 'always_on' | 'default_on' | 'default_off' | 'never_on': Duo availability. One of `default_on`, `default_off`, `never_on` or `always_on`
  - `duo_remote_flows_availability` boolean: Enable GitLab Duo remote flows for this group
  - `duo_foundational_flows_availability` boolean: Enable GitLab foundational Duo flows for this group
  - `duo_custom_agents_availability` boolean: Enable GitLab Duo custom agents for this group
  - `duo_custom_flows_availability` boolean: Enable GitLab Duo custom flows for this group
  - `duo_external_agents_availability` boolean: Enable GitLab Duo external agents for this group
  - `tool_approval_for_session_availability` 'default_on' | 'default_off' | 'never_on': Tool approval for session availability. One of `default_on`, `default_off` or `never_on`
  - `amazon_q_auto_review_enabled` boolean: Enable Amazon Q auto review for merge request
  - `experiment_features_enabled` boolean: Enable experiment features for this group
  - `model_prompt_cache_enabled` boolean: Enable model prompt cache for this group
  - `foundational_agents_statuses` object[]: Whether each foundational agent has been enabled or disabled.
    - `reference` string, required: Reference of the foundational agent.
    - `enabled` boolean, required: Whether foundational agent has been enabled or disabled.
  - `ai_settings_attributes` object: AI-related settings
    - `duo_agent_platform_enabled` boolean: Whether Duo Agent Platform features are enabled
    - `duo_workflow_mcp_enabled` boolean: Enable MCP support for Duo Agent Platform
    - `ai_usage_data_collection_enabled` boolean: Enable AI usage data collection for this namespace
    - `ai_catalog_restricted_to_group_hierarchy` boolean: Confine the AI Catalog to items within this top-level group hierarchy
    - `web_search_enabled` boolean: Allow web search in GitLab Duo Chat for this top-level group
    - `foundational_agents_default_enabled` boolean: Whether new foundational agents are enabled by default
    - `prompt_injection_protection_level` 'no_checks' | 'log_only' | 'interrupt': Prompt injection protection level. One of `no_checks`, `log_only` or `interrupt`
    - `include_recommended_allowed` boolean: Whether to include recommended domains in the network access allowlist
    - `allow_all_unix_sockets` boolean: Whether to allow all Unix sockets for network access
    - `allow_project_extension` boolean: Whether to allow projects to extend the network access domain allowlist
    - `require_sandbox` boolean: Whether flows that run on GitLab Runner fail when the execution environment sandbox is unavailable
    - `minimum_access_level_execute` 10 | 15 | 20 | 30 | 40 | 50: The minimum access level required to execute Duo Agent Platform. This field is behind a feature flag.
    - `minimum_access_level_execute_async` 30 | 40 | 50: The minimum access level required to execute Duo Agent Platform features in CI/CD. This field is behind a feature flag.
    - `minimum_access_level_manage` 30 | 40 | 50: The minimum access level required to manage Duo Agent Platform. This field is behind a feature flag.
    - `minimum_access_level_enable_on_projects` 30 | 40 | 50: The minimum access level required to enable Duo Agent Platform. This field is behind a feature flag.

## Response `201`

Create a group

- APIEntitiesGroup: API_Entities_Group model
  - `id` integer, required
  - `web_url` string, required
  - `name` string, required
  - `path` string, required
  - `description` string, required
  - `visibility` string, required
  - `share_with_group_lock` boolean, required
  - `require_two_factor_authentication` boolean, required
  - `two_factor_grace_period` integer, required
  - `project_creation_level` string, required
  - `auto_devops_enabled` string, required
  - `subgroup_creation_level` string, required
  - `emails_disabled` boolean, required
  - `emails_enabled` boolean, required
  - `show_diff_preview_in_email` boolean, required
  - `mentions_disabled` string, required
  - `lfs_enabled` boolean, required
  - `archived` boolean, required
  - `math_rendering_limits_enabled` boolean, required
  - `lock_math_rendering_limits_enabled` boolean, required
  - `crm_enabled` boolean, required
  - `resource_access_token_notify_inherited` boolean, required
  - `lock_resource_access_token_notify_inherited` boolean, required
  - `default_branch` string, required
  - `default_branch_protection` integer, required
  - `default_branch_protection_defaults` string, required
  - `avatar_url` string, required
  - `request_access_enabled` boolean, required
  - `full_name` string, required
  - `full_path` string, required
  - `created_at` string, required
  - `parent_id` string, required
  - `organization_id` integer, required
  - `shared_runners_setting` string, required
  - `max_artifacts_size` integer, required
  - `custom_attributes` APIEntitiesCustomAttribute: API_Entities_CustomAttribute model
    - `key` string, required
    - `value` string, required
  - `statistics` object
    - `storage_size` string, required
    - `repository_size` string, required
    - `wiki_size` string, required
    - `lfs_objects_size` string, required
    - `job_artifacts_size` string, required
    - `pipeline_artifacts_size` string, required
    - `packages_size` string, required
    - `snippets_size` string, required
    - `uploads_size` string, required
  - `marked_for_deletion_on` string, required
  - `root_storage_statistics` APIEntitiesNamespaceRootStorageStatistics
    - `build_artifacts_size` integer, required: CI artifacts size in bytes.
    - `container_registry_size` integer, required: container registry size in bytes.
    - `container_registry_size_is_estimated` boolean, required: Indicates whether the deduplicated container registry size for the namespace is an estimated value or not.
    - `dependency_proxy_size` integer, required: Dependency Proxy sizes in bytes.
    - `lfs_objects_size` integer, required: LFS objects size in bytes.
    - `packages_size` integer, required: Packages size in bytes.
    - `pipeline_artifacts_size` integer, required: CI pipeline artifacts size in bytes.
    - `repository_size` integer, required: Git repository size in bytes.
    - `snippets_size` integer, required: Snippets size in bytes.
    - `storage_size` integer, required: Total storage in bytes.
    - `uploads_size` integer, required: Uploads size in bytes.
    - `wiki_size` integer, required: Wiki size in bytes.
  - `ldap_cn` string, required
  - `ldap_access` string, required
  - `ldap_group_links` APIEntitiesLdapGroupLink
    - `cn` string, required
    - `group_access` integer, required
    - `provider` string, required
    - `filter` string
    - `member_role_id` integer
  - `saml_group_links` APIEntitiesSamlGroupLink
    - `name` string, required
    - `access_level` integer, required
    - `member_role_id` integer
    - `provider` string, required
  - `file_template_project_id` string
  - `wiki_access_level` string, required
  - `repository_storage` string
  - `duo_core_features_enabled` boolean: [Experimental] Indicates whether GitLab Duo Core features are enabled for the group
  - `duo_features_enabled` string
  - `lock_duo_features_enabled` string
  - `auto_duo_code_review_enabled` string
  - `web_based_commit_signing_enabled` string
  - `allow_personal_snippets` string
  - `duo_namespace_access_rules` string
  - `built_in_project_templates_enabled` boolean
  - `lock_built_in_project_templates_enabled` boolean

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)