Labels

Note: To help with migrating from our REST API v3 to GraphQL API v4, we're introducing a preview period to include the GraphQL node_id in the response for many REST API v3 resources. See the blog post for full details. To access node_id during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.jean-grey-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.

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,
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Houston, we have a problem",
    "color": "f29513",
    "default": true
  }
]

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,
  "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
  "name": "bug",
  "description": "Houston, we have a problem",
  "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": "Houston, we have a problem",
  "color": "f29513"
}

Response

Status: 201 Created
Location: https://api.github.com/repos/octocat/Hello-World/labels/bug
{
  "id": 208045946,
  "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
  "name": "bug",
  "description": "Houston, we have a problem",
  "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,
  "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,
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Houston, we have a problem",
    "color": "f29513",
    "default": true
  }
]

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

Input

[
  "Label1",
  "Label2"
]

Response

Status: 200 OK
[
  {
    "id": 208045946,
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Houston, we have a problem",
    "color": "f29513",
    "default": true
  }
]

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.

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

Response if the label was removed successfully

Status: 200 OK
[
  {
    "id": 208045946,
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Houston, we have a problem",
    "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

Input

[
  "Label1",
  "Label2"
]

Sending an empty array ([]) will remove all Labels from the Issue.

Response

Status: 200 OK
[
  {
    "id": 208045946,
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Houston, we have a problem",
    "color": "f29513",
    "default": true
  }
]

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,
    "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
    "name": "bug",
    "description": "Houston, we have a problem",
    "color": "f29513",
    "default": true
  }
]