Project visibility level

Removals in API v5

Project merge method

List all projects

• Pagination limits

List user projects

List projects starred by a user

Get single project

• Templates for issues and merge requests

Get project users

List a project’s groups

List a project’s shareable groups

Get project events

Create project

Create project for user

Edit project

Fork project

List forks of a project

Star a project

Unstar a project

List starrers of a project

Languages

Archive a project

Unarchive a project

Delete project

Restore project marked for deletion

Upload a file

Upload a project avatar

Remove a project avatar

Share project with group

Delete a shared project link within a group

Import project members

Hooks

• List project hooks
• Get project hook
• Add project hook
• Edit project hook
• Delete project hook

Fork relationship

• Create a forked from/to relation between existing projects
• Delete an existing forked from relationship

Search for projects by name

Start the Housekeeping task for a project

Push rules

• Get project push rules
• Add project push rule
• Edit project push rule
• Delete project push rule

Get groups to which a user can transfer a project

Transfer a project to a new namespace

Branches

Project import/export

Project members

Project vulnerabilities

Get a project’s pull mirror details

Configure pull mirroring for a project

Start the pull mirroring process for a Project

Project badges

Download snapshot of a Git repository

Get the path to repository storage

Projects API

Interact with projects by using the REST API.

Project visibility level

A project in GitLab can be private, internal, or public. The visibility level is determined by the visibility field in the project.

For details, see Project visibility .

The fields returned in responses vary based on the permissions of the authenticated user.

Removals in API v5

These attributes are deprecated, and are scheduled to be removed in v5 of the API:

tag_list : Use the topics attribute instead.
• marked_for_deletion_at : Use the marked_for_deletion_on attribute instead. Available only to GitLab Premium or Ultimate .
• approvals_before_merge : Use the Merge request approvals API instead. Available only to GitLab Premium or Ultimate .

Project merge method

The merge_method can use these options:

merge : a merge commit is created for every merge, and merging is allowed if no conflicts are present.
• rebase_merge : a merge commit is created for every merge, but merging is only allowed if fast-forward merge is possible. You can make sure that the target branch would build after this merge request builds and merges.
• ff : no merge commits are created and all merges are fast-forwarded. Merging is only allowed if the branch could be fast-forwarded.

List all projects

The _links.cluster_agents attribute in the response was introduced in GitLab 15.0.

Get a list of all visible projects across GitLab for the authenticated user. When accessed without authentication, only public projects with simple fields are returned.

GET /projects
AttributeTypeRequiredDescription
archivedboolean NoLimit by archived status.
id_afterinteger NoLimit results to projects with IDs greater than the specified ID.
id_beforeinteger NoLimit results to projects with IDs less than the specified ID.
importedboolean NoLimit results to projects which were imported from external systems by current user.
last_activity_afterdatetime NoLimit results to projects with last activity after specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
last_activity_beforedatetime NoLimit results to projects with last activity before specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
membershipboolean NoLimit by projects that the current user is a member of.
min_access_levelinteger NoLimit by current user minimal role (access_level).
order_bystring NoReturn projects ordered by id, name, path, created_at, updated_at, last_activity_at, or similarity fields. repository_size, storage_size, packages_size or wiki_size fields are only allowed for administrators. similarity (introduced in GitLab 14.1) is only available when searching and is limited to projects that the current user is a member of. Default is created_at.
ownedboolean NoLimit by projects explicitly owned by the current user.
repository_checksum_failed 
boolean NoLimit projects where the repository checksum calculation has failed.
repository_storagestring NoLimit results to projects stored on repository_storage. (administrators only)
search_namespacesboolean NoInclude ancestor namespaces when matching search criteria. Default is false.
searchstring NoReturn list of projects matching the search criteria.
simpleboolean NoReturn only limited fields for each project. This operation is a no-op without authentication where only simple fields are returned.
sortstring NoReturn projects sorted in asc or desc order. Default is desc.
starredboolean NoLimit by projects starred by the current user.
statisticsboolean NoInclude project statistics. Available only to users with at least the Reporter role.
topicstring NoComma-separated topic names. Limit results to projects that match all of given topics. See topics attribute.
topic_idinteger NoLimit results to projects with the assigned topic given by the topic ID.
visibilitystring NoLimit by visibility public, internal, or private.
wiki_checksum_failed 
boolean NoLimit projects where the wiki checksum calculation has failed.
with_custom_attributesboolean NoInclude custom attributes in response. (administrator only)
with_issues_enabledboolean NoLimit by enabled issues feature.
with_merge_requests_enabledboolean NoLimit by enabled merge requests feature.
with_programming_languagestring NoLimit by projects which use the given programming language.
updated_beforedatetime NoLimit results to projects last updated before the specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Introduced in GitLab 15.10. For this filter to work, you must also provide updated_at as the order_by attribute.
updated_afterdatetime NoLimit results to projects last updated after the specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Introduced in GitLab 15.10. For this filter to work, you must also provide updated_at as the order_by attribute.
This endpoint supports keyset pagination
for selected order_by options.




    
When simple=true or the user is unauthenticated this returns something like:
Example request:
curl --request GET "https://gitlab.example.com/api/v4/projects"
Example response:
[
    "id": 4,
    "description": null,
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "created_at": "2013-09-30T13:46:02Z",
    "default_branch": "main",
    "tag_list": [
      "example",
      "disapora client"
    "topics": [
      "example",
      "disapora client"
    "ssh_url_to_repo": "[email protected]:diaspora/diaspora-client.git",
    "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
    "web_url": "https://gitlab.example.com/diaspora/diaspora-client",
    "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png",
    "star_count": 0,
    "last_activity_at": "2013-09-30T13:46:02Z",
    "namespace": {
      "id": 2,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora",
      "parent_id": null,
      "avatar_url": null,
      "web_url": "https://gitlab.example.com/diaspora"
When the user is authenticated and simple is not set this returns something like:
[
    "id": 4,
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "created_at": "2013-09-30T13:46:02Z",
    "updated_at": "2013-09-30T13:46:02Z",
    "default_branch": "main",
    "tag_list": [ //deprecated, use `topics` instead
      "example",
      "disapora client"
    "topics": [
      "example",
      "disapora client"
    "ssh_url_to_repo": "[email protected]:diaspora/diaspora-client.git",
    "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
    "web_url": "https://gitlab.example.com/diaspora/diaspora-client",
    "readme_url": "https://gitlab.example.com/diaspora/diaspora-client/blob/master/README.md",
    "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png",
    "forks_count": 0,
    "star_count": 0,
    "last_activity_at": "2022-06-24T17:11:26.841Z",
    "namespace": {
      "id": 3,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora",
      "parent_id": null,
      "avatar_url": "https://gitlab.example.com/uploads/project/avatar/6/uploads/avatar.png",
      "web_url": "https://gitlab.example.com/diaspora"
    "container_registry_image_prefix": "registry.gitlab.example.com/diaspora/diaspora-client",
    "_links": {
      "self": "https://gitlab.example.com/api/v4/projects/4",
      "issues": "https://gitlab.example.com/api/v4/projects/4/issues",
      "merge_requests": "https://gitlab.example.com/api/v4/projects/4/merge_requests",
      "repo_branches": "https://gitlab.example.com/api/v4/projects/4/repository/branches",
      "labels": "https://gitlab.example.com/api/v4/projects/4/labels",
      "events": "https://gitlab.example.com/api/v4/projects/4/events",
      "members": "https://gitlab.example.com/api/v4/projects/4/members",
      "cluster_agents": "https://gitlab.example.com/api/v4/projects/4/cluster_agents"
    "packages_enabled": true,
    "empty_repo": false,
    "archived": false,
    "visibility": "public",
    "resolve_outdated_diff_discussions": false,
    "container_expiration_policy": {
      "cadence": "1month",
      "enabled": true,
      "keep_n": 1,
      "older_than": "14d",
      "name_regex": "",
      "name_regex_keep": ".*-main",




    

      "next_run_at": "2022-06-25T17:11:26.865Z"
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
    "jobs_enabled": true,
    "snippets_enabled": true,
    "container_registry_enabled": true,
    "service_desk_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",
    "analytics_access_level": "enabled",
    "container_registry_access_level": "enabled",
    "security_and_compliance_access_level": "private",
    "emails_disabled": null,
    "shared_runners_enabled": true,
    "group_runners_enabled": true,
    "lfs_enabled": true,
    "creator_id": 1,
    "import_url": null,
    "import_type": null,
    "import_status": "none",
    "import_error": null,
    "open_issues_count": 0,
    "ci_default_git_depth": 20,
    "ci_forward_deployment_enabled": true,
    "ci_allow_fork_pipelines_to_run_in_parent_project": true,
    "ci_job_token_scope_enabled": false,
    "ci_separated_caches": true,
    "public_jobs": true,
    "build_timeout": 3600,
    "auto_cancel_pending_pipelines": "enabled",
    "ci_config_path": "",
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
    "allow_merge_on_skipped_pipeline": null,
    "restrict_user_defined_variables": 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",
    "squash_option": "default_off",
    "enforce_auth_checks_on_uploads": true,
    "suggestion_commit_message": null,
    "merge_commit_template": null,
    "squash_commit_template": null,
    "issue_branch_template": "gitlab/%{id}-%{title}",
    "auto_devops_enabled": false,
    "auto_devops_deploy_strategy": "continuous",
    "autoclose_referenced_issues": true,
    "keep_latest_artifact": true,
    "runner_token_expiration_interval": null,
    "external_authorization_classification_label": "",
    "requirements_enabled": false,
    "requirements_access_level": "enabled",
    "security_and_compliance_enabled": false,
    "compliance_frameworks": [],
    "permissions": {
      "project_access": null,
      "group_access": null
You can filter by custom attributes with:
GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value
Example request:
curl --globoff --request GET "https://gitlab.example.com/api/v4/projects?custom_attributes[location]=Antarctica&custom_attributes[role]=Developer"
Pagination limits
In GitLab 13.0 and later, offset-based pagination
is limited to 50,000 records.
Keyset pagination is required to retrieve
projects beyond this limit.
Keyset pagination supports only order_by=id. Other sorting options aren’t available.
List user projects
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.

Get a list of visible projects owned by the given user. When accessed without authentication, only public projects are returned.

Only the projects in the user’s (specified in user_id ) namespace are returned. Projects owned by the user in any group or subgroups are not returned. An empty list is returned if a profile is set to private.

This endpoint supports keyset pagination for selected order_by options.

GET /users/:user_id/projects
AttributeTypeRequiredDescription
user_idstring YesThe ID or username of the user.
archivedboolean NoLimit by archived status.
id_afterinteger NoLimit results to projects with IDs greater than the specified ID.
id_beforeinteger NoLimit results to projects with IDs less than the specified ID.
membershipboolean NoLimit by projects that the current user is a member of.
min_access_levelinteger NoLimit by current user minimal role (access_level).
order_bystring NoReturn projects ordered by id, name, path, created_at, updated_at, or last_activity_at fields. Default is created_at.
ownedboolean NoLimit by projects explicitly owned by the current user.
searchstring NoReturn list of projects matching the search criteria.
simpleboolean NoReturn only limited fields for each project. Without authentication, this operation is a no-op; only simple fields are returned.
sortstring NoReturn projects sorted in asc or desc order. Default is desc.
starredboolean NoLimit by projects starred by the current user.
statisticsboolean NoInclude project statistics. Available only to users with at least the Reporter role.
visibilitystring NoLimit by visibility public, internal, or private.
with_custom_attributesboolean NoInclude custom attributes in response. (administrator only)
with_issues_enabledboolean NoLimit by enabled issues feature.
with_merge_requests_enabledboolean NoLimit by enabled merge requests feature.
with_programming_languagestring NoLimit by projects which use the given programming language.
updated_beforedatetime NoLimit results to projects last updated before the specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Introduced in GitLab 15.10.
updated_afterdatetime NoLimit results to projects last updated after the specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Introduced in GitLab 15.10.
[




    

    "id": 4,
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
    "default_branch": "master",
    "visibility": "private",
    "ssh_url_to_repo": "[email protected]:diaspora/diaspora-client.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
    "web_url": "http://example.com/diaspora/diaspora-client",
    "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md",
    "tag_list": [ //deprecated, use `topics` instead
      "example",
      "disapora client"
    "topics": [
      "example",
      "disapora client"
    "owner": {
      "id": 3,
      "name": "Diaspora",
      "created_at": "2013-09-30T13:46:02Z"
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
    "can_create_merge_request_in": true,
    "resolve_outdated_diff_discussions": false,
    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
    "container_registry_access_level": "disabled",
    "security_and_compliance_access_level": "disabled",
    "created_at": "2013-09-30T13:46:02Z",
    "updated_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "import_url": null,
    "import_type": null,
    "import_status": "none",
    "import_error": null,
    "namespace": {
      "id": 3,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora"
    "import_status": "none",
    "archived": false,
    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
    "shared_runners_enabled": true,
    "group_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
    "ci_default_git_depth": 50,
    "ci_forward_deployment_enabled": true,
    "ci_allow_fork_pipelines_to_run_in_parent_project": true,
    "ci_separated_caches": true,
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
    "allow_merge_on_skipped_pipeline": false,
    "restrict_user_defined_variables": false,
    "only_allow_merge_if_all_discussions_are_resolved": false,
    "remove_source_branch_after_merge": false,
    "request_access_enabled": false,
    "merge_method": "merge",
    "squash_option": "default_on",
    "autoclose_referenced_issues": true,
    "enforce_auth_checks_on_uploads": true,
    "suggestion_commit_message": null,
    "merge_commit_template": null,
    "squash_commit_template": null,
    "issue_branch_template": "gitlab/%{id}-%{title}",
    "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on
    "marked_for_deletion_on": "2020-04-03",
    "statistics": {
      "commit_count": 37,
      "storage_size": 1038090,
      "repository_size": 1038090,
      "wiki_size" : 0,
      "lfs_objects_size": 0,
      "job_artifacts_size": 0,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 0,
      "uploads_size": 0
    "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
    




    
"_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members",
      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
    "id": 6,
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
    "default_branch": "master",
    "visibility": "private",
    "ssh_url_to_repo": "[email protected]:brightbox/puppet.git",
    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
    "web_url": "http://example.com/brightbox/puppet",
    "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md",
    "tag_list": [ //deprecated, use `topics` instead
      "example",
      "puppet"
    "topics": [
      "example",
      "puppet"
    "owner": {
      "id": 4,
      "name": "Brightbox",
      "created_at": "2013-09-30T13:46:02Z"
    "name": "Puppet",
    "name_with_namespace": "Brightbox / Puppet",
    "path": "puppet",
    "path_with_namespace": "brightbox/puppet",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
    "can_create_merge_request_in": true,
    "resolve_outdated_diff_discussions": false,
    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
    "container_registry_access_level": "disabled",
    "security_and_compliance_access_level": "disabled",
    "created_at": "2013-09-30T13:46:02Z",
    "updated_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "import_url": null,
    "import_type": null,
    "import_status": "none",
    "import_error": null,
    "namespace": {
      "id": 4,
      "name": "Brightbox",
      "path": "brightbox",
      "kind": "group",
      "full_path": "brightbox"
    "import_status": "none",
    "import_error": null,
    "permissions": {
      "project_access": {
        "access_level": 10,
        "notification_level": 3
      "group_access": {
        "access_level": 50,
        "notification_level": 3
    "archived": false,
    "avatar_url": null,
    "shared_runners_enabled": true,
    "group_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
    "ci_default_git_depth": 0,
    "ci_forward_deployment_enabled": true,
    "ci_allow_fork_pipelines_to_run_in_parent_project": true,
    "ci_separated_caches": true,
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
    "allow_merge_on_skipped_pipeline": false,
    "restrict_user_defined_variables": false,
    "only_allow_merge_if_all_discussions_are_resolved": false,
    "remove_source_branch_after_merge": false,
    "request_access_enabled": false,
    "merge_method": "merge",
    "squash_option": "default_on",
    "auto_devops_enabled": true,
    "auto_devops_deploy_strategy": "continuous",
    "repository_storage": "default",
    "approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
    "mirror": false,
    "mirror_user_id": 45,
    "mirror_trigger_builds": false,
    "only_mirror_protected_branches": false,
    "mirror_overwrites_diverged_branches": false,
    "external_authorization_classification_label": null,
    "packages_enabled": true,
    "service_desk_enabled": false,
    "service_desk_address": null,
    "autoclose_referenced_issues": true,
    "enforce_auth_checks_on_uploads": true,
    "suggestion_commit_message": null,
    




    
"merge_commit_template": null,
    "squash_commit_template": null,
    "issue_branch_template": "gitlab/%{id}-%{title}",
    "statistics": {
      "commit_count": 12,
      "storage_size": 2066080,
      "repository_size": 2066080,
      "wiki_size" : 0,
      "lfs_objects_size": 0,
      "job_artifacts_size": 0,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 0,
      "uploads_size": 0
    "container_registry_image_prefix": "registry.example.com/brightbox/puppet",
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members",
      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
List projects starred by a user
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.

Get a list of visible projects starred by the given user. When accessed without authentication, only public projects are returned.

GET /users/:user_id/starred_projects
AttributeTypeRequiredDescription
user_idstring YesThe ID or username of the user.
archivedboolean NoLimit by archived status.
membershipboolean NoLimit by projects that the current user is a member of.
min_access_levelinteger NoLimit by current user minimal role (access_level).
order_bystring NoReturn projects ordered by id, name, path, created_at, updated_at, or last_activity_at fields. Default is created_at.
ownedboolean NoLimit by projects explicitly owned by the current user.
searchstring NoReturn list of projects matching the search criteria.
simpleboolean NoReturn only limited fields for each project. Without authentication, this operation is a no-op; only simple fields are returned.
sortstring NoReturn projects sorted in asc or desc order. Default is desc.
starredboolean NoLimit by projects starred by the current user.
statisticsboolean NoInclude project statistics. Available only to users with at least the Reporter role.
visibilitystring NoLimit by visibility public, internal, or private.
with_custom_attributesboolean NoInclude custom attributes in response. (administrator only)
with_issues_enabledboolean NoLimit by enabled issues feature.
with_merge_requests_enabledboolean NoLimit by enabled merge requests feature.
updated_beforedatetime NoLimit results to projects last updated before the specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Introduced in GitLab 15.10.
updated_afterdatetime NoLimit results to projects last updated after the specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Introduced in GitLab 15.10.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/5/starred_projects"
Example response:
[
    "id": 4,
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
    "default_branch": "master",
    "visibility": "private",
    "ssh_url_to_repo": "[email protected]:diaspora/diaspora-client.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
    "web_url": "http://example.com/diaspora/diaspora-client",
    "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md",
    "tag_list": [ //deprecated, use `topics` instead
      "example",
      "disapora client"
    "topics": [
      "example",
      "disapora client"
    "owner": {
      "id": 3,
      "name": "Diaspora",
      "created_at": "2013-09-30T13:46:02Z"
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
    "can_create_merge_request_in": true,
    "resolve_outdated_diff_discussions": false,
    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
    "container_registry_access_level": "disabled",
    "security_and_compliance_access_level": "disabled",
    "created_at": "2013-09-30T13:46:02Z",
    "updated_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "namespace": {
      "id": 3,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora"
    "import_status":




    
 "none",
    "archived": false,
    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
    "shared_runners_enabled": true,
    "group_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
    "allow_merge_on_skipped_pipeline": false,
    "restrict_user_defined_variables": false,
    "only_allow_merge_if_all_discussions_are_resolved": false,
    "remove_source_branch_after_merge": false,
    "request_access_enabled": false,
    "merge_method": "merge",
    "squash_option": "default_on",
    "autoclose_referenced_issues": true,
    "enforce_auth_checks_on_uploads": true,
    "suggestion_commit_message": null,
    "merge_commit_template": null,
    "squash_commit_template": null,
    "issue_branch_template": "gitlab/%{id}-%{title}",
    "statistics": {
      "commit_count": 37,
      "storage_size": 1038090,
      "repository_size": 1038090,
      "lfs_objects_size": 0,
      "job_artifacts_size": 0,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 0,
      "uploads_size": 0
    "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members",
      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
    "id": 6,
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
    "default_branch": "master",
    "visibility": "private",
    "ssh_url_to_repo": "[email protected]:brightbox/puppet.git",
    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
    "web_url": "http://example.com/brightbox/puppet",
    "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md",
    "tag_list": [ //deprecated, use `topics` instead
      "example",
      "puppet"
    "topics": [
      "example",
      "puppet"
    "owner": {
      "id": 4,
      "name": "Brightbox",
      "created_at": "2013-09-30T13:46:02Z"
    "name": "Puppet",
    "name_with_namespace": "Brightbox / Puppet",
    "path": "puppet",
    "path_with_namespace": "brightbox/puppet",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
    "can_create_merge_request_in": true,
    "resolve_outdated_diff_discussions": false,
    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
    "container_registry_access_level": "disabled",
    "security_and_compliance_access_level": "disabled",
    "created_at": "2013-09-30T13:46:02Z",
    "updated_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "namespace": {
      "id": 4,
      "name": "Brightbox",
      "path": "brightbox",
      "kind": "group",
      "full_path": "brightbox"
    "import_status": "none",
    "import_error": null,
    "permissions": {
      "project_access": {
        "access_level": 10,
        "notification_level": 3
      "group_access": {
        "access_level": 50,
        "notification_level": 3
    "archived": false,
    "avatar_url": null,
    "shared_runners_enabled": true,
    "group_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds"




    
: false,
    "allow_merge_on_skipped_pipeline": false,
    "restrict_user_defined_variables": false,
    "only_allow_merge_if_all_discussions_are_resolved": false,
    "remove_source_branch_after_merge": false,
    "request_access_enabled": false,
    "merge_method": "merge",
    "squash_option": "default_on",
    "auto_devops_enabled": true,
    "auto_devops_deploy_strategy": "continuous",
    "repository_storage": "default",
    "approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
    "mirror": false,
    "mirror_user_id": 45,
    "mirror_trigger_builds": false,
    "only_mirror_protected_branches": false,
    "mirror_overwrites_diverged_branches": false,
    "external_authorization_classification_label": null,
    "packages_enabled": true,
    "service_desk_enabled": false,
    "service_desk_address": null,
    "autoclose_referenced_issues": true,
    "enforce_auth_checks_on_uploads": true,
    "suggestion_commit_message": null,
    "merge_commit_template": null,
    "squash_commit_template": null,
    "issue_branch_template": "gitlab/%{id}-%{title}",
    "statistics": {
      "commit_count": 12,
      "storage_size": 2066080,
      "repository_size": 2066080,
      "lfs_objects_size": 0,
      "job_artifacts_size": 0,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 0,
      "uploads_size": 0
    "container_registry_image_prefix": "registry.example.com/brightbox/puppet",
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members",
      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
Get single project
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.

Get a specific project. This endpoint can be accessed without authentication if the project is publicly accessible.

GET /projects/:id
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
licenseboolean NoInclude project license data.
statisticsboolean NoInclude project statistics. Available only to users with at least the Reporter role.
with_custom_attributesboolean NoInclude custom attributes in response. (administrators only)
  "id": 3,
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
  "default_branch": "master",
  "visibility": "private",
  "ssh_url_to_repo": "[email protected]:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
  "tag_list": [ //deprecated, use `topics` instead
    "example",
    "disapora project"
  "topics": [
    "example",
    "disapora project"
  "owner": {
    "id": 3,
    "name": "Diaspora",
    "created_at": "2013-09-30T13:46:02Z"
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
  "jobs_enabled": true,
  "wiki_enabled": true,
  "snippets_enabled": false,
  "can_create_merge_request_in": true,
  "resolve_outdated_diff_discussions": false,
  "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
  "container_registry_access_level": "disabled",
  "security_and_compliance_access_level": "disabled",
  "container_expiration_policy": {
    "cadence": "7d",
    "enabled": false,
    "keep_n": null,
    "older_than": null,
    "name_regex": null, // to be deprecated in GitLab 13.0 in favor of `name_regex_delete`
    "name_regex_delete":




    
 null,
    "name_regex_keep": null,
    "next_run_at": "2020-01-07T21:42:58.658Z"
  "created_at": "2013-09-30T13:46:02Z",
  "updated_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
    "kind": "group",
    "full_path": "diaspora",
    "avatar_url": "http://localhost:3000/uploads/group/avatar/3/foo.jpg",
    "web_url": "http://localhost:3000/groups/diaspora"
  "import_url": null,
  "import_type": null,
  "import_status": "none",
  "import_error": null,
  "permissions": {
    "project_access": {
      "access_level": 10,
      "notification_level": 3
    "group_access": {
      "access_level": 50,
      "notification_level": 3
  "archived": false,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  "shared_runners_enabled": true,
  "group_runners_enabled": true,
  "forks_count": 0,
  "star_count": 0,
  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
  "ci_default_git_depth": 50,
  "ci_forward_deployment_enabled": true,
  "ci_allow_fork_pipelines_to_run_in_parent_project": true,
  "ci_separated_caches": true,
  "public_jobs": true,
  "shared_with_groups": [
      "group_id": 4,
      "group_name": "Twitter",
      "group_full_path": "twitter",
      "group_access_level": 30
      "group_id": 3,
      "group_name": "Gitlab Org",
      "group_full_path": "gitlab-org",
      "group_access_level": 10
  "repository_storage": "default",
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "restrict_user_defined_variables": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "remove_source_branch_after_merge": false,
  "printing_merge_requests_link_enabled": true,
  "request_access_enabled": false,
  "merge_method": "merge",
  "squash_option": "default_on",
  "auto_devops_enabled": true,
  "auto_devops_deploy_strategy": "continuous",
  "approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
  "mirror": false,
  "mirror_user_id": 45,
  "mirror_trigger_builds": false,
  "only_mirror_protected_branches": false,
  "mirror_overwrites_diverged_branches": false,
  "external_authorization_classification_label": null,
  "packages_enabled": true,
  "service_desk_enabled": false,
  "service_desk_address": null,
  "autoclose_referenced_issues": true,
  "suggestion_commit_message": null,
  "enforce_auth_checks_on_uploads": true,
  "merge_commit_template": null,
  "squash_commit_template": null,
  "issue_branch_template": "gitlab/%{id}-%{title}",
  "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on
  "marked_for_deletion_on": "2020-04-03",
  "compliance_frameworks": [ "sox" ],
  "statistics": {
    "commit_count": 37,
    "storage_size": 1038090,
    "repository_size": 1038090,
    "wiki_size" : 0,
    "lfs_objects_size": 0,
    "job_artifacts_size": 0,
    "pipeline_artifacts_size": 0,
    "packages_size": 0,
    "snippets_size": 0,
    "uploads_size": 0
  "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels"




    
,
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members",
    "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"

Users of GitLab Ultimate can also see the only_allow_merge_if_all_status_checks_passed parameters using GitLab 15.5 and later:

{
  "id": 1,
  "project_id": 3,
  "only_allow_merge_if_all_status_checks_passed": false,

If the project is a fork, the forked_from_project field appears in the response. For this field, if the upstream project is private, a valid token for authentication must be provided. The field mr_default_target_self appears as well. If this value is false , then all merge requests target the upstream project by default.

{
   "id":3,
   "mr_default_target_self": false,
   "forked_from_project":{
      "id":13083,
      "description":"GitLab Community Edition",
      "name":"GitLab Community Edition",
      "name_with_namespace":"GitLab.org / GitLab Community Edition",
      "path":"gitlab-foss",
      "path_with_namespace":"gitlab-org/gitlab-foss",
      "created_at":"2013-09-26T06:02:36.000Z",
      "default_branch":"master",
      "tag_list":[], //deprecated, use `topics` instead
      "topics":[],
      "ssh_url_to_repo":"[email protected]:gitlab-org/gitlab-foss.git",
      "http_url_to_repo":"https://gitlab.com/gitlab-org/gitlab-foss.git",
      "web_url":"https://gitlab.com/gitlab-org/gitlab-foss",
      "avatar_url":"https://gitlab.com/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png",
      "license_url": "https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE",
      "license": {
        "key": "mit",
        "name": "MIT License",
        "nickname": null,
        "html_url": "http://choosealicense.com/licenses/mit/",
        "source_url": "https://opensource.org/licenses/MIT"
      "star_count":3812,
      "forks_count":3561,
      "last_activity_at":"2018-01-02T11:40:26.570Z",
      "namespace": {
            "id": 72,
            "name": "GitLab.org",
            "path": "gitlab-org",
            "kind": "group",
            "full_path": "gitlab-org",
            "parent_id": null

Templates for issues and merge requests

Introduced in GitLab 13.10.

Users of GitLab Premium or Ultimate can also see the issues_template and merge_requests_template parameters for managing issue and merge request description templates .

{
  "id": 3,
  "issues_template": null,
  "merge_requests_template": null,

Get project users

Get the users list of a project.

GET /projects/:id/users
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
searchstring NoSearch for specific users.
skip_usersinteger array NoFilter out users with the specified IDs.
[
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
    "web_url": "http://localhost:3000/john_smith"
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
    "web_url": "http://localhost:3000/jack_smith"
List a project’s groups
Get a list of ancestor groups for this project.
GET /projects/:id/groups
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
searchstring NoSearch for specific groups.
shared_min_access_levelinteger NoLimit to shared groups with at least this role (access_level).
shared_visible_onlyboolean NoLimit to shared groups user has access to.
skip_groupsarray of integers NoSkip the group IDs passed.
with_sharedboolean NoInclude projects shared with this group. Default is false.
[
    "id": 1,
    "name": "Foobar Group",
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "full_name": "Foobar Group",
    "full_path": "foo-bar"
    "id": 2,
    "name": "Shared Group",
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar",
    "full_name": "Shared Group",
    "full_path": "foo/shared"
List a project’s shareable groups
Get a list of groups that can be shared with a project
GET /projects/:id/share_locations
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
searchstring NoSearch for specific groups.
[




    

    "id": 22,
    "web_url": "http://127.0.0.1:3000/groups/gitlab-org",
    "name": "Gitlab Org",
    "avatar_url": null,
    "full_name": "Gitlab Org",
    "full_path": "gitlab-org"
    "id": 25,
    "web_url": "http://127.0.0.1:3000/groups/gnuwget",
    "name": "Gnuwget",
    "avatar_url": null,
    "full_name": "Gnuwget",
    "full_path": "gnuwget"
Get project events
Refer to the Events API documentation.
Create project
operations_access_level removed in GitLab 16.0.
Creates a new project owned by the authenticated user.
If your HTTP repository isn’t publicly accessible, add authentication information
to the URL https://username:[email protected]/group/project.git,
where password is a public access key with the api scope enabled.
POST /projects
Example request:
curl --request POST --header "PRIVATE-TOKEN: <your-token>" \
     --header "Content-Type: application/json" --data '{
        "name": "new_project", "description": "New Project", "path": "new_project",
        "namespace_id": "42", "initialize_with_readme": "true"}' \
     --url 'https://gitlab.example.com/api/v4/projects/'
AttributeTypeRequiredDescription
namestring Yes (if path isn’t provided)The name of the new project. Equals path if not provided.
pathstring Yes (if name isn’t provided)Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). Starting with GitLab 14.9, path must not start or end with a special character and must not contain consecutive special characters.
allow_merge_on_skipped_pipelineboolean NoSet whether or not merge requests can be merged with skipped jobs.
only_allow_merge_if_all_status_checks_passed 
boolean NoIndicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. Introduced in GitLab 15.5 with feature flag only_allow_merge_if_all_status_checks_passed disabled by default.
analytics_access_levelstring NoOne of disabled, private or enabled
approvals_before_merge 
integer NoHow many approvers should approve merge requests by default. To configure approval rules, see Merge request approvals API. Deprecated in GitLab 16.0.
auto_cancel_pending_pipelinesstring NoAuto-cancel pending pipelines. This action toggles between an enabled state and a disabled state; it is not a boolean.
auto_devops_deploy_strategystring NoAuto Deploy strategy (continuous, manual or timed_incremental).
auto_devops_enabledboolean NoEnable Auto DevOps for this project.
autoclose_referenced_issuesboolean NoSet whether auto-closing referenced issues on default branch.
avatarmixed NoImage file for avatar of the project.
build_git_strategystring NoThe Git strategy. Defaults to fetch.
build_timeoutinteger NoThe maximum amount of time, in seconds, that a job can run.
builds_access_levelstring NoOne of disabled, private, or enabled.
ci_config_pathstring NoThe path to CI configuration file.
container_expiration_policy_attributeshash NoUpdate the image cleanup policy for this project. Accepts: cadence (string), keep_n (integer), older_than (string), name_regex (string), name_regex_delete (string), name_regex_keep (string), enabled (boolean). See the Container Registry documentation for more information on cadence, keep_n and older_than values.
container_registry_access_levelstring NoSet visibility of container registry, for this project, to one of disabled, private or enabled.
container_registry_enabledboolean No
(Deprecated) Enable container registry for this project. Use container_registry_access_level instead.
default_branchstring NoThe default branch name. Requires initialize_with_readme to be true.
descriptionstring NoShort project description.
emails_disabledboolean NoDisable email notifications.
external_authorization_classification_label 
string NoThe classification label for the project.
forking_access_levelstring NoOne of disabled, private, or enabled.
group_with_project_templates_id 
integer NoFor group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires use_custom_template to be true.
import_urlstring NoURL to import repository from. When the URL value isn’t empty, you must not set initialize_with_readme to true. Doing so might result in the following error: not a git repository.
initialize_with_readmeboolean NoWhether to create a Git repository with just a README.md file. Default is false. When this boolean is true, you must not pass import_url or other attributes of this endpoint which specify alternative contents for the repository. Doing so might result in the following error: not a git repository.
issues_access_levelstring NoOne of disabled, private, or enabled.
issues_enabledboolean No
(Deprecated) Enable issues for this project. Use issues_access_level instead.
jobs_enabledboolean No
(Deprecated) Enable jobs for this project. Use builds_access_level instead.
lfs_enabledboolean NoEnable LFS.
merge_methodstring NoSet the merge method used.
merge_pipelines_enabledboolean NoEnable or disable merge pipelines.
merge_requests_access_levelstring NoOne of disabled, private, or enabled.
merge_requests_enabledboolean No
(Deprecated) Enable merge requests for this project. Use merge_requests_access_level instead.
merge_trains_enabledboolean NoEnable or disable merge trains.
mirror_trigger_builds 
boolean NoPull mirroring triggers builds.
mirror 
boolean NoEnables pull mirroring in a project.
namespace_idinteger NoNamespace for the new project (defaults to the current user’s namespace).
only_allow_merge_if_all_discussions_are_resolvedboolean NoSet whether merge requests can only be merged when all the discussions are resolved.
only_allow_merge_if_pipeline_succeedsboolean NoSet whether merge requests can only be merged with successful pipelines. This setting is named Pipelines must succeed in the project settings.
packages_enabledboolean NoEnable or disable packages repository feature.
pages_access_levelstring NoOne of disabled, private, enabled, or public.
printing_merge_request_link_enabledboolean NoShow link to create/view merge request when pushing from the command line.
public_buildsboolean NoIf true, jobs can be viewed by non-project members.
releases_access_levelstring NoOne of disabled, private, or enabled.
environments_access_levelstring NoOne of disabled, private, or enabled.
feature_flags_access_levelstring NoOne of disabled, private, or enabled.
infrastructure_access_levelstring NoOne of disabled, private, or enabled.
monitor_access_levelstring NoOne of disabled, private, or enabled.
remove_source_branch_after_mergeboolean NoEnable Delete source branch option by default for all new merge requests.
repository_access_levelstring NoOne of disabled, private, or enabled.
repository_storagestring NoWhich storage shard the repository is on. (administrator only)
request_access_enabledboolean NoAllow users to request member access.
requirements_access_levelstring NoOne of disabled, private or enabled
resolve_outdated_diff_discussionsboolean NoAutomatically resolve merge request diffs discussions on lines changed with a push.
security_and_compliance_access_levelstring No(GitLab 14.9 and later) Security and compliance access level. One of disabled, private, or enabled.
shared_runners_enabledboolean NoEnable shared runners for this project.
group_runners_enabledboolean NoEnable group runners for this project.
snippets_access_levelstring NoOne of disabled, private, or enabled.
snippets_enabledboolean No
(Deprecated) Enable snippets for this project. Use snippets_access_level instead.
squash_optionstring NoOne of never, always, default_on, or default_off.
tag_listarray No
(Deprecated in GitLab 14.0) The list of tags for a project; put array of tags, that should be finally assigned to a project. Use topics instead.
template_namestring NoWhen used without use_custom_template, name of a built-in project template. When used with use_custom_template, name of a custom project template.
template_project_id 
integer NoWhen used with use_custom_template, project ID of a custom project template. Using a project ID is preferable to using template_name since template_name may be ambiguous.
topicsarray NoThe list of topics for a project; put array of topics, that should be finally assigned to a project. (Introduced in GitLab 14.0.)
use_custom_template 
boolean NoUse either custom instance or group (with group_with_project_templates_id) project template.
visibilitystring NoSee project visibility level.
wiki_access_levelstring NoOne of disabled, private, or enabled.
wiki_enabledboolean No
(Deprecated) Enable wiki for this project. Use wiki_access_level instead.
Create project for user
operations_access_level removed in GitLab 16.0.




    
Creates a new project owned by the specified user. Available only for administrators.
If your HTTP repository isn’t publicly accessible, add authentication information
to the URL https://username:[email protected]/group/project.git,
where password is a public access key with the api scope enabled.
POST /projects/user/:user_id
AttributeTypeRequiredDescription
user_idinteger YesThe user ID of the project owner.
namestring YesThe name of the new project.
allow_merge_on_skipped_pipelineboolean NoSet whether or not merge requests can be merged with skipped jobs.
only_allow_merge_if_all_status_checks_passed 
boolean NoIndicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. Introduced in GitLab 15.5 with feature flag only_allow_merge_if_all_status_checks_passed disabled by default.
analytics_access_levelstring NoOne of disabled, private or enabled
approvals_before_merge 
integer NoHow many approvers should approve merge requests by default. Deprecated in GitLab 16.0. To configure approval rules, see Merge request approvals API.
auto_cancel_pending_pipelinesstring NoAuto-cancel pending pipelines. This action toggles between an enabled state and a disabled state; it is not a boolean.
auto_devops_deploy_strategystring NoAuto Deploy strategy (continuous, manual or timed_incremental).
auto_devops_enabledboolean NoEnable Auto DevOps for this project.
autoclose_referenced_issuesboolean NoSet whether auto-closing referenced issues on default branch.
avatarmixed NoImage file for avatar of the project.
build_git_strategystring NoThe Git strategy. Defaults to fetch.
build_timeoutinteger NoThe maximum amount of time, in seconds, that a job can run.
builds_access_levelstring NoOne of disabled, private, or enabled.
ci_config_pathstring NoThe path to CI configuration file.
container_registry_access_levelstring NoSet visibility of container registry, for this project, to one of disabled, private or enabled.
container_registry_enabledboolean No
(Deprecated) Enable container registry for this project. Use container_registry_access_level instead.
default_branchstring NoThe default branch name. Requires initialize_with_readme to be true.
descriptionstring NoShort project description.
emails_disabledboolean NoDisable email notifications.
enforce_auth_checks_on_uploadsboolean NoEnforce auth checks on uploads.
external_authorization_classification_label 
string NoThe classification label for the project.
forking_access_levelstring NoOne of disabled, private, or enabled.
group_with_project_templates_id 
integer NoFor group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires use_custom_template to be true.
import_urlstring NoURL to import repository from.
initialize_with_readmeboolean No
false by default.
issues_access_levelstring NoOne of disabled, private, or enabled.
issues_enabledboolean No
(Deprecated) Enable issues for this project. Use issues_access_level instead.
jobs_enabledboolean No
(Deprecated) Enable jobs for this project. Use builds_access_level instead.
lfs_enabledboolean NoEnable LFS.
merge_commit_templatestring No
Template used to create merge commit message in merge requests. (Introduced in GitLab 14.5.)
merge_methodstring NoSet the merge method used.
merge_requests_access_levelstring NoOne of disabled, private, or enabled.
merge_requests_enabledboolean No
(Deprecated) Enable merge requests for this project. Use merge_requests_access_level instead.
mirror_trigger_builds 
boolean NoPull mirroring triggers builds.
mirror 
boolean NoEnables pull mirroring in a project.
namespace_idinteger NoNamespace for the new project (defaults to the current user’s namespace).
only_allow_merge_if_all_discussions_are_resolvedboolean NoSet whether merge requests can only be merged when all the discussions are resolved.
only_allow_merge_if_pipeline_succeedsboolean NoSet whether merge requests can only be merged with successful jobs.
packages_enabledboolean NoEnable or disable packages repository feature.
pages_access_levelstring NoOne of disabled, private, enabled, or public.
pathstring NoCustom repository name for new project. By default generated based on name.
printing_merge_request_link_enabledboolean NoShow link to create/view merge request when pushing from the command line.
public_buildsboolean NoIf true, jobs can be viewed by non-project-members.
releases_access_levelstring NoOne of disabled, private, or enabled.
environments_access_levelstring NoOne of disabled, private, or enabled.
feature_flags_access_levelstring NoOne of disabled, private, or enabled.
infrastructure_access_levelstring NoOne of disabled, private, or enabled.
monitor_access_levelstring NoOne of disabled, private, or enabled.
remove_source_branch_after_mergeboolean NoEnable Delete source branch option by default for all new merge requests.
repository_access_levelstring NoOne of disabled, private, or enabled.
repository_storagestring NoWhich storage shard the repository is on. (administrators only)
request_access_enabledboolean NoAllow users to request member access.
requirements_access_levelstring NoOne of disabled, private, enabled or public
resolve_outdated_diff_discussionsboolean NoAutomatically resolve merge request diffs discussions on lines changed with a push.
security_and_compliance_access_levelstring No(GitLab 14.9 and later) Security and compliance access level. One of disabled, private, or enabled.
shared_runners_enabledboolean NoEnable shared runners for this project.
group_runners_enabledboolean NoEnable group runners for this project.
snippets_access_levelstring NoOne of disabled, private, or enabled.
snippets_enabledboolean No
(Deprecated) Enable snippets for this project. Use snippets_access_level instead.
issue_branch_templatestring NoTemplate used to suggest names for branches created from issues. (Introduced in GitLab 15.6.)
squash_commit_templatestring No
Template used to create squash commit message in merge requests. (Introduced in GitLab 14.6.)
squash_optionstring NoOne of never, always, default_on, or default_off.
suggestion_commit_messagestring NoThe commit message used to apply merge request suggestions.
tag_listarray No
(Deprecated in GitLab 14.0) The list of tags for a project; put array of tags, that should be finally assigned to a project. Use topics instead.
template_namestring NoWhen used without use_custom_template, name of a built-in project template. When used with use_custom_template, name of a custom project template.
topicsarray NoThe list of topics for the project. (Introduced in GitLab 14.0.)
use_custom_template 
boolean NoUse either custom instance or group (with group_with_project_templates_id) project template.
visibilitystring NoSee project visibility level.
wiki_access_levelstring NoOne of disabled, private, or enabled.
wiki_enabledboolean No
(Deprecated) Enable wiki for this project. Use wiki_access_level instead.
Edit project
operations_access_level removed in GitLab 16.0.




    
Updates an existing project.
If your HTTP repository isn’t publicly accessible, add authentication information
to the URL https://username:[email protected]/group/project.git,
where password is a public access key with the api scope enabled.
PUT /projects/:id
For example, to toggle the setting for
shared runners on a GitLab.com project:
curl --request PUT --header "PRIVATE-TOKEN: <your-token>" \
     --url 'https://gitlab.com/api/v4/projects/<your-project-ID>' \
     --data "shared_runners_enabled=true" # to turn off: "shared_runners_enabled=false"
Supported attributes:
allow_pipeline_trigger_approve_deployment 
only_allow_merge_if_all_status_checks_passed 
external_authorization_classification_label 
issues_template 
merge_requests_template 
mirror_overwrites_diverged_branches 
mirror_trigger_builds 
mirror_user_id 
only_mirror_protected_branches 

Attribute
Type
Required
Description

id
integer or string
 Yes
The ID or URL-encoded path of the project.

allow_merge_on_skipped_pipeline
boolean
 No
Set whether or not merge requests can be merged with skipped jobs.

boolean
 No
Set whether or not a pipeline triggerer is allowed to approve deployments.

boolean
 No
Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false.

Introduced in GitLab 15.5 with feature flag only_allow_merge_if_all_status_checks_passed disabled by default. The feature flag was enabled by default in GitLab 15.9.

analytics_access_level
string
 No
One of disabled, private or enabled
approvals_before_merge 
integer
 No
How many approvers should approve merge requests by default. Deprecated in GitLab 16.0. To configure approval rules, see Merge request approvals API.

auto_cancel_pending_pipelines
string
 No
Auto-cancel pending pipelines. This action toggles between an enabled state and a disabled state; it is not a boolean.

auto_devops_deploy_strategy
string
 No
Auto Deploy strategy (continuous, manual, or timed_incremental).

auto_devops_enabled
boolean
 No
Enable Auto DevOps for this project.

autoclose_referenced_issues
boolean
 No
Set whether auto-closing referenced issues on default branch.

avatar
mixed
 No
Image file for avatar of the project.

build_git_strategy
string
 No
The Git strategy. Defaults to fetch.

build_timeout
integer
 No
The maximum amount of time, in seconds, that a job can run.

builds_access_level
string
 No
One of disabled, private, or enabled.

ci_config_path
string
 No
The path to CI configuration file.

ci_default_git_depth
integer
 No
Default number of revisions for shallow cloning.

ci_forward_deployment_enabled
boolean
 No
Enable or disable prevent outdated deployment jobs.

ci_allow_fork_pipelines_to_run_in_parent_project
boolean
 No
Enable or disable running pipelines in the parent project for merge requests from forks. (Introduced in GitLab 15.3.)
ci_separated_caches
boolean
 No
Set whether or not caches should be separated by branch protection status.

container_expiration_policy_attributes
hash
 No
Update the image cleanup policy for this project. Accepts: cadence (string), keep_n (integer), older_than (string), name_regex (string), name_regex_delete (string), name_regex_keep (string), enabled (boolean).

container_registry_access_level
string
 No
Set visibility of container registry, for this project, to one of disabled, private or enabled.

container_registry_enabled
boolean
 No

(Deprecated) Enable container registry for this project. Use container_registry_access_level instead.

default_branch
string
 No
The default branch name.

description
string
 No
Short project description.

emails_disabled
boolean
 No
Disable email notifications.

enforce_auth_checks_on_uploads
boolean
 No
Enforce auth checks on uploads.

string
 No
The classification label for the project.

forking_access_level
string
 No
One of disabled, private, or enabled.

import_url
string
 No
URL the repository was imported from.

issues_access_level
string
 No
One of disabled, private, or enabled.

issues_enabled
boolean
 No

(Deprecated) Enable issues for this project. Use issues_access_level instead.

string
 No
Default description for Issues. Description is parsed with GitLab Flavored Markdown. See Templates for issues and merge requests.

jobs_enabled
boolean
 No

(Deprecated) Enable jobs for this project. Use builds_access_level instead.

keep_latest_artifact
boolean
 No
Disable or enable the ability to keep the latest artifact for this project.

lfs_enabled
boolean
 No
Enable LFS.

merge_commit_template
string
 No

Template used to create merge commit message in merge requests. (Introduced in GitLab 14.5.)
merge_method
string
 No
Set the merge method used.

merge_pipelines_enabled
boolean
 No
Enable or disable merge pipelines.

merge_requests_access_level
string
 No
One of disabled, private, or enabled.

merge_requests_enabled
boolean
 No

(Deprecated) Enable merge requests for this project. Use merge_requests_access_level instead.

string
 No
Default description for merge requests. Description is parsed with GitLab Flavored Markdown. See Templates for issues and merge requests.

merge_trains_enabled
boolean
 No
Enable or disable merge trains.

boolean
 No
Pull mirror overwrites diverged branches.

boolean
 No
Pull mirroring triggers builds.

integer
 No
User responsible for all the activity surrounding a pull mirror event. (administrators only)
mirror 





    
boolean
 No
Enables pull mirroring in a project.

mr_default_target_self
boolean
 No
For forked projects, target merge requests to this project. If false, the target is the upstream project.

name
string
 No
The name of the project.

only_allow_merge_if_all_discussions_are_resolved
boolean
 No
Set whether merge requests can only be merged when all the discussions are resolved.

only_allow_merge_if_pipeline_succeeds
boolean
 No
Set whether merge requests can only be merged with successful jobs.

boolean
 No
Only mirror protected branches.

packages_enabled
boolean
 No
Enable or disable packages repository feature.

pages_access_level
string
 No
One of disabled, private, enabled, or public.

path
string
 No
Custom repository name for the project. By default generated based on name.

printing_merge_request_link_enabled
boolean
 No
Show link to create/view merge request when pushing from the command line.

public_builds
boolean
 No
If true, jobs can be viewed by non-project members.

releases_access_level
string
 No
One of disabled, private, or enabled.

environments_access_level
string
 No
One of disabled, private, or enabled.

feature_flags_access_level
string
 No
One of disabled, private, or enabled.

infrastructure_access_level
string
 No
One of disabled, private, or enabled.

monitor_access_level
string
 No
One of disabled, private, or enabled.

remove_source_branch_after_merge
boolean
 No
Enable Delete source branch option by default for all new merge requests.

repository_access_level
string
 No
One of disabled, private, or enabled.

repository_storage
string
 No
Which storage shard the repository is on. (administrators only)
request_access_enabled
boolean
 No
Allow users to request member access.

requirements_access_level
string
 No
One of disabled, private, enabled or public
resolve_outdated_diff_discussions
boolean
 No
Automatically resolve merge request diffs discussions on lines changed with a push.

restrict_user_defined_variables
boolean
 No
Allow only users with the Maintainer role to pass user-defined variables when triggering a pipeline. For example when the pipeline is triggered in the UI, with the API, or by a trigger token.

security_and_compliance_access_level
string
 No
(GitLab 14.9 and later) Security and compliance access level. One of disabled, private, or enabled.

service_desk_enabled
boolean
 No
Enable or disable Service Desk feature.

shared_runners_enabled
boolean
 No
Enable shared runners for this project.

group_runners_enabled
boolean
 No
Enable group runners for this project.

snippets_access_level
string
 No
One of disabled, private, or enabled.

snippets_enabled
boolean
 No

(Deprecated) Enable snippets for this project. Use snippets_access_level instead.

issue_branch_template
string
 No
Template used to suggest names for branches created from issues. (Introduced in GitLab 15.6.)
squash_commit_template
string
 No

Template used to create squash commit message in merge requests. (Introduced in GitLab 14.6.)
squash_option
string
 No
One of never, always, default_on, or default_off.

suggestion_commit_message
string
 No
The commit message used to apply merge request suggestions.

tag_list
array
 No

(Deprecated in GitLab 14.0) The list of tags for a project; put array of tags, that should be finally assigned to a project. Use topics instead.

topics
array
 No
The list of topics for the project. This replaces any existing topics that are already added to the project. (Introduced in GitLab 14.0.)
visibility
string
 No
See project visibility level.

wiki_access_level
string
 No
One of disabled, private, or enabled.

wiki_enabled
boolean
 No

(Deprecated) Enable wiki for this project. Use wiki_access_level instead.
Fork project
Forks a project into the user namespace of the authenticated user or the one provided.




    
The forking operation for a project is asynchronous and is completed in a
background job. The request returns immediately. To determine whether the
fork of the project has completed, query the import_status for the new project.
POST /projects/:id/fork
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
descriptionstring NoThe description assigned to the resultant project after forking.
mr_default_target_selfboolean NoFor forked projects, target merge requests to this project. If false, the target is the upstream project.
namestring NoThe name assigned to the resultant project after forking.
namespace_idinteger NoThe ID of the namespace that the project is forked to.
namespace_pathstring NoThe path of the namespace that the project is forked to.
namespaceinteger or string No
(Deprecated) The ID or path of the namespace that the project is forked to.
pathstring NoThe path assigned to the resultant project after forking.
visibilitystring NoThe visibility level assigned to the resultant project after forking.
List forks of a project
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.
List the projects accessible to the calling user that have an established,
forked relationship with the specified project
GET /projects/:id/forks
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
archivedboolean NoLimit by archived status.
membershipboolean NoLimit by projects that the current user is a member of.
min_access_levelinteger NoLimit by current user minimal role (access_level).
order_bystring NoReturn projects ordered by id, name, path, created_at, updated_at, or last_activity_at fields. Default is created_at.
ownedboolean NoLimit by projects explicitly owned by the current user.
searchstring NoReturn list of projects matching the search criteria.
simpleboolean NoReturn only limited fields for each project. Without authentication, this operation is a no-op; only simple fields are returned.
sortstring NoReturn projects sorted in asc or desc order. Default is desc.
starredboolean NoLimit by projects starred by the current user.
statisticsboolean NoInclude project statistics. Available only to users with at least the Reporter role.
visibilitystring NoLimit by visibility public, internal, or private.
with_custom_attributesboolean NoInclude custom attributes in response. (administrators only)
with_issues_enabledboolean NoLimit by enabled issues feature.
with_merge_requests_enabledboolean NoLimit by enabled merge requests feature.
updated_beforedatetime NoLimit results to projects last updated before the specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Introduced in GitLab 15.10.
updated_afterdatetime NoLimit results to projects last updated after the specified time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Introduced in GitLab 15.10.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/forks"
Example responses:
[
    "id": 3,
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
    "default_branch": "master",
    "visibility": "internal",
    "ssh_url_to_repo": "[email protected]:diaspora/diaspora-project-site.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
    "web_url": "http://example.com/diaspora/diaspora-project-site",
    "readme_url": 




    
"http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
    "tag_list": [ //deprecated, use `topics` instead
      "example",
      "disapora project"
    "topics": [
      "example",
      "disapora project"
    "name": "Diaspora Project Site",
    "name_with_namespace": "Diaspora / Diaspora Project Site",
    "path": "diaspora-project-site",
    "path_with_namespace": "diaspora/diaspora-project-site",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
    "can_create_merge_request_in": true,
    "resolve_outdated_diff_discussions": false,
    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
    "container_registry_access_level": "disabled",
    "security_and_compliance_access_level": "disabled",
    "created_at": "2013-09-30T13:46:02Z",
    "updated_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "namespace": {
      "id": 3,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora"
    "import_status": "none",
    "archived": true,
    "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
    "shared_runners_enabled": true,
    "group_runners_enabled": true,
    "forks_count": 0,
    "star_count": 1,
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
    "allow_merge_on_skipped_pipeline": false,
    "restrict_user_defined_variables": false,
    "only_allow_merge_if_all_discussions_are_resolved": false,
    "remove_source_branch_after_merge": false,
    "request_access_enabled": false,
    "merge_method": "merge",
    "squash_option": "default_on",
    "autoclose_referenced_issues": true,
    "enforce_auth_checks_on_uploads": true,
    "suggestion_commit_message": null,
    "merge_commit_template": null,
    "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members",
      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
Star a project
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.
Stars a given project. Returns status code 304 if the project is already
starred.
POST /projects/:id/star
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star"
Example response:
{
  "id": 3,
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
  "default_branch": "master",
  "visibility": "internal",
  "ssh_url_to_repo": "[email protected]:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
  "tag_list": [ //deprecated, use `topics` instead
    "example",
    "disapora project"
  "topics": [
    "example",
    "disapora project"
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
  "jobs_enabled": true,
  "wiki_enabled": true,
  "snippets_enabled": false,
  "can_create_merge_request_in": true,
  "resolve_outdated_diff_discussions": false,
  "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
  "container_registry_access_level": "disabled",
  "security_and_compliance_access_level": "disabled",
  




    
"created_at": "2013-09-30T13:46:02Z",
  "updated_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
    "kind": "group",
    "full_path": "diaspora"
  "import_status": "none",
  "archived": true,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  "shared_runners_enabled": true,
  "group_runners_enabled": true,
  "forks_count": 0,
  "star_count": 1,
  "public_jobs": true,
  "shared_with_groups": [],
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "restrict_user_defined_variables": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "remove_source_branch_after_merge": false,
  "request_access_enabled": false,
  "merge_method": "merge",
  "squash_option": "default_on",
  "autoclose_referenced_issues": true,
  "enforce_auth_checks_on_uploads": true,
  "suggestion_commit_message": null,
  "merge_commit_template": null,
  "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members",
    "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
Unstar a project
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.
Unstars a given project. Returns status code 304 if the project is not starred.
POST /projects/:id/unstar
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar"
Example response:
{
  "id": 3,
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
  "default_branch": "master",
  "visibility": "internal",
  "ssh_url_to_repo": "[email protected]:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
  "tag_list": [ //deprecated, use `topics` instead
    "example",
    "disapora project"
  "topics": [
    "example",
    "disapora project"
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
  "jobs_enabled": true,
  "wiki_enabled": true,
  "snippets_enabled": false,
  "can_create_merge_request_in": true,
  "resolve_outdated_diff_discussions": false,
  "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
  "container_registry_access_level": "disabled",
  "security_and_compliance_access_level": "disabled",
  "created_at": "2013-09-30T13:46:02Z",
  "updated_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
    "kind": "group",
    "full_path": "diaspora"
  "import_status": "none",
  "archived": true,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0"




    
,
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  "shared_runners_enabled": true,
  "group_runners_enabled": true,
  "forks_count": 0,
  "star_count": 0,
  "public_jobs": true,
  "shared_with_groups": [],
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "restrict_user_defined_variables": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "remove_source_branch_after_merge": false,
  "request_access_enabled": false,
  "merge_method": "merge",
  "squash_option": "default_on",
  "autoclose_referenced_issues": true,
  "enforce_auth_checks_on_uploads": true,
  "suggestion_commit_message": null,
  "merge_commit_template": null,
  "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members",
    "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
List starrers of a project
List the users who starred the specified project.
GET /projects/:id/starrers
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
searchstring NoSearch for specific users.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/starrers"
Example responses:
[
    "starred_since": "2019-01-28T14:47:30.642Z",
    "user": {
        "id": 1,
        "username": "jane_smith",
        "name": "Jane Smith",
        "state": "active",
        "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
        "web_url": "http://localhost:3000/jane_smith"
    "starred_since": "2018-01-02T11:40:26.570Z",
    "user": {
      "id": 2,
      "username": "janine_smith",
      "name": "Janine Smith",
      "state": "blocked",
      "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
      "web_url": "http://localhost:3000/janine_smith"
Languages
Get languages used in a project with percentage value.
GET /projects/:id/languages
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages"
Example response:
{
  "Ruby": 66.69,
  "JavaScript": 22.98,
  "HTML": 7.91,
  "CoffeeScript": 2.42
Archive a project
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.
Archives the project if the user is either an administrator or the owner of this
project. This action is idempotent, thus archiving an already archived project
does not change the project.
POST /projects/:id/archive
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive"
Example response:
{
  "id": 3,
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
  "default_branch": "master",
  "visibility": "private",
  "ssh_url_to_repo": "[email protected]:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
  "tag_list": [ //deprecated, use `topics` instead
    "example",
    "disapora project"
  "topics": [
    "example",
    "disapora project"
  "owner": {
    "id": 3,
    "name": "Diaspora",
    "created_at": "2013-09-30T13:46:02Z"
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
  "jobs_enabled": true,
  "wiki_enabled": true,
  "snippets_enabled": false,
  "can_create_merge_request_in": true,
  "resolve_outdated_diff_discussions":




    
 false,
  "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
  "container_registry_access_level": "disabled",
  "security_and_compliance_access_level": "disabled",
  "created_at": "2013-09-30T13:46:02Z",
  "updated_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
    "kind": "group",
    "full_path": "diaspora"
  "import_status": "none",
  "import_error": null,
  "permissions": {
    "project_access": {
      "access_level": 10,
      "notification_level": 3
    "group_access": {
      "access_level": 50,
      "notification_level": 3
  "archived": true,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  "shared_runners_enabled": true,
  "group_runners_enabled": true,
  "forks_count": 0,
  "star_count": 0,
  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
  "ci_default_git_depth": 50,
  "ci_forward_deployment_enabled": true,
  "ci_allow_fork_pipelines_to_run_in_parent_project": true,
  "ci_separated_caches": true,
  "public_jobs": true,
  "shared_with_groups": [],
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "restrict_user_defined_variables": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "remove_source_branch_after_merge": false,
  "request_access_enabled": false,
  "merge_method": "merge",
  "squash_option": "default_on",
  "autoclose_referenced_issues": true,
  "enforce_auth_checks_on_uploads": true,
  "suggestion_commit_message": null,
  "merge_commit_template": null,
  "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members",
    "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
Unarchive a project
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.
Unarchives the project if the user is either an administrator or the owner of
this project. This action is idempotent, thus unarchiving a non-archived project
doesn’t change the project.
POST /projects/:id/unarchive
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive"
Example response:
{
  "id": 3,
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
  "default_branch": "master",
  "visibility": "private",
  "ssh_url_to_repo": "[email protected]:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
  "tag_list": [ //deprecated, use `topics` instead
    "example",
    "disapora project"
  "topics": [
    "example",
    "disapora project"
  "owner": {
    "id": 3,
    "name": "Diaspora",
    "created_at": "2013-09-30T13:46:02Z"
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
  "jobs_enabled": true,
  "wiki_enabled": true,
  "snippets_enabled": false,
  "can_create_merge_request_in": true,
  "resolve_outdated_diff_discussions": false,
  "container_registry_enabled"




    
: false, // deprecated, use container_registry_access_level instead
  "container_registry_access_level": "disabled",
  "security_and_compliance_access_level": "disabled",
  "created_at": "2013-09-30T13:46:02Z",
  "updated_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
    "kind": "group",
    "full_path": "diaspora"
  "import_status": "none",
  "import_error": null,
  "permissions": {
    "project_access": {
      "access_level": 10,
      "notification_level": 3
    "group_access": {
      "access_level": 50,
      "notification_level": 3
  "archived": false,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  "shared_runners_enabled": true,
  "group_runners_enabled": true,
  "forks_count": 0,
  "star_count": 0,
  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
  "ci_default_git_depth": 50,
  "ci_forward_deployment_enabled": true,
  "ci_allow_fork_pipelines_to_run_in_parent_project": true,
  "ci_separated_caches": true,
  "public_jobs": true,
  "shared_with_groups": [],
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "restrict_user_defined_variables": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "remove_source_branch_after_merge": false,
  "request_access_enabled": false,
  "merge_method": "merge",
  "squash_option": "default_on",
  "autoclose_referenced_issues": true,
  "enforce_auth_checks_on_uploads": true,
  "suggestion_commit_message": null,
  "merge_commit_template": null,
  "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members",
    "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
Delete project
The default behavior of Delayed project deletion in GitLab 12.6 was changed to Immediate deletion in GitLab 13.2.
This endpoint:

Deletes a project including all associated resources (including issues and
merge requests).
In GitLab 12.6 and later, on
Premium or Ultimate tiers,
delayed project deletion
is applied if enabled.
From GitLab 15.11 on
Premium or Ultimate tiers, deletes a project immediately if the project is already
marked for deletion, and the permanently_remove and full_path parameters are passed.
From GitLab 16.0 on
Premium or Ultimate tiers, delayed project deletion is enabled by default.
The deletion happens after the number of days specified in the
default deletion delay.

The option to delete projects immediately from deletion protection settings in the Admin Area was deprecated in GitLab 15.9 and removed in GitLab 16.0.
DELETE /projects/:id
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
permanently_remove 
boolean/stringnoImmediately deletes a project if it is marked for deletion. Introduced in GitLab 15.11
full_path 
stringnoFull path of project to use with permanently_remove. Introduced in GitLab 15.11. To find the project path, use path_with_namespace from get single project
Restore project marked for deletion 
Introduced in GitLab 12.6.
Restores project marked for deletion.
POST /projects/:id/restore
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
Upload a file
Version history
Maximum attachment size enforcement introduced in GitLab 13.11 with a flag named enforce_max_attachment_size_upload_api. Disabled by default.
Maximum attachment size enabled on GitLab.com in GitLab 13.11.

Generally available in GitLab 15.10. Feature flag enforce_max_attachment_size_upload_api removed.
Uploads a file to the specified project to be used in an issue or merge request
description, or a comment.
POST /projects/:id/uploads
AttributeTypeRequiredDescription
filestring YesThe file to be uploaded.
idinteger or string YesThe ID or URL-encoded path of the project.
To upload a file from your file system, use the --form argument. This causes
cURL to post data using the header Content-Type: multipart/form-data. The
file= parameter must point to a file on your file system and be preceded by
@. For example:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "[email protected]" "https://gitlab.example.com/api/v4/projects/5/uploads"
Returned object:
{




    

  "alt": "dk",
  "url": "/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png",
  "full_path": "/namespace1/project1/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png",
  "markdown": "![dk](/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png)"
The returned url is relative to the project path. The returned full_path is
the absolute path to the file. In Markdown contexts, the link is expanded when
the format in markdown is used.
Upload a project avatar
Uploads an avatar to the specified project.
PUT /projects/:id
AttributeTypeRequiredDescription
avatarstring YesThe file to be uploaded.
idinteger or string YesThe ID or URL-encoded path of the project.
To upload an avatar from your file system, use the --form argument. This causes
cURL to post data using the header Content-Type: multipart/form-data. The
file= parameter must point to an image file on your file system and be
preceded by @. For example:
Example request:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "[email protected]" "https://gitlab.example.com/api/v4/projects/5"
Returned object:
{
  "avatar_url": "https://gitlab.example.com/uploads/-/system/project/avatar/2/dk.png"
Remove a project avatar
Introduced in GitLab 15.4.
To remove a project avatar, use a blank value for the avatar attribute.
Example request:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "avatar=" "https://gitlab.example.com/api/v4/projects/5"
Share project with group
Allow to share project with group.
POST /projects/:id/share
AttributeTypeRequiredDescription
group_accessinteger YesThe role (access_level) to grant the group.
group_idinteger YesThe ID of the group to share with.
idinteger or string YesThe ID or URL-encoded path of the project.
expires_atstring NoShare expiration date in ISO 8601 format: 2016-09-26
Delete a shared project link within a group
Unshare the project from the group. Returns 204 and no content on success.
DELETE /projects/:id/share/:group_id
AttributeTypeRequiredDescription
group_idinteger YesThe ID of the group.
idinteger or string YesThe ID or URL-encoded path of the project.
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17"
Import project members
Import members from another project.
If the importing member’s role in the target project is:

Maintainer, then members with the Owner role in the source project are imported with the Maintainer role.
Owner, then members with the Owner role in the source project are imported with the Owner role.
POST /projects/:id/import_project_members/:project_id
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the target project to receive the members.
project_idinteger or string YesThe ID or URL-encoded path of the source project to import the members from.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/import_project_members/32"
Returns:

200 OK on success.

404 Project Not Found if the target or source project does not exist or cannot be accessed by the requester.

422 Unprocessable Entity if the import of project members does not complete successfully.
Hooks
Also called Project Hooks and Webhooks. These are different for System Hooks
that are system-wide.
List project hooks
Get a list of project hooks.
GET /projects/:id/hooks
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
Get project hook
Get a specific hook for a project.
GET /projects/:id/hooks/:hook_id
AttributeTypeRequiredDescription
hook_idinteger YesThe ID of a project hook.
idinteger or string YesThe ID or URL-encoded path of the project.
{
  "id": 1,
  "url": "http://example.com/hook",
  "project_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "issues_events": true,
  "confidential_issues_events": true,
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
  "confidential_note_events": true,
  "job_events": true,
  "pipeline_events": true,
  "wiki_page_events": true,
  "deployment_events": true,
  "releases_events": true,
  "enable_ssl_verification": true,
  "repository_update_events": false,
  "alert_status": "executable",
  "disabled_until": null,
  "url_variables": [ ],
  "created_at": "2012-10-12T17:04:47Z"
Add project hook
Adds a hook to a specified project.
POST /projects/:id/hooks
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
urlstring YesThe hook URL.
confidential_issues_eventsboolean NoTrigger hook on confidential issues events.
confidential_note_eventsboolean NoTrigger hook on confidential note events.
deployment_eventsboolean NoTrigger hook on deployment events.
enable_ssl_verificationboolean NoDo SSL verification when triggering the hook.
issues_eventsboolean NoTrigger hook on issues events.
job_eventsboolean NoTrigger hook on job events.
merge_requests_eventsboolean NoTrigger hook on merge requests events.
note_eventsboolean NoTrigger hook on note events.
pipeline_eventsboolean NoTrigger hook on pipeline events.
push_events_branch_filterstring NoTrigger hook on push events for matching branches only.
push_eventsboolean NoTrigger hook on push events.
releases_eventsboolean NoTrigger hook on release events.
tag_push_eventsboolean NoTrigger hook on tag push events.
tokenstring NoSecret token to validate received payloads; the token isn’t returned in the response.
wiki_page_eventsboolean NoTrigger hook on wiki events.
Edit project hook
Edits a hook for a specified project.




    
PUT /projects/:id/hooks/:hook_id
AttributeTypeRequiredDescription
hook_idinteger YesThe ID of the project hook.
idinteger or string YesThe ID or URL-encoded path of the project.
urlstring YesThe hook URL.
confidential_issues_eventsboolean NoTrigger hook on confidential issues events.
confidential_note_eventsboolean NoTrigger hook on confidential note events.
deployment_eventsboolean NoTrigger hook on deployment events.
enable_ssl_verificationboolean NoDo SSL verification when triggering the hook.
issues_eventsboolean NoTrigger hook on issues events.
job_eventsboolean NoTrigger hook on job events.
merge_requests_eventsboolean NoTrigger hook on merge requests events.
note_eventsboolean NoTrigger hook on note events.
pipeline_eventsboolean NoTrigger hook on pipeline events.
push_events_branch_filterstring NoTrigger hook on push events for matching branches only.
push_eventsboolean NoTrigger hook on push events.
releases_eventsboolean NoTrigger hook on release events.
tag_push_eventsboolean NoTrigger hook on tag push events.
tokenstring NoSecret token to validate received payloads. Not returned in the response. When you change the webhook URL, the secret token is reset and not retained.
wiki_page_eventsboolean NoTrigger hook on wiki page events.
Delete project hook
Removes a hook from a project. This method is idempotent, and can be called
multiple times. Either the hook is available or not.
DELETE /projects/:id/hooks/:hook_id
AttributeTypeRequiredDescription
hook_idinteger YesThe ID of the project hook.
idinteger or string YesThe ID or URL-encoded path of the project.
Note the JSON response differs if the hook is available or not. If the project
hook is available before it’s returned in the JSON response or an empty response
is returned.
Fork relationship
Allows modification of the forked relationship between existing projects.
Available only for project owners and administrators.
Create a forked from/to relation between existing projects
POST /projects/:id/fork/:forked_from_id
AttributeTypeRequiredDescription
forked_from_idID YesThe ID of the project that was forked from.
idinteger or string YesThe ID or URL-encoded path of the project.
Delete an existing forked from relationship
DELETE /projects/:id/fork
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
Search for projects by name
Search for projects by name which are accessible to the authenticated user. This
endpoint can be accessed without authentication if the project is publicly
accessible.
GET /projects
AttributeTypeRequiredDescription
searchstring YesA string contained in the project name.
order_bystring NoReturn requests ordered by id, name, created_at or last_activity_at fields.
sortstring NoReturn requests sorted in asc or desc order.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?search=test"
Start the Housekeeping task for a project
POST /projects/:id/housekeeping
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
taskstring No
prune to trigger manual prune of unreachable objects or eager to trigger eager housekeeping.
Push rules 
Get project push rules
Get the push rules of a
project.
GET /projects/:id/push_rule
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project
  "id": 1,
  "project_id": 3,
  "commit_message_regex": "Fixes \\d+\\..*",
  "commit_message_negative_regex": "ssh\\:\\/\\/",
  "branch_name_regex": "",
  "deny_delete_tag": false,
  "created_at": "2012-10-12T17:04:47Z",
  "member_check": false,
  "prevent_secrets": false,
  "author_email_regex": "",
  "file_name_regex": "",
  "max_file_size": 5,
  "commit_committer_check": false,
  "reject_unsigned_commits": false
Add project push rule
Adds a push rule to a specified project.
POST /projects/:id/push_rule
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
author_email_regexstring NoAll commit author emails must match this, for example @my-company.com$.
branch_name_regexstring NoAll branch names must match this, for example (feature|hotfix)\/*.
commit_committer_checkboolean NoUsers can only push commits to this repository if the committer email is one of their own verified emails.
commit_message_negative_regexstring NoNo commit message is allowed to match this, for example ssh\:\/\/.
commit_message_regexstring NoAll commit messages must match this, for example Fixed \d+\..*.
deny_delete_tagboolean NoDeny deleting a tag.
file_name_regexstring NoAll committed filenames must not match this, for example (jar|exe)$.
max_file_sizeinteger NoMaximum file size (MB).
member_checkboolean NoRestrict commits by author (email) to existing GitLab users.
prevent_secretsboolean NoGitLab rejects any files that are likely to contain secrets.
reject_unsigned_commitsboolean NoReject commit when it’s not signed through GPG.
Edit project push rule
Edits a push rule for a specified project.




    
PUT /projects/:id/push_rule
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
author_email_regexstring NoAll commit author emails must match this, for example @my-company.com$.
branch_name_regexstring NoAll branch names must match this, for example (feature|hotfix)\/*.
commit_committer_checkboolean NoUsers can only push commits to this repository if the committer email is one of their own verified emails.
commit_message_negative_regexstring NoNo commit message is allowed to match this, for example ssh\:\/\/.
commit_message_regexstring NoAll commit messages must match this, for example Fixed \d+\..*.
deny_delete_tagboolean NoDeny deleting a tag.
file_name_regexstring NoAll committed filenames must not match this, for example (jar|exe)$.
max_file_sizeinteger NoMaximum file size (MB).
member_checkboolean NoRestrict commits by author (email) to existing GitLab users.
prevent_secretsboolean NoGitLab rejects any files that are likely to contain secrets.
reject_unsigned_commitsboolean NoReject commits when they are not GPG signed.
Delete project push rule
Moved to GitLab Premium in 13.9.
Removes a push rule from a project. This method is idempotent and can be
called multiple times. Either the push rule is available or not.
DELETE /projects/:id/push_rule
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
Get groups to which a user can transfer a project
Introduced in GitLab 15.4
Retrieve a list of groups to which the user can transfer a project.
GET /projects/:id/transfer_locations
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
searchstring NoThe group names to search for.
Example request:
curl --request GET "https://gitlab.example.com/api/v4/projects/1/transfer_locations"
Example response:
[
    "id": 27,
    "web_url": "https://gitlab.example.com/groups/gitlab",
    "name": "GitLab",
    "avatar_url": null,
    "full_name": "GitLab",
    "full_path": "GitLab"
    "id": 31,
    "web_url": "https://gitlab.example.com/groups/foobar",
    "name": "FooBar",
    "avatar_url": null,
    "full_name": "FooBar",
    "full_path": "FooBar"
Transfer a project to a new namespace
The _links.cluster_agents attribute in the response introduced in GitLab 14.10.
See the Project documentation
for prerequisites to transfer a project.
PUT /projects/:id/transfer
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
namespaceinteger or string YesThe ID or path of the namespace to transfer to project to.
Example request:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/transfer?namespace=14"
Example response:
  {
  "id": 7,
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
  "name": "hello-world",
  "name_with_namespace": "cute-cats / hello-world",
  "path": "hello-world",
  "path_with_namespace": "cute-cats/hello-world",
  "created_at": "2020-10-15T16:25:22.415Z",
  "updated_at": "2020-10-15T16:25:22.415Z",
  "default_branch": "master",
  "tag_list": [], //deprecated, use `topics` instead
  "topics": [],
  "ssh_url_to_repo": "[email protected]:cute-cats/hello-world.git",
  "http_url_to_repo": "https://gitlab.example.com/cute-cats/hello-world.git",
  "web_url": "https://gitlab.example.com/cute-cats/hello-world",
  "readme_url": "https://gitlab.example.com/cute-cats/hello-world/-/blob/master/README.md",
  "avatar_url": null,
  "forks_count": 0,
  "star_count": 0,
  "last_activity_at": "2020-10-15T16:25:22.415Z",
  "namespace": {
    "id": 18,
    "name": "cute-cats",
    "path": "cute-cats",
    "kind": "group",
    "full_path": "cute-cats",
    "parent_id": null,
    "avatar_url": null,
    "web_url": "https://gitlab.example.com/groups/cute-cats"
  "container_registry_image_prefix": "registry.example.com/cute-cats/hello-world",
  "_links": {
    "self": "https://gitlab.example.com/api/v4/projects/7",
    "issues": "https://gitlab.example.com/api/v4/projects/7/issues",
    "merge_requests": "https://gitlab.example.com/api/v4/projects/7/merge_requests",
    "repo_branches": "https://gitlab.example.com/api/v4/projects/7/repository/branches",
    "labels": "https://gitlab.example.com/api/v4/projects/7/labels",
    "events": "https://gitlab.example.com/api/v4/projects/7/events",
    "members": "https://gitlab.example.com/api/v4/projects/7/members"
  "packages_enabled": true,
  "empty_repo": false,
  "archived": false,
  "visibility": "private",
  "resolve_outdated_diff_discussions": false,
  "container_registry_enabled": true, // deprecated, use container_registry_access_level instead
  "container_registry_access_level": "enabled",
  "container_expiration_policy"




    
: {
    "cadence": "7d",
    "enabled": false,
    "keep_n": null,
    "older_than": null,
    "name_regex": null,
    "name_regex_keep": null,
    "next_run_at": "2020-10-22T16:25:22.746Z"
  "issues_enabled": true,
  "merge_requests_enabled": true,
  "wiki_enabled": true,
  "jobs_enabled": true,
  "snippets_enabled": true,
  "service_desk_enabled": false,
  "service_desk_address": null,
  "can_create_merge_request_in": true,
  "issues_access_level": "enabled",
  "repository_access_level": "enabled",
  "merge_requests_access_level": "enabled",
  "forking_access_level": "enabled",
  "analytics_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,
  "shared_runners_enabled": true,
  "group_runners_enabled": true,
  "lfs_enabled": true,
  "creator_id": 2,
  "import_status": "none",
  "open_issues_count": 0,
  "ci_default_git_depth": 50,
  "public_jobs": true,
  "build_timeout": 3600,
  "auto_cancel_pending_pipelines": "enabled",
  "ci_config_path": null,
  "shared_with_groups": [],
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": null,
  "restrict_user_defined_variables": 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",
  "squash_option": "default_on",
  "suggestion_commit_message": null,
  "merge_commit_template": null,
  "auto_devops_enabled": true,
  "auto_devops_deploy_strategy": "continuous",
  "autoclose_referenced_issues": true,
  "approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
  "mirror": false,
  "compliance_frameworks": []
Branches
Read more in the Branches documentation.
Project import/export
Read more in the Project import/export documentation.
Project members
Read more in the Project members documentation.
Project vulnerabilities
Read more in the Project vulnerabilities documentation.
Get a project’s pull mirror details 
Introduced in GitLab 15.6.
Returns the details of the project’s pull mirror.
GET /projects/:id/mirror/pull
Supported attributes:

Attribute
Type
Required
Description

id
integer or string
 Yes
The ID or URL-encoded path of the project.
Example request:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"
Example response:
{
  "id": 101486,
  "last_error": null,
  "last_successful_update_at": "2020-01-06T17:32:02.823Z",
  "last_update_at": "2020-01-06T17:32:02.823Z",
  "last_update_started_at": "2020-01-06T17:31:55.864Z",
  "update_status": "finished",
  "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
Configure pull mirroring for a project 
Version history
Moved to GitLab Premium in GitLab 13.9.
Field mirror_branch_regex introduced in GitLab 15.8 with a flag named mirror_only_branches_match_regex. Disabled by default.

Enabled by default in GitLab 16.0.

On self-managed GitLab, by default the field mirror_branch_regex is available.
To hide the feature, ask an administrator to disable the feature flag
named mirror_only_branches_match_regex.
On GitLab.com, this feature is available.
Configure pull mirroring while creating a new project
or updating an existing project using the API
if the remote repository is publicly accessible
or via username:token authentication.
In case your HTTP repository is not publicly accessible,
you can add the authentication information to the URL:
https://username:[email protected]/group/project.git,
where token is a personal access token
with the API scope enabled.

Attribute
Type
Required
Description

import_url
string
 Yes
URL of remote repository being mirrored (with user:token if needed).

mirror
boolean
 Yes
Enables pull mirroring on project when set to true.

mirror_trigger_builds
boolean
 No
Trigger pipelines for mirror updates when set to true.

only_mirror_protected_branches
boolean
 No
Limits mirroring to only protected branches when set to true.

mirror_branch_regex
String
 No
Contains a regular expression. Only branches with names matching the regex are mirrored. Requires only_mirror_protected_branches to be disabled.
Start the pull mirroring process for a Project 
Moved to GitLab Premium in 13.9.
POST /projects/:id/mirror/pull
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"
Project badges
Read more in the Project Badges documentation.
Download snapshot of a Git repository
This endpoint may only be accessed by an administrative user.
Download a snapshot of the project (or wiki, if requested) Git repository. This
snapshot is always in uncompressed tar
format.
If a repository is corrupted to the point where git clone doesn’t work, the
snapshot may allow some of the data to be retrieved.
GET /projects/:id/snapshot
AttributeTypeRequiredDescription
idinteger or string YesThe ID or URL-encoded path of the project.
wikiboolean NoWhether to download the wiki, rather than project, repository.
Get the path to repository storage
Introduced in GitLab 14.0.
Get the path to repository storage for specified project if Gitaly Cluster is not being used. If Gitaly Cluster is being used, see
Praefect-generated replica paths (GitLab 15.0 and later).
Available for administrators only.
GET /projects/:id/storage
AttributeTypeRequiredDescription
idinteger or string YesID or URL-encoded path of the project.
[
    "project_id": 1,
    "disk_path": "@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
    "created_at": "2012-10-12T17:04:47Z",
    "repository_storage": "default"
Docs
Edit this page
to fix an error or add an improvement in a merge request.

Create an issue
to suggest an improvement to this page.

Product
Create an issue
if there's something you don't like about this feature.

Propose functionality
by submitting a feature request.

Join First Look
to help shape new features.
Feature availability and product trials
View pricing
to see all GitLab tiers and features, or to upgrade.

Try GitLab for free
with access to all features for 30 days.

Get Help

If you didn't find what you were looking for,
search the docs.

If you want help with something specific and could use community support,
post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab
subscription).

Request support