--- stage: Data Stores group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Projects API **(FREE ALL)** Interact with [projects](../user/project/index.md) 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](../user/public_access.md). The fields returned in responses vary based on the [permissions](../user/permissions.md) 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](https://about.gitlab.com/pricing/). - `approvals_before_merge`: Use the [Merge request approvals API](merge_request_approvals.md) instead. Available only to [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/). ## 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](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) 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. ```plaintext GET /projects ``` | Attribute | Type | Required | Description | |--------------------------------------------|----------|------------------------|-------------| | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `id_after` | integer | **{dotted-circle}** No | Limit results to projects with IDs greater than the specified ID. | | `id_before` | integer | **{dotted-circle}** No | Limit results to projects with IDs less than the specified ID. | | `imported` | boolean | **{dotted-circle}** No | Limit results to projects which were imported from external systems by current user. | | `last_activity_after` | datetime | **{dotted-circle}** No | Limit results to projects with last activity after specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | | `last_activity_before` | datetime | **{dotted-circle}** No | Limit results to projects with last activity before specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [role (`access_level`)](members.md#roles). | | `order_by` | string | **{dotted-circle}** No | Return 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](https://gitlab.com/gitlab-org/gitlab/-/issues/332890) 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`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | | `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed. | | `repository_storage` | string | **{dotted-circle}** No | Limit results to projects stored on `repository_storage`. _(administrators only)_ | | `search_namespaces` | boolean | **{dotted-circle}** No | Include ancestor namespaces when matching search criteria. Default is `false`. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This operation is a no-op without authentication where only simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Available only to users with at least the Reporter role. | | `topic` | string | **{dotted-circle}** No | Comma-separated topic names. Limit results to projects that match all of given topics. See `topics` attribute. | | `topic_id` | integer | **{dotted-circle}** No | Limit results to projects with the assigned topic given by the topic ID. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | | `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | | `updated_before` | datetime | **{dotted-circle}** No | Limit results to projects last updated before the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. For this filter to work, you must also provide `updated_at` as the `order_by` attribute. | | `updated_after` | datetime | **{dotted-circle}** No | Limit results to projects last updated after the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) 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](rest/index.md#keyset-based-pagination) for selected `order_by` options. When `simple=true` or the user is unauthenticated this returns something like: Example request: ```shell curl --request GET "https://gitlab.example.com/api/v4/projects" ``` Example response: ```json [ { "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": "git@gitlab.example.com: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: ```json [ { "id": 4, "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "description_html": "
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "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": "git@gitlab.example.com: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, "emails_enabled": 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_forward_deployment_rollback_allowed": 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](custom_attributes.md) with: ```plaintext GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value ``` Example request: ```shell 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](rest/index.md#offset-based-pagination) is [limited to 50,000 records](https://gitlab.com/gitlab-org/gitlab/-/issues/34565). [Keyset pagination](rest/index.md#keyset-based-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](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 14.10. Get a list of visible projects owned by the given user. When accessed without authentication, only public projects are returned. Prerequisite: - To view [certain attributes](https://gitlab.com/gitlab-org/gitlab/-/blob/520776fa8e5a11b8275b7c597d75246fcfc74c89/lib/api/entities/project.rb#L109-130), you must be an administrator or have the Owner role for the project. NOTE: 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](rest/index.md#keyset-based-pagination) for selected `order_by` options. ```plaintext GET /users/:user_id/projects ``` | Attribute | Type | Required | Description | |-------------------------------|---------|------------------------|-------------| | `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `id_after` | integer | **{dotted-circle}** No | Limit results to projects with IDs greater than the specified ID. | | `id_before` | integer | **{dotted-circle}** No | Limit results to projects with IDs less than the specified ID. | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [role (`access_level`)](members.md#roles). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. Without authentication, this operation is a no-op; only simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Available only to users with at least the Reporter role. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | | `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | | `updated_before` | datetime | **{dotted-circle}** No | Limit results to projects last updated before the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. | | `updated_after` | datetime | **{dotted-circle}** No | Limit results to projects last updated after the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. | ```json [ { "id": 4, "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "description_html": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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_forward_deployment_rollback_allowed": 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": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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_forward_deployment_rollback_allowed": 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 a user has contributed to Get a list of visible projects a given user has contributed to. ```plaintext GET /users/:user_id/contributed_projects ``` | Attribute | Type | Required | Description | |-------------------------------|---------|------------------------|-------------| | `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. Without authentication, this operation is a no-op; only simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | ```shell curl --header "PRIVATE-TOKEN:Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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" } } ] ``` ## List projects starred by a user > The `_links.cluster_agents` attribute in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 14.10. Get a list of visible projects starred by the given user. When accessed without authentication, only public projects are returned. ```plaintext GET /users/:user_id/starred_projects ``` | Attribute | Type | Required | Description | |-------------------------------|---------|------------------------|-------------| | `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [role (`access_level`)](members.md#roles). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. Without authentication, this operation is a no-op; only simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Available only to users with at least the Reporter role. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | | `updated_before` | datetime | **{dotted-circle}** No | Limit results to projects last updated before the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. | | `updated_after` | datetime | **{dotted-circle}** No | Limit results to projects last updated after the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. | ```shell curl --header "PRIVATE-TOKEN:Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 14.10. Get a specific project. This endpoint can be accessed without authentication if the project is publicly accessible. ```plaintext GET /projects/:id ``` | Attribute | Type | Required | Description | |--------------------------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `license` | boolean | **{dotted-circle}** No | Include project license data. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Available only to users with at least the Reporter role. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrators only)_ | ```json { "id": 3, "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "description_html": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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_forward_deployment_rollback_allowed": 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](https://about.gitlab.com/pricing/) can also see the `only_allow_merge_if_all_status_checks_passed` parameters using GitLab 15.5 and later: ```json { "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. ```json { "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":"git@gitlab.com: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 **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55718) in GitLab 13.10. Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) can also see the `issues_template` and `merge_requests_template` parameters for managing [issue and merge request description templates](../user/project/description_templates.md). ```json { "id": 3, "issues_template": null, "merge_requests_template": null, ... } ``` ## Get project users Get the users list of a project. ```plaintext GET /projects/:id/users ``` | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | | `skip_users` | integer array | **{dotted-circle}** No | Filter out users with the specified IDs. | ```json [ { "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. ```plaintext GET /projects/:id/groups ``` | Attribute | Type | Required | Description | |-----------------------------|-------------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific groups. | | `shared_min_access_level` | integer | **{dotted-circle}** No | Limit to shared groups with at least this [role (`access_level`)](members.md#roles). | | `shared_visible_only` | boolean | **{dotted-circle}** No | Limit to shared groups user has access to. | | `skip_groups` | array of integers | **{dotted-circle}** No | Skip the group IDs passed. | | `with_shared` | boolean | **{dotted-circle}** No | Include projects shared with this group. Default is `false`. | ```json [ { "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 ```plaintext GET /projects/:id/share_locations ``` | Attribute | Type | Required | Description | |-----------------------------|-------------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific groups. | ```json [ { "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](events.md#list-a-projects-visible-events). ## Create project > `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) 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:password@gitlab.company.com/group/project.git`, where `password` is a public access key with the `api` scope enabled. ```plaintext POST /projects ``` Example request: ```shell curl --request POST --header "PRIVATE-TOKEN:Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "internal", "ssh_url_to_repo": "git@example.com: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](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 14.10. Stars a given project. Returns status code `304` if the project is already starred. ```plaintext POST /projects/:id/star ``` | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN:Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "internal", "ssh_url_to_repo": "git@example.com: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](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 14.10. Unstars a given project. Returns status code `304` if the project is not starred. ```plaintext POST /projects/:id/unstar ``` | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN:Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "internal", "ssh_url_to_repo": "git@example.com: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. ```plaintext GET /projects/:id/starrers ``` | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | ```shell curl --header "PRIVATE-TOKEN:Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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_forward_deployment_rollback_allowed": 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](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) 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. ```plaintext POST /projects/:id/unarchive ``` | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN:Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "default_branch": "master", "visibility": "private", "ssh_url_to_repo": "git@example.com: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_forward_deployment_rollback_allowed": 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](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. This endpoint: - Deletes a project including all associated resources (including issues and merge requests). - In [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) and later, on [Premium or Ultimate](https://about.gitlab.com/pricing/) tiers, [delayed project deletion](../user/project/settings/index.md#delayed-project-deletion) is applied if enabled. - From [GitLab 15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/396500) on [Premium or Ultimate](https://about.gitlab.com/pricing/) 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](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or Ultimate](https://about.gitlab.com/pricing/) tiers, delayed project deletion is enabled by default. The deletion happens after the number of days specified in the [default deletion delay](../administration/settings/visibility_and_access_controls.md#deletion-protection). WARNING: The option to delete projects immediately from deletion protection settings in the Admin Area was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.9 and removed in GitLab 16.0. ```plaintext DELETE /projects/:id ``` | Attribute | Type | Required | Description | |------------------------------------|-------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `permanently_remove` **(PREMIUM)** | boolean/string | no | Immediately deletes a project if it is marked for deletion. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396500) in GitLab 15.11 | | `full_path` **(PREMIUM)** | string | no | Full path of project to use with `permanently_remove`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396500) in GitLab 15.11. To find the project path, use `path_with_namespace` from [get single project](projects.md#get-single-project) | ## Restore project marked for deletion **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. Restores project marked for deletion. ```plaintext POST /projects/:id/restore ``` | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ## Upload a file > - Maximum attachment size enforcement [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57250) in GitLab 13.11 [with a flag](../administration/feature_flags.md) named `enforce_max_attachment_size_upload_api`. Disabled by default. > - Maximum attachment size [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62542) in GitLab 13.11. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112450) 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. ```plaintext POST /projects/:id/uploads ``` | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `file` | string | **{check-circle}** Yes | The file to be uploaded. | | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | 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: ```shell curl --request POST --header "PRIVATE-TOKEN:Lorem ipsum dolor sit amet, consectetur adipiscing elit.
", "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": "git@gitlab.example.com: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, "emails_enabled": 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](branches.md) documentation. ## Project import/export Read more in the [Project import/export](project_import_export.md) documentation. ## Project members Read more in the [Project members](members.md) documentation. ## Project vulnerabilities Read more in the [Project vulnerabilities](project_vulnerabilities.md) documentation. ## Get a project's pull mirror details **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354506) in GitLab 15.6. Returns the details of the project's pull mirror. ```plaintext GET /projects/:id/mirror/pull ``` Supported attributes: | Attribute | Type | Required | Description | |:----------|:------|:------------|:------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | Example request: ```shell curl --request GET --header "PRIVATE-TOKEN: