Resource subscriptions

Use this API to subscribe to and unsubscribe from issues, merge requests, and labels in projects and groups.

All API calls to non-public information require authentication.

POST /api/v4/groups/{id}/labels/{subscribable_id}/subscribe

Subscribes the currently authenticated user to a specified group label. They will receive notifications on changes to this item.

Parameters

Name	Type	Description
`id` Path, required	String	The group ID
`subscribable_id` Path, required	String	The ID of a resource

Responses

Code	Description	Schema
`201`	Created	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

Unsubscribe to a group label

POST /api/v4/groups/{id}/labels/{subscribable_id}/unsubscribe

Unsubscribes the currently authenticated user from a specified group label. They will no longer receive notifications on changes to this item.

Parameters

Name	Type	Description
`id` Path, required	String	The group ID
`subscribable_id` Path, required	String	The ID of a resource

Responses

Code	Description	Schema
`201`	Created	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

POST /api/v4/projects/{id}/issues/{subscribable_id}/subscribe

Subscribes the currently authenticated user to a specified issue. They will receive notifications on changes to this item.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID
`subscribable_id` Path, required	String	The ID of a resource

Responses

Code	Description	Schema
`201`	Created	APIEntitiesIssue
`400`	Bad Request	—
`404`	Not Found	—

Unsubscribe to an issue

POST /api/v4/projects/{id}/issues/{subscribable_id}/unsubscribe

Unsubscribes the currently authenticated user from a specified issue. They will no longer receive notifications on changes to this item.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID
`subscribable_id` Path, required	String	The ID of a resource

Responses

Code	Description	Schema
`201`	Created	APIEntitiesIssue
`400`	Bad Request	—
`404`	Not Found	—

POST /api/v4/projects/{id}/labels/{subscribable_id}/subscribe

Subscribes the currently authenticated user to a specified project label. They will receive notifications on changes to this item.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID
`subscribable_id` Path, required	String	The ID of a resource

Responses

Code	Description	Schema
`201`	Created	APIEntitiesProjectLabel
`400`	Bad Request	—
`404`	Not Found	—

Unsubscribe to a project label

POST /api/v4/projects/{id}/labels/{subscribable_id}/unsubscribe

Unsubscribes the currently authenticated user from a specified project label. They will no longer receive notifications on changes to this item.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID
`subscribable_id` Path, required	String	The ID of a resource

Responses

Code	Description	Schema
`201`	Created	APIEntitiesProjectLabel
`400`	Bad Request	—
`404`	Not Found	—

POST /api/v4/projects/{id}/merge_requests/{subscribable_id}/subscribe

Subscribes the currently authenticated user to a specified merge request. They will receive notifications on changes to this item.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID
`subscribable_id` Path, required	String	The ID of a resource

Responses

Code	Description	Schema
`201`	Created	APIEntitiesMergeRequest
`400`	Bad Request	—
`404`	Not Found	—

Unsubscribe to a merge request

POST /api/v4/projects/{id}/merge_requests/{subscribable_id}/unsubscribe

Unsubscribes the currently authenticated user from a specified merge request. They will no longer receive notifications on changes to this item.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID
`subscribable_id` Path, required	String	The ID of a resource

Responses

Code	Description	Schema
`201`	Created	APIEntitiesMergeRequest
`400`	Bad Request	—
`404`	Not Found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCiPipeline

Property	Type	Description
`archived`	Boolean	Example: `false`
`before_sha`	String	Example: `a91957a858320c0e17f3a0eca7cfacbff50ea29a`
`committed_at`	String (date-time)	Example: `2015-12-24T15:51:21.880Z`
`coverage`	Number (float)	Example: `98.29`
`created_at`	String (date-time)	Example: `2015-12-24T15:51:21.880Z`
`detailed_status`	DetailedStatusEntity	—
`duration`	Integer	Time spent running in seconds Example: `127`
`finished_at`	String (date-time)	Example: `2015-12-24T17:54:31.198Z`
`id`	Integer (int64)	Example: `1`
`iid`	Integer	Example: `2`
`project_id`	Integer (int64)	Example: `3`
`queued_duration`	Integer	Time spent enqueued in seconds Example: `63`
`ref`	String	Example: `feature-branch`
`sha`	String	Example: `0ec9e58fdfca6cdd6652c083c9edb53abc0bad52`
`source`	String	Example: `push`
`started_at`	String (date-time)	Example: `2015-12-24T17:54:30.733Z`
`status`	String	Example: `success`
`tag`	Boolean	Example: `false`
`updated_at`	String (date-time)	Example: `2015-12-24T17:54:31.198Z`
`user`	APIEntitiesUserBasic	—
`web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61`
`yaml_errors`	String	Example: `widgets:build: needs 'widgets:test'`

APIEntitiesCiPipelineBasic

Property	Type	Description
`created_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`id`	Integer (int64)	Example: `1`
`iid`	Integer	Example: `2`
`project_id`	Integer (int64)	Example: `3`
`ref`	String	Example: `feature-branch`
`sha`	String	Example: `0ec9e58fdfca6cdd6652c083c9edb53abc0bad52`
`source`	String	Example: `push`
`status`	String	Example: `success`
`updated_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61`

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesDiffRefs

Property	Type	Description
`base_sha`	String	Example: `b83d6e391c22777fca1ed3012fce84f633d7fed0`
`head_sha`	String	Example: `b83d6e391c22777fca1ed3012fce84f633d7fed0`
`start_sha`	String	Example: `b83d6e391c22777fca1ed3012fce84f633d7fed0`

APIEntitiesGroupLabel

Property	Type	Description
`archived`	Boolean	Example: `false`
`closed_issues_count`	Integer	Example: `0`
`color`	String	Example: `#FF0000`
`description`	String	Example: `Bug reported by user`
`description_html`	String	Example: `<p>Bug reported by user</p>`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `bug`
`open_issues_count`	Integer	Example: `1`
`open_merge_requests_count`	Integer	Example: `1`
`subscribed`	Boolean	Example: `false`
`text_color`	String	Example: `#FFFFFF`

APIEntitiesIssuableReferences

Property	Type	Description
`full`	String	Example: `test&6`
`relative`	String	Example: `&6`
`short`	String	Example: `&6`

APIEntitiesIssuableTimeStats

Property	Type	Description
`human_time_estimate`	String	Example: `3h 30m`
`human_total_time_spent`	String	Example: `1h`
`time_estimate`	Integer	Example: `12600`
`total_time_spent`	Integer	Example: `3600`

APIEntitiesIssue

Property	Type	Description
`_links`	Object	—
`_links.award_emoji`	String	Example: `http://example.com/api/v4/projects/1/issues/2/award_emoji`
`_links.closed_as_duplicate_of`	String	Example: `http://example.com/api/v4/projects/1/issues/75`
`_links.notes`	String	Example: `http://example.com/api/v4/projects/1/issues/2/notes`
`_links.project`	String	Example: `http://example.com/api/v4/projects/1`
`_links.self`	String	Example: `http://example.com/api/v4/projects/1/issues/2`
`assignee`	APIEntitiesUserBasic	—
`assignees`	APIEntitiesUserBasic	—
`author`	APIEntitiesUserBasic	—
`closed_at`	String (date-time)	Example: `2022-11-15T08:30:55.232Z`
`closed_by`	APIEntitiesUserBasic	—
`confidential`	Boolean	—
`created_at`	String (date-time)	Example: `2022-08-17T12:46:35.053Z`
`description`	String	Example: `Repellendus impedit et vel velit dignissimos.`
`discussion_locked`	Boolean	—
`downvotes`	Integer	—
`due_date`	String (date)	Example: `2022-11-20`
`has_tasks`	Boolean	Example: `true`
`id`	Integer (int64)	Example: `84`
`iid`	Integer	Example: `14`
`imported`	Boolean	Example: `false`
`imported_from`	String	Example: `github`
`issue_type`	String	Example: `issue`
`labels`	Array of strings	Example: `["bug"]`
`merge_requests_count`	Integer	—
`milestone`	APIEntitiesMilestone	—
`moved_to_id`	Integer (int64)	Example: `1`
`project_id`	Integer (int64)	Example: `4`
`references`	APIEntitiesIssuableReferences	—
`service_desk_reply_to`	String	Example: `user@example.com`
`severity`	String	One of [“UNKNOWN”, “LOW”, “MEDIUM”, “HIGH”, “CRITICAL”]
`start_date`	String (date)	Example: `2022-11-18`
`state`	String	Example: `closed`
`subscribed`	Boolean	Example: `false`
`task_completion_status`	APIEntitiesTaskCompletionStatus	—
`task_status`	String	Example: `2 of 4 tasks completed`
`time_stats`	APIEntitiesIssuableTimeStats	—
`title`	String	Example: `Impedit et ut et dolores vero provident ullam est`
`type`	String	One of [“ISSUE”, “INCIDENT”, “TEST_CASE”, “REQUIREMENT”, “TASK”, “TICKET”] Example: `ISSUE`
`updated_at`	String (date-time)	Example: `2022-11-14T17:22:01.470Z`
`upvotes`	Integer	—
`user_notes_count`	Integer	—
`web_url`	String	Example: `http://example.com/example/example/issues/14`

APIEntitiesMergeRequest

Property	Type	Description
`allow_collaboration`	Boolean	—
`allow_maintainer_to_push`	Boolean	—
`assignee`	APIEntitiesUserBasic	—
`assignees`	APIEntitiesUserBasic	—
`author`	APIEntitiesUserBasic	—
`blocking_discussions_resolved`	Boolean	—
`changes_count`	String	Example: `1`
`closed_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`closed_by`	APIEntitiesUserBasic	—
`created_at`	String (date-time)	Example: `2022-08-17T12:46:35.053Z`
`description`	String	Example: `Repellendus impedit et vel velit dignissimos.`
`description_html`	String	—
`detailed_merge_status`	String	Example: `mergeable`
`diff_refs`	APIEntitiesDiffRefs	—
`discussion_locked`	Boolean	—
`diverged_commits_count`	Integer	Example: `0`
`downvotes`	Integer	—
`draft`	Boolean	—
`first_contribution`	Boolean	—
`first_deployed_to_production_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`force_remove_source_branch`	Boolean	—
`has_conflicts`	Boolean	—
`head_pipeline`	APIEntitiesCiPipeline	—
`id`	Integer (int64)	Example: `84`
`iid`	Integer	Example: `14`
`imported`	Boolean	—
`imported_from`	String	Example: `bitbucket`
`labels`	Array of strings	—
`latest_build_finished_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`latest_build_started_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merge_after`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merge_commit_sha`	String	Example: `1234abcd`
`merge_error`	String	Example: `Merge error`
`merge_status`	String	Example: `unchecked`
`merge_user`	APIEntitiesUserBasic	—
`merge_when_pipeline_succeeds`	Boolean	—
`merged_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merged_by`	APIEntitiesUserBasic	—
`milestone`	APIEntitiesMilestone	—
`pipeline`	APIEntitiesCiPipelineBasic	—
`prepared_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`project_id`	Integer (int64)	Example: `4`
`rebase_in_progress`	Boolean	—
`reference`	String	Example: `!1`
`references`	APIEntitiesIssuableReferences	—
`reviewers`	APIEntitiesUserBasic	—
`sha`	String	Example: `1234abcd`
`should_remove_source_branch`	Boolean	—
`source_branch`	String	—
`source_project_id`	Integer (int64)	—
`squash`	Boolean	—
`squash_commit_sha`	String	Example: `1234abcd`
`squash_on_merge`	Boolean	—
`state`	String	Example: `closed`
`subscribed`	Boolean	—
`target_branch`	String	—
`target_project_id`	Integer (int64)	—
`task_completion_status`	APIEntitiesTaskCompletionStatus	—
`time_stats`	APIEntitiesIssuableTimeStats	—
`title`	String	Example: `Impedit et ut et dolores vero provident ullam est`
`title_html`	String	—
`updated_at`	String (date-time)	Example: `2022-11-14T17:22:01.470Z`
`upvotes`	Integer	—
`user`	Object	—
`user.can_merge`	Boolean	—
`user_notes_count`	Integer	—
`web_url`	String	Example: `https://gitlab.example.com/my-group/my-project/-/merge_requests/1`
`work_in_progress`	Boolean	—

APIEntitiesMilestone

Property	Type	Description
`created_at`	String	—
`description`	String	—
`due_date`	String	—
`expired`	Boolean	—
`group_id`	String	—
`id`	Integer (int64)	—
`iid`	Integer (int64)	—
`project_id`	Integer (int64)	—
`start_date`	String	—
`state`	String	—
`title`	String	—
`updated_at`	String	—
`web_url`	String	—

APIEntitiesProjectLabel

Property	Type	Description
`archived`	Boolean	Example: `false`
`closed_issues_count`	Integer	Example: `0`
`color`	String	Example: `#FF0000`
`description`	String	Example: `Bug reported by user`
`description_html`	String	Example: `<p>Bug reported by user</p>`
`id`	Integer (int64)	Example: `1`
`is_project_label`	Boolean	—
`name`	String	Example: `bug`
`open_issues_count`	Integer	Example: `1`
`open_merge_requests_count`	Integer	Example: `1`
`priority`	Integer	Example: `10`
`subscribed`	Boolean	Example: `false`
`text_color`	String	Example: `#FFFFFF`

APIEntitiesTaskCompletionStatus

Property	Type	Description
`completed_count`	Integer	Example: `3`
`count`	Integer	Example: `5`

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

DetailedStatusEntity

Property	Type	Description
`action`	Object	—
`action.button_title`	String	Example: `Cancel this job`
`action.confirmation_message`	String	Example: `Are you sure?`
`action.icon`	String	Example: `cancel`
`action.method`	String	Example: `post`
`action.path`	String	Example: `/namespace1/project1/-/jobs/2/cancel`
`action.title`	String	Example: `Cancel`
`details_path`	String	Example: `/test-group/test-project/-/pipelines/287`
`favicon`	String	Example: `/assets/ci_favicons/favicon_status_success.png`
`group`	String	Example: `success`
`has_details`	Boolean	Example: `true`
`icon`	String	Example: `status_success`
`illustration`	Object	Example: `{"content":"This job depends on upstream jobs that need to succeed in order for this job to be triggered","image":"illustrations/empty-state/empty-job-not-triggered-md.svg","size":"","title":"This job has not been triggered yet"}`
`label`	String	Example: `passed`
`text`	String	Example: `passed`
`tooltip`	String	Example: `passed`

Subscribe to a group label

Unsubscribe to a group label

Subscribe to an issue

Unsubscribe to an issue

Subscribe to a project label

Unsubscribe to a project label

Subscribe to a merge request

Unsubscribe to a merge request

Schemas

APIEntitiesCiPipeline

APIEntitiesCiPipelineBasic

APIEntitiesCustomAttribute

APIEntitiesDiffRefs

APIEntitiesGroupLabel

APIEntitiesIssuableReferences

APIEntitiesIssuableTimeStats

APIEntitiesIssue

APIEntitiesMergeRequest

APIEntitiesMilestone

APIEntitiesProjectLabel

APIEntitiesTaskCompletionStatus

APIEntitiesUserBasic

DetailedStatusEntity

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error