Labels

Use this API to manage labels for both projects and groups. For the difference between the two, see types of labels.

List all group labels

GET /api/v4/groups/{id}/labels

Lists all group labels for a specified group.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`with_counts` Query	Boolean	Include issue and merge request counts Default: `false`
`include_ancestor_groups` Query	Boolean	Include ancestor groups Default: `true`
`include_descendant_groups` Query	Boolean	Include descendant groups. This feature was added in GitLab 13.6 Default: `false`
`only_group_labels` Query	Boolean	Toggle to include only group labels or also project labels. This feature was added in GitLab 13.6 Default: `true`
`search` Query	String	Keyword to filter labels by. This feature was added in GitLab 13.6
`archived` Query	Boolean	Filter by archived status. This feature was added in GitLab 18.10
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

Create a group label

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

Creates a group label.

Parameters

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

Request body (application/json)

Property	Type	Description
`archived`	Boolean	Whether the label is archived
`color` Required	String	The color of the label given in 6-digit hex notation with leading ‘#’ sign (e.g. #FFAABB) or one of the allowed CSS color names
`description`	String	The description of label to be created
`name` Required	String	The name of the label to be created

Responses

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

Update a group label

PUT /api/v4/groups/{id}/labels

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

Parameters

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

Request body (application/json)

Property	Type	Description
`archived`	Boolean	Whether the label is archived
`color`	String	The new color of the label given in 6-digit hex notation with leading ‘#’ sign (e.g. #FFAABB) or one of the allowed CSS color names
`description`	String	The new description of label
`label_id`	Integer	The ID of the label to be updated
`name`	String	The name of the label to be updated
`new_name`	String	The new name of the label

Responses

Code	Description	Schema
`200`	OK	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

Delete a group label

DELETE /api/v4/groups/{id}/labels

Deletes a specified group label.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`name` Query, required	String	The name of the label to be deleted

Responses

Code	Description	Schema
`200`	OK	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a group label

GET /api/v4/groups/{id}/labels/{name}

Retrieves a specified group label.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`name` Path, required	String or integer	The ID or name of a label
`include_ancestor_groups` Query	Boolean	Include ancestor groups Default: `true`
`include_descendant_groups` Query	Boolean	Include descendant groups. This feature was added in GitLab 13.6 Default: `false`
`only_group_labels` Query	Boolean	Toggle to include only group labels or also project labels. This feature was added in GitLab 13.6 Default: `true`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

Update a group label

PUT /api/v4/groups/{id}/labels/{name}

Updates a specified group label. At least one parameter is required to update the group label.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`name` Path, required	String	The name or id of the label to be updated

Request body (application/json)

Property	Type	Description
`archived`	Boolean	Whether the label is archived
`color`	String	The new color of the label given in 6-digit hex notation with leading ‘#’ sign (e.g. #FFAABB) or one of the allowed CSS color names
`description`	String	The new description of label
`new_name`	String	The new name of the label

Responses

Code	Description	Schema
`200`	OK	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

Delete a group label

DELETE /api/v4/groups/{id}/labels/{name}

Deletes a specified group label.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`name` Path, required	String	The name or id of the label to be deleted

Responses

Code	Description	Schema
`200`	OK	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

List all project labels

GET /api/v4/projects/{id}/labels

Lists all labels for a specified project. By default, this request returns 20 results at a time because the API results are paginated.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`with_counts` Query	Boolean	Include issue and merge request counts Default: `false`
`include_ancestor_groups` Query	Boolean	Include ancestor groups Default: `true`
`search` Query	String	Keyword to filter labels by. This feature was added in GitLab 13.6
`archived` Query	Boolean	Filter by archived status. This feature was added in GitLab 18.10
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectLabel
`400`	Bad Request	—
`404`	Not Found	—

Create a project label

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

Creates a label for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`archived`	Boolean	Whether the label is archived
`color` Required	String	The color of the label given in 6-digit hex notation with leading ‘#’ sign (e.g. #FFAABB) or one of the allowed CSS color names
`description`	String	The description of label to be created
`name` Required	String	The name of the label to be created
`priority`	Integer	The priority of the label

Responses

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

Update an existing label (deprecated)

PUT /api/v4/projects/{id}/labels

At least one optional parameter is required.

Deprecated in GitLab 12.4. Use PUT /projects/:id/labels/:name instead.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`archived`	Boolean	Whether the label is archived
`color`	String	The new color of the label given in 6-digit hex notation with leading ‘#’ sign (e.g. #FFAABB) or one of the allowed CSS color names
`description`	String	The new description of label
`label_id`	Integer	The ID of the label to be updated
`name`	String	The name of the label to be updated
`new_name`	String	The new name of the label
`priority`	Integer	The priority of the label

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectLabel
`400`	Bad Request	—
`404`	Not Found	—

Delete an existing label (deprecated)

DELETE /api/v4/projects/{id}/labels

Deprecated in GitLab 12.4. Use DELETE /projects/:id/labels/:name instead.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`label_id` Query	Integer	The ID of the label to be deleted
`name` Query	String	The name of the label to be deleted

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectLabel
`400`	Bad Request	—
`404`	Not Found	—

Promote a label to a group label (deprecated)

PUT /api/v4/projects/{id}/labels/promote

Added in GitLab 12.3 and deprecated in GitLab 12.4. Use PUT /projects/:id/labels/:name/promote instead.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`name` Required	String	The name of the label to be promoted

Responses

Code	Description	Schema
`200`	OK	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a project label

GET /api/v4/projects/{id}/labels/{name}

Retrieves a specified label for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`name` Path, required	String or integer	The ID or name of a label
`include_ancestor_groups` Query	Boolean	Include ancestor groups Default: `true`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectLabel
`400`	Bad Request	—
`404`	Not Found	—

Update a project label

PUT /api/v4/projects/{id}/labels/{name}

Updates a specified label for a project with a different name or color. At least one parameter is required to update the label.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`name` Path, required	String	The name or id of the label to be updated

Request body (application/json)

Property	Type	Description
`archived`	Boolean	Whether the label is archived
`color`	String	The new color of the label given in 6-digit hex notation with leading ‘#’ sign (e.g. #FFAABB) or one of the allowed CSS color names
`description`	String	The new description of label
`new_name`	String	The new name of the label
`priority`	Integer	The priority of the label

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectLabel
`400`	Bad Request	—
`404`	Not Found	—

Delete a project label

DELETE /api/v4/projects/{id}/labels/{name}

Deletes a specified label from a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`name` Path, required	String	The name or id of the label to be deleted

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectLabel
`400`	Bad Request	—
`404`	Not Found	—

Promote a project label to a group label

PUT /api/v4/projects/{id}/labels/{name}/promote

Promotes a specified project label to a group label. The label keeps its ID.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`name` Path, required	String	The name or id of the label to be promoted

Responses

Code	Description	Schema
`200`	OK	APIEntitiesGroupLabel
`400`	Bad Request	—
`404`	Not Found	—

Schemas

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

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`

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`

List all group labels

Create a group label

Update a group label

Delete a group label

Retrieve a group label

Update a group label

Delete a group label

List all project labels

Create a project label

Update an existing label (deprecated)

Delete an existing label (deprecated)

Promote a label to a group label (deprecated)

Retrieve a project label

Update a project label

Delete a project label

Promote a project label to a group label

Schemas

APIEntitiesGroupLabel

APIEntitiesProjectLabel

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