Group labels API

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

This API supports managing group labels. It allows users to list, create, update, and delete group labels. Furthermore, users can subscribe to and unsubscribe from group labels.

List group labels

Get all labels for a given group.

GET /groups/:id/labels

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`with_counts`	boolean	no	Whether or not to include issue and merge request counts. Defaults to `false`.
`include_ancestor_groups`	boolean	no	Include ancestor groups. Defaults to `true`.
`include_descendant_groups`	boolean	no	Include descendant groups. Defaults to `false`.
`only_group_labels`	boolean	no	Toggle to include only group labels or also project labels. Defaults to `true`.
`search`	string	no	Keyword to filter labels by.

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true"

Example response:

[
  {
    "id": 7,
    "name": "bug",
    "color": "#FF0000",
    "text_color" : "#FFFFFF",
    "description": null,
    "description_html": null,
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false
  },
  {
    "id": 4,
    "name": "feature",
    "color": "#228B22",
    "text_color" : "#FFFFFF",
    "description": null,
    "description_html": null,
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false
  }
]

Get a single group label

Get a single label for a given group.

GET /groups/:id/labels/:label_id

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group.
`label_id`	integer or string	yes	The ID or title of a group’s label.
`include_ancestor_groups`	boolean	no	Include ancestor groups. Defaults to `true`.
`include_descendant_groups`	boolean	no	Include descendant groups. Defaults to `false`.
`only_group_labels`	boolean	no	Toggle to include only group labels or also project labels. Defaults to `true`.

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"

Example response:

{
  "id": 7,
  "name": "bug",
  "color": "#FF0000",
  "text_color" : "#FFFFFF",
  "description": null,
  "description_html": null,
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false
}

Create a new group label

Create a new group label for a given group.

POST /groups/:id/labels

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group
`name`	string	yes	The name of the label
`color`	string	yes	The color of the label given in 6-digit hex notation with leading ‘#’ sign (for example, #FFAABB) or one of the CSS color names
`description`	string	no	The description of the label,

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
     --data '{"name": "Feature Proposal", "color": "#FFA500", "description": "Describes new ideas" }' \
     "https://gitlab.example.com/api/v4/groups/5/labels"

Example response:

{
  "id": 9,
  "name": "Feature Proposal",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false
}

Update a group label

Updates an existing group label. At least one parameter is required, to update the group label.

PUT /groups/:id/labels/:label_id

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`label_id`	integer or string	yes	The ID or title of a group’s label.
`new_name`	string	no	The new name of the label
`color`	string	no	The color of the label given in 6-digit hex notation with leading ‘#’ sign (for example, #FFAABB) or one of the CSS color names
`description`	string	no	The description of the label.

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
     --data '{"new_name": "Feature Idea" }' "https://gitlab.example.com/api/v4/groups/5/labels/Feature%20Proposal"

Example response:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false
}

An older endpoint PUT /groups/:id/labels with name in the parameters is still available, but deprecated.

Delete a group label

Deletes a group label with a given name.

DELETE /groups/:id/labels/:label_id

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`label_id`	integer or string	yes	The ID or title of a group’s label.

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"

An older endpoint DELETE /groups/:id/labels with name in the parameters is still available, but deprecated.

Subscribes the authenticated user to a group label to receive notifications. If the user is already subscribed to the label, the status code 304 is returned.

POST /groups/:id/labels/:label_id/subscribe

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`label_id`	integer or string	yes	The ID or title of a group’s label.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe"

Example response:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": true
}

Unsubscribe from a group label

Unsubscribes the authenticated user from a group label to not receive notifications from it. If the user is not subscribed to the label, the status code 304 is returned.

POST /groups/:id/labels/:label_id/unsubscribe

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`label_id`	integer or string	yes	The ID or title of a group’s label.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe"

Example response:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false
}

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

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

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

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

Get help

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

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

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

Request support

Group labels API

List group labels

Get a single group label

Create a new group label

Update a group label

Delete a group label

Subscribe to a group label

Unsubscribe from a group label

Help & feedback

Docs

Product

Feature availability and product trials

Get help