debian-mirror-gitlab/doc/api/group_labels.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

276 lines
10 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
stage: Plan
group: Project Management
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-23 00:09:42 +05:30
---
2021-09-30 23:02:18 +05:30
# Group labels API **(FREE)**
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21368) in GitLab 11.8.
2019-03-02 22:35:43 +05:30
2022-05-07 20:08:51 +05:30
This API supports managing [group labels](../user/project/labels.md#types-of-labels).
2021-09-30 23:02:18 +05:30
It allows users to list, create, update, and delete group labels. Furthermore, users can subscribe to and
unsubscribe from group labels.
2019-03-02 22:35:43 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-11-11 11:23:49 +05:30
The `description_html` - was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) to response JSON in GitLab 12.7.
2020-03-13 15:44:24 +05:30
2019-03-02 22:35:43 +05:30
## List group labels
Get all labels for a given group.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
GET /groups/:id/labels
```
2019-10-12 21:52:04 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-11-11 11:23:49 +05:30
| `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543) in GitLab 12.2)_ |
2019-12-21 20:55:43 +05:30
| `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. |
2021-01-29 00:20:46 +05:30
| `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 |
| `only_group_labels` | boolean | no | Toggle to include only group labels or also project labels. Defaults to `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 |
| `search` | string | no | Keyword to filter labels by. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 |
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true"
2019-03-02 22:35:43 +05:30
```
Example response:
```json
[
{
"id": 7,
"name": "bug",
"color": "#FF0000",
2019-07-07 11:18:12 +05:30
"text_color" : "#FFFFFF",
2019-03-02 22:35:43 +05:30
"description": null,
2020-03-13 15:44:24 +05:30
"description_html": null,
2019-03-02 22:35:43 +05:30
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
},
{
"id": 4,
"name": "feature",
"color": "#228B22",
2019-07-07 11:18:12 +05:30
"text_color" : "#FFFFFF",
2019-03-02 22:35:43 +05:30
"description": null,
2020-03-13 15:44:24 +05:30
"description_html": null,
2019-03-02 22:35:43 +05:30
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
}
]
```
2019-12-21 20:55:43 +05:30
## Get a single group label
Get a single label for a given group.
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
GET /groups/:id/labels/:label_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. |
2019-12-21 20:55:43 +05:30
| `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`. |
2021-01-29 00:20:46 +05:30
| `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 |
| `only_group_labels` | boolean | no | Toggle to include only group labels or also project labels. Defaults to `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 |
2019-12-21 20:55:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"
2019-12-21 20:55:43 +05:30
```
Example response:
```json
{
"id": 7,
"name": "bug",
"color": "#FF0000",
"text_color" : "#FFFFFF",
"description": null,
2020-03-13 15:44:24 +05:30
"description_html": null,
2019-12-21 20:55:43 +05:30
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
}
```
2019-03-02 22:35:43 +05:30
## Create a new group label
Create a new group label for a given group.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
POST /groups/:id/labels
```
| Attribute | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
2019-03-02 22:35:43 +05:30
| `name` | string | yes | The name of the label |
2021-09-30 23:02:18 +05:30
| `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](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) |
2019-07-07 11:18:12 +05:30
| `description` | string | no | The description of the label, |
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
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"
2019-03-02 22:35:43 +05:30
```
Example response:
```json
{
"id": 9,
"name": "Feature Proposal",
"color": "#FFA500",
2019-07-07 11:18:12 +05:30
"text_color" : "#FFFFFF",
2019-03-02 22:35:43 +05:30
"description": "Describes new ideas",
2020-03-13 15:44:24 +05:30
"description_html": "Describes new ideas",
2019-03-02 22:35:43 +05:30
"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.
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
PUT /groups/:id/labels/:label_id
2019-03-02 22:35:43 +05:30
```
| Attribute | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
2019-12-21 20:55:43 +05:30
| `label_id` | integer or string | yes | The ID or title of a group's label. |
2019-03-02 22:35:43 +05:30
| `new_name` | string | no | The new name of the label |
2021-09-30 23:02:18 +05:30
| `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](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) |
2019-07-07 11:18:12 +05:30
| `description` | string | no | The description of the label. |
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
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"
2019-03-02 22:35:43 +05:30
```
Example response:
```json
{
"id": 9,
"name": "Feature Idea",
"color": "#FFA500",
2019-07-07 11:18:12 +05:30
"text_color" : "#FFFFFF",
2019-03-02 22:35:43 +05:30
"description": "Describes new ideas",
2020-03-13 15:44:24 +05:30
"description_html": "Describes new ideas",
2019-03-02 22:35:43 +05:30
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
}
```
2021-02-22 17:27:13 +05:30
NOTE:
2020-07-28 23:09:34 +05:30
An older endpoint `PUT /groups/:id/labels` with `name` in the parameters is still available, but deprecated.
2019-12-21 20:55:43 +05:30
2019-03-02 22:35:43 +05:30
## Delete a group label
Deletes a group label with a given name.
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
DELETE /groups/:id/labels/:label_id
2019-03-02 22:35:43 +05:30
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
2019-12-21 20:55:43 +05:30
| `label_id` | integer or string | yes | The ID or title of a group's label. |
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"
2019-03-02 22:35:43 +05:30
```
2021-02-22 17:27:13 +05:30
NOTE:
2020-07-28 23:09:34 +05:30
An older endpoint `DELETE /groups/:id/labels` with `name` in the parameters is still available, but deprecated.
2019-12-21 20:55:43 +05:30
2019-03-02 22:35:43 +05:30
## Subscribe to a group label
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.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
POST /groups/:id/labels/:label_id/subscribe
```
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
2019-07-07 11:18:12 +05:30
| `label_id` | integer or string | yes | The ID or title of a group's label. |
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe"
2019-03-02 22:35:43 +05:30
```
Example response:
```json
{
"id": 9,
"name": "Feature Idea",
"color": "#FFA500",
2019-07-07 11:18:12 +05:30
"text_color" : "#FFFFFF",
2019-03-02 22:35:43 +05:30
"description": "Describes new ideas",
2020-03-13 15:44:24 +05:30
"description_html": "Describes new ideas",
2019-03-02 22:35:43 +05:30
"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.
2020-04-08 14:13:33 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
POST /groups/:id/labels/:label_id/unsubscribe
```
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
2019-07-07 11:18:12 +05:30
| `label_id` | integer or string | yes | The ID or title of a group's label. |
2019-03-02 22:35:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe"
2019-03-02 22:35:43 +05:30
```
Example response:
```json
{
"id": 9,
"name": "Feature Idea",
"color": "#FFA500",
2019-07-07 11:18:12 +05:30
"text_color" : "#FFFFFF",
2019-03-02 22:35:43 +05:30
"description": "Describes new ideas",
2020-03-13 15:44:24 +05:30
"description_html": "Describes new ideas",
2019-03-02 22:35:43 +05:30
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
}
```