Labels¶

Labels are used to categorize issues and pull requests. The API lets you create, update, and delete repository task labels, replace the label set of a repository or a single issue in bulk, and query enterprise-level labels.

Objects¶

Object	Description	Related endpoint
Task label	A label defined inside a repository: name, color, description	List a repository's task labels
Repository label set	Replaces a repository's label list as a whole	Replace all repository labels
Issue label set	Replaces or clears all labels of an issue	Replace all issue labels
Enterprise label	A label defined under an enterprise namespace	Get all enterprise labels

Identification¶

A repository is identified by owner + repo; a label is identified by original_name (used to locate the original label when renaming) or by label name.
An issue is identified by number, and an enterprise by enterprise.

Common tasks¶

Task	Endpoint
List repository labels	`GET /api/v5/repos/{owner}/{repo}/labels`
Create a label	`POST /api/v5/repos/{owner}/{repo}/labels`
Update a label	`PATCH /api/v5/repos/{owner}/{repo}/labels/{original_name}`
Delete a label	`DELETE /api/v5/repos///labels/*`
Replace all repository labels	`PUT /api/v5/repos/{owner}/{repo}/project_labels`
Replace all issue labels	`PUT /api/v5/repos/{owner}/{repo}/issues/{number}/labels`
Clear all issue labels	`DELETE /api/v5/repos/{owner}/{repo}/issues/{number}/labels`
List enterprise labels	`GET /api/v5/enterprises/{enterprise}/labels`

Notes¶

Replacing all repository labels uses PUT …/project_labels, not …/labels; only creating, updating, and deleting individual labels goes through /labels.
The path for deleting a task label uses * placeholders: DELETE /api/v5/repos/*/*/labels/*, which is inconsistent with the other {owner}/{repo} notation.
Enterprise labels have two endpoints under different version prefixes: GET /api/v5/enterprises/{enterprise}/labels and GET /api/v8/enterprises/{enterprise}/labels. Their fields may differ; choose as needed.
When renaming, use original_name to locate the label; after the name is changed, subsequent calls must use the new name.
The endpoints for attaching labels to issues and PRs live in their respective Issue and Pull Request groups. This group only covers the definition of labels themselves and their bulk replacement.

Endpoints¶

This module contains 9 endpoints in total.

#	Endpoint	Method and path	Description
1	Replace all repository labels	`PUT /api/v5/repos/{owner}/{repo}/project_labels`	This endpoint replaces all labels of the specified repository: pass a list of new label names to overwrite all existing labels in one go; label names are converted to lowercase and deduplicated. Passing an empty array…
2	Delete all issue labels	`DELETE /api/v5/repos/{owner}/{repo}/issues/{number}/labels`	This endpoint deletes all labels of an issue in the specified repository, locating the target by repository namespace address and issue number. On success it returns an empty…
3	Replace all issue labels	`PUT /api/v5/repos/{owner}/{repo}/issues/{number}/labels`	This endpoint replaces all labels of the specified issue in the specified repository. The request body is an array of strings made up of label names; after replacement, the issue's labels…
4	Update a repository's task label	`PATCH /api/v5/repos/{owner}/{repo}/labels/{original_name}`	This endpoint updates a task label of the specified repository, locating the target label by its original name. It supports changing the label's new name and color. On success it returns the label's ID…
5	Get all task labels in a repository	`GET /api/v5/repos/{owner}/{repo}/labels`	This endpoint gets all task labels in the specified repository, returning the label ID, name, color, and owning repository ID, among other information. It also supports controlling the number of returned labels via pagination parameters…
6	Create a repository task label	`POST /api/v5/repos/{owner}/{repo}/labels`	This endpoint creates a task label under the specified repository. Submitting a label name and color completes the creation; on success it returns the label's identifier, name, and color information.
7	Delete a repository task label	`DELETE /api/v5/repos///labels/*`	This endpoint deletes a task label from the specified repository. By passing the repository's namespace address, repository path, and label name, the corresponding label is removed from the repository. On success…
8	Get all enterprise labels	`GET /api/v5/enterprises/{enterprise}/labels`	This endpoint gets all labels of the specified enterprise, supports paginated queries with a maximum of 100 per page. The result is a list of labels, including label ID, name, color…
9	Get label list	`GET /api/v8/enterprises/{enterprise}/labels`	Call this endpoint to get the label list.

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc