Labels

List all labels for this repository

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

GET /repos/:owner/:repo/labels

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "id": 208045946,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Something isn't working",
    "color": "f29513",
    "default": true
  },
  {
    "id": 208045947,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDc=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/enhancement",
    "name": "enhancement",
    "description": "New feature or request",
    "color": "a2eeef",
    "default": false
  }
]

Get a single label

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

GET /repos/:owner/:repo/labels/:name

Response

Status: 200 OK
{
  "id": 208045946,
  "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
  "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
  "name": "bug",
  "description": "Something isn't working",
  "color": "f29513",
  "default": true
}

Create a label

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

POST /repos/:owner/:repo/labels

Parameters

Name Type Description
name string Required. The name of the label. Emoji can be added to label names, using either native emoji or colon-style markup. For example, typing :strawberry: will render the emoji :strawberry:. For a full list of available emoji and codes, see emoji-cheat-sheet.com.
color string Required. The hexadecimal color code for the label, without the leading #.
description string A short description of the label.

Example

{
  "name": "bug",
  "description": "Something isn't working",
  "color": "f29513"
}

Response

Status: 201 Created
Location: https://api.github.com/repos/octocat/Hello-World/labels/bug
{
  "id": 208045946,
  "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
  "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
  "name": "bug",
  "description": "Something isn't working",
  "color": "f29513",
  "default": true
}

Update a label

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

PATCH /repos/:owner/:repo/labels/:current_name

Parameters

Name Type Description
name string The new name of the label. Emoji can be added to label names, using either native emoji or colon-style markup. For example, typing :strawberry: will render the emoji :strawberry:. For a full list of available emoji and codes, see emoji-cheat-sheet.com.
color string The hexadecimal color code for the label, without the leading #.
description string A short description of the label.

Example

{
  "name": "bug :bug:",
  "description": "Small bug fix required",
  "color": "b01f26"
}

Response

Status: 200 OK
{
  "id": 208045946,
  "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
  "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug%20:bug:",
  "name": "bug :bug:",
  "description": "Small bug fix required",
  "color": "b01f26",
  "default": true
}

Delete a label

DELETE /repos/:owner/:repo/labels/:name

Response

Status: 204 No Content

List labels on an issue

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

GET /repos/:owner/:repo/issues/:number/labels

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "id": 208045946,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Something isn't working",
    "color": "f29513",
    "default": true
  },
  {
    "id": 208045947,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDc=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/enhancement",
    "name": "enhancement",
    "description": "New feature or request",
    "color": "a2eeef",
    "default": false
  }
]

Add labels to an issue

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

POST /repos/:owner/:repo/issues/:number/labels

Parameters

Name Type Description
labels array of strings Required. The name of the label to add to the issue. Must contain at least one label. Note: Alternatively, you can pass a single label as a string or an array of labels directly, but GitHub recommends passing an object with the labels key.

Example

{
  "labels": ["bug", "enhancement"]
}

Response

Status: 200 OK
[
  {
    "id": 208045946,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Something isn't working",
    "color": "f29513",
    "default": true
  },
  {
    "id": 208045947,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDc=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/enhancement",
    "name": "enhancement",
    "description": "New feature or request",
    "color": "a2eeef",
    "default": false
  }
]

Remove a label from an issue

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

Removes the specified label from the issue, and returns the remaining labels on the issue.

DELETE /repos/:owner/:repo/issues/:number/labels/:name

Response if the label was removed successfully

Status: 200 OK
[
  {
    "id": 208045946,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Something isn't working",
    "color": "f29513",
    "default": true
  }
]

Response if the label does not exist

Status: 404 Not Found
{
  "message": "Label does not exist",
  "documentation_url": "https://developer.github.com/v3"
}

Replace all labels for an issue

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

PUT /repos/:owner/:repo/issues/:number/labels

Parameters

Name Type Description
labels array of strings The names of the labels to add to the issue. You can pass an empty array to remove all labels. Note: Alternatively, you can pass a single label as a string or an array of labels directly, but GitHub recommends passing an object with the labels key.

Example

{
  "labels": ["bug", "enhancement"]
}

Response

Status: 200 OK
[
  {
    "id": 208045946,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Something isn't working",
    "color": "f29513",
    "default": true
  },
  {
    "id": 208045947,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDc=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/enhancement",
    "name": "enhancement",
    "description": "New feature or request",
    "color": "a2eeef",
    "default": false
  }
]

Remove all labels from an issue

DELETE /repos/:owner/:repo/issues/:number/labels

Response

Status: 204 No Content

Get labels for every issue in a milestone

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support.

GET /repos/:owner/:repo/milestones/:number/labels

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "id": 208045946,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Something isn't working",
    "color": "f29513",
    "default": true
  },
  {
    "id": 208045947,
    "node_id": "MDU6TGFiZWwyMDgwNDU5NDc=",
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/enhancement",
    "name": "enhancement",
    "description": "New feature or request",
    "color": "a2eeef",
    "default": false
  }
]