Labels - GitHub Docs

List labels for an issue

get /repos/{owner}/{repo}/issues/{issue_number}/labels

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`issue_number`	integer	path	issue_number parameter
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/labels

JavaScript @octokit/core.js

await octokit.request('GET /repos/{owner}/{repo}/issues/{issue_number}/labels', {
  owner: 'OWNER',
  repo: 'REPO',
  issue_number: 'ISSUE_NUMBER'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/labels

Response

Status: 200

[
  {
    "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
  }
]

Status codes

HTTP Status Code	Description
`200`	OK
`410`	Gone

Notes

Works with GitHub Apps

Add labels to an issue

post /repos/{owner}/{repo}/issues/{issue_number}/labels

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`issue_number`	integer	path	issue_number parameter
`labels`	array of strings	body	The names of the labels to add to the issue's existing labels. You can pass an empty array to remove all labels. 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. You can also replace all of the labels for an issue. For more information, see "Set labels for an issue."

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/labels \
  -d '{"labels":["bug","enhancement"]}'

JavaScript @octokit/core.js

await octokit.request('POST /repos/{owner}/{repo}/issues/{issue_number}/labels', {
  owner: 'OWNER',
  repo: 'REPO',
  issue_number: 'ISSUE_NUMBER',
  labels: [
    'bug',
    'enhancement'
  ]
})

Response

Status: 200

[
  {
    "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
  }
]

Status codes

HTTP Status Code	Description
`200`	OK
`410`	Gone
`422`	Validation failed

Notes

Works with GitHub Apps

Set labels for an issue

Removes any previous labels and sets the new labels for an issue.

put /repos/{owner}/{repo}/issues/{issue_number}/labels

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`issue_number`	integer	path	issue_number parameter
`labels`	array of strings	body	The names of the labels to set for the issue. The labels you set replace any existing labels. You can pass an empty array to remove all labels. 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. You can also add labels to the existing labels for an issue. For more information, see "Add labels to an issue."

Code samples

Example

Shell

curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/labels \
  -d '{"labels":["bug","enhancement"]}'

JavaScript @octokit/core.js

await octokit.request('PUT /repos/{owner}/{repo}/issues/{issue_number}/labels', {
  owner: 'OWNER',
  repo: 'REPO',
  issue_number: 'ISSUE_NUMBER',
  labels: [
    'bug',
    'enhancement'
  ]
})

Response

Status: 200

[
  {
    "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
  }
]

Status codes

HTTP Status Code	Description
`200`	OK
`410`	Gone
`422`	Validation failed

Notes

Works with GitHub Apps

Remove all labels from an issue

delete /repos/{owner}/{repo}/issues/{issue_number}/labels

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`issue_number`	integer	path	issue_number parameter

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/labels

JavaScript @octokit/core.js

await octokit.request('DELETE /repos/{owner}/{repo}/issues/{issue_number}/labels', {
  owner: 'OWNER',
  repo: 'REPO',
  issue_number: 'ISSUE_NUMBER'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/labels

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content
`410`	Gone

Notes

Works with GitHub Apps

Remove a label from an issue

Removes the specified label from the issue, and returns the remaining labels on the issue. This endpoint returns a 404 Not Found status if the label does not exist.

delete /repos/{owner}/{repo}/issues/{issue_number}/labels/{name}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`issue_number`	integer	path	issue_number parameter
`name`	string	path

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/labels/NAME

JavaScript @octokit/core.js

await octokit.request('DELETE /repos/{owner}/{repo}/issues/{issue_number}/labels/{name}', {
  owner: 'OWNER',
  repo: 'REPO',
  issue_number: 'ISSUE_NUMBER',
  name: 'NAME'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/labels/NAME

Response

Status: 200

[
  {
    "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
  }
]

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found
`410`	Gone

Notes

Works with GitHub Apps

List labels for a repository

get /repos/{owner}/{repo}/labels

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/labels

JavaScript @octokit/core.js

await octokit.request('GET /repos/{owner}/{repo}/labels', {
  owner: 'OWNER',
  repo: 'REPO'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/labels

Response

Status: 200

[
  {
    "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
  }
]

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found

Notes

Works with GitHub Apps

Create a label

post /repos/{owner}/{repo}/labels

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`name`	string	body	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 . For a full list of available emoji and codes, see "Emoji cheat sheet."
`color`	string	body	The hexadecimal color code for the label, without the leading `#`.
`description`	string	body	A short description of the label. Must be 100 characters or fewer.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/labels \
  -d '{"name":"bug","description":"Something isn't working","color":"f29513"}'

JavaScript @octokit/core.js

await octokit.request('POST /repos/{owner}/{repo}/labels', {
  owner: 'OWNER',
  repo: 'REPO',
  name: 'bug',
  description: 'Something isn\'t working',
  color: 'f29513'
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/labels \
  -f name='bug' -f description='Something isn't working' -f color='f29513'

Response

Status: 201

{
  "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
}

Status codes

HTTP Status Code	Description
`201`	Created
`404`	Resource not found
`422`	Validation failed

Notes

Works with GitHub Apps

Get a label

get /repos/{owner}/{repo}/labels/{name}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`name`	string	path

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/labels/NAME

JavaScript @octokit/core.js

await octokit.request('GET /repos/{owner}/{repo}/labels/{name}', {
  owner: 'OWNER',
  repo: 'REPO',
  name: 'NAME'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/labels/NAME

Response

Status: 200

{
  "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
}

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found

Notes

Works with GitHub Apps

Update a label

patch /repos/{owner}/{repo}/labels/{name}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`name`	string	path
`new_name`	string	body	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 . For a full list of available emoji and codes, see "Emoji cheat sheet."
`color`	string	body	The hexadecimal color code for the label, without the leading `#`.
`description`	string	body	A short description of the label. Must be 100 characters or fewer.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/labels/NAME \
  -d '{"new_name":"bug :bug:","description":"Small bug fix required","color":"b01f26"}'

JavaScript @octokit/core.js

await octokit.request('PATCH /repos/{owner}/{repo}/labels/{name}', {
  owner: 'OWNER',
  repo: 'REPO',
  name: 'NAME',
  new_name: 'bug :bug:',
  description: 'Small bug fix required',
  color: 'b01f26'
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/labels/NAME \
  -f new_name='bug :bug:' -f description='Small bug fix required' -f color='b01f26'

Response

Status: 200

{
  "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
}

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

Delete a label

delete /repos/{owner}/{repo}/labels/{name}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`name`	string	path

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/labels/NAME

JavaScript @octokit/core.js

await octokit.request('DELETE /repos/{owner}/{repo}/labels/{name}', {
  owner: 'OWNER',
  repo: 'REPO',
  name: 'NAME'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/labels/NAME

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

Notes

Works with GitHub Apps

List labels for issues in a milestone

get /repos/{owner}/{repo}/milestones/{milestone_number}/labels

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`milestone_number`	integer	path	milestone_number parameter
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/milestones/MILESTONE_NUMBER/labels

JavaScript @octokit/core.js

await octokit.request('GET /repos/{owner}/{repo}/milestones/{milestone_number}/labels', {
  owner: 'OWNER',
  repo: 'REPO',
  milestone_number: 'MILESTONE_NUMBER'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/milestones/MILESTONE_NUMBER/labels

Response

Status: 200

[
  {
    "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
  }
]

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps