The GitHub Issues API lets you programmatically manage issue tracking on GitHub, enabling you to list and filter issues across repositories, create and edit issues, change their state (open/closed), and manage assignees, labels, and milestones. It supports adding, updating, and deleting comments; applying reactions; locking or unlocking conversations; and viewing issue events and timelines for auditing and automation.
openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Issues API
description: |-
Use the REST API to view and manage issues, including issue assignees,
comments, labels, and milestones.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
tags:
- name: Add
- name: All
- name: Assigned
- name: Assignees
- name: Checks
- name: Comment
- name: Comments
- name: Create
- name: Delete
- name: Events
- name: Get
- name: Issues
- name: Labels
- name: Lists
- name: Locks
- name: Reactions
- name: Remove
- name: Repositories
- name: Sets
- name: Timelines
- name: Unlock
- name: Update
- name: Users
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
paths:
/repos/{owner}/{repo}/issues/comments:
get:
summary: GitHub List Issue Comments for Repository
description: >-
You can use the REST API to list comments on issues and pull requests
for a repository. Every pull request is an issue, but not every issue is
a pull request.
By default, issue comments are ordered by ascending ID.
This endpoint supports the following custom media types. For more
information, see "[Media
types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types)."
- **`application/vnd.github.raw+json`**: Returns the raw markdown body.
Response will include `body`. This is the default if you do not pass any
specific media type.
- **`application/vnd.github.text+json`**: Returns a text only
representation of the markdown body. Response will include `body_text`.
- **`application/vnd.github.html+json`**: Returns HTML rendered from the
body's markdown. Response will include `body_html`.
- **`application/vnd.github.full+json`**: Returns raw, text, and HTML
representations. Response will include `body`, `body_text`, and
`body_html`.
tags:
- Comments
- Issues
- Lists
- Repositories
operationId: listIssueCommentsForRepository
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/comments#list-issue-comments-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/sort'
- name: direction
description: Either `asc` or `desc`. Ignored without the `sort` parameter.
in: query
required: false
schema:
type: string
enum:
- asc
- desc
example: asc
- $ref: '#/components/parameters/since'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/issue-comment'
examples:
default:
$ref: '#/components/examples/issue-comment-items'
headers:
Link:
$ref: '#/components/headers/link'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: comments
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-18'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/issues/comments/{comment_id}:
get:
summary: GitHub Get an Issue Comment
description: >-
You can use the REST API to get comments on issues and pull requests.
Every pull request is an issue, but not every issue is a pull request.
This endpoint supports the following custom media types. For more
information, see "[Media
types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types)."
- **`application/vnd.github.raw+json`**: Returns the raw markdown body.
Response will include `body`. This is the default if you do not pass any
specific media type.
- **`application/vnd.github.text+json`**: Returns a text only
representation of the markdown body. Response will include `body_text`.
- **`application/vnd.github.html+json`**: Returns HTML rendered from the
body's markdown. Response will include `body_html`.
- **`application/vnd.github.full+json`**: Returns raw, text, and HTML
representations. Response will include `body`, `body_text`, and
`body_html`.
tags:
- Comments
- Get
- Issues
operationId: getAnIssueComment
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/comments#get-an-issue-comment
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/issue-comment'
examples:
default:
$ref: '#/components/examples/issue-comment'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: comments
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-18'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update an Issue Comment
description: >-
You can use the REST API to update comments on issues and pull requests.
Every pull request is an issue, but not every issue is a pull request.
This endpoint supports the following custom media types. For more
information, see "[Media
types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types)."
- **`application/vnd.github.raw+json`**: Returns the raw markdown body.
Response will include `body`. This is the default if you do not pass any
specific media type.
- **`application/vnd.github.text+json`**: Returns a text only
representation of the markdown body. Response will include `body_text`.
- **`application/vnd.github.html+json`**: Returns HTML rendered from the
body's markdown. Response will include `body_html`.
- **`application/vnd.github.full+json`**: Returns raw, text, and HTML
representations. Response will include `body`, `body_text`, and
`body_html`.
tags:
- Comment
- Issues
- Update
operationId: updateAnIssueComment
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/comments#update-an-issue-comment
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
body:
type: string
description: The contents of the comment.
required:
- body
examples:
default:
value:
body: Me too
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/issue-comment'
examples:
default:
$ref: '#/components/examples/issue-comment'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: comments
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-18'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete an Issue Comment
description: >-
You can use the REST API to delete comments on issues and pull requests.
Every pull request is an issue, but not every issue is a pull request.
tags:
- Comments
- Delete
- Issues
operationId: deleteAnIssueComment
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/comments#delete-an-issue-comment
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: comments
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/issues/comments/{comment_id}/reactions:
get:
summary: GitHub List Reactions for an Issue Comment
description: >-
List the reactions to an [issue
comment](https://docs.github.com/[email protected]/rest/issues/comments#get-an-issue-comment).
tags:
- Comments
- Issues
- Lists
- Reactions
operationId: listReactionsForAnIssueComment
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/reactions/reactions#list-reactions-for-an-issue-comment
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- name: content
description: >-
Returns a single [reaction
type](https://docs.github.com/[email protected]/rest/reactions/reactions#about-reactions).
Omit this parameter to list all reactions to an issue comment.
in: query
required: false
schema:
type: string
enum:
- '+1'
- '-1'
- laugh
- confused
- heart
- hooray
- rocket
- eyes
example: '+1'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/reaction'
examples:
default:
$ref: '#/components/examples/reaction-items'
headers:
Link:
$ref: '#/components/headers/link'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: reactions
subcategory: reactions
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-18'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create Reaction for an Issue Comment
description: >-
Create a reaction to an [issue
comment](https://docs.github.com/[email protected]/rest/issues/comments#get-an-issue-comment).
A response with an HTTP `200` status means that you already added the
reaction type to this issue comment.
tags:
- Comments
- Create
- Issues
- Reactions
operationId: createReactionForAnIssueComment
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/reactions/reactions#create-reaction-for-an-issue-comment
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
content:
type: string
description: >-
The [reaction
type](https://docs.github.com/[email protected]/rest/reactions/reactions#about-reactions)
to add to the issue comment.
enum:
- '+1'
- '-1'
- laugh
- confused
- heart
- hooray
- rocket
- eyes
required:
- content
examples:
default:
value:
content: heart
responses:
'200':
description: Reaction exists
content:
application/json:
schema:
$ref: '#/components/schemas/reaction'
examples:
default:
$ref: '#/components/examples/reaction'
'201':
description: Reaction created
content:
application/json:
schema:
$ref: '#/components/schemas/reaction'
examples:
default:
$ref: '#/components/examples/reaction'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: reactions
subcategory: reactions
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-18'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/issues/comments/{comment_id}/reactions/{reaction_id}:
delete:
summary: GitHub Delete an Issue Comment Reaction
description: >-
**Note:** You can also specify a repository by `repository_id` using the
route `DELETE delete
/repositories/:repository_id/issues/comments/:comment_id/reactions/:reaction_id`.
Delete a reaction to an [issue
comment](https://docs.github.com/[email protected]/rest/issues/comments#get-an-issue-comment).
tags:
- Comments
- Delete
- Issues
- Reactions
operationId: deleteAnIssueCommentReaction
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/reactions/reactions#delete-an-issue-comment-reaction
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- $ref: '#/components/parameters/reaction-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: reactions
subcategory: reactions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/issues/events:
get:
summary: GitHub List Issue Events for Repository
description: >-
The List Issue Events For Repository endpoint retrieves a paginated list
of all issue events that have occurred within a specific repository.
This GET operation accepts the repository owner and repository name as
path parameters and returns event data such as when issues were opened,
closed, reopened, labeled, assigned, or had other state changes applied
to them. The endpoint supports pagination through query parameters and
requires appropriate authentication to access private repositories,
making it useful for tracking issue activity history, generating
analytics, or monitoring repository engagement patterns across all
issues rather than individual ones.
tags:
- Events
- Issues
- Lists
- Repositories
operationId: listIssueEventsForRepository
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/events#list-issue-events-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/issue-event'
examples:
default:
$ref: '#/components/examples/issue-event-items'
headers:
Link:
$ref: '#/components/headers/link'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: events
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-18'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/issues/events/{event_id}:
get:
summary: GitHub Get an Issue Event
description: >-
The GET /repos/{owner}/{repo}/issues/events/{event_id} endpoint
retrieves detailed information about a specific event associated with an
issue in a GitHub repository. This operation requires the repository
owner's username, the repository name, and the unique event identifier
to fetch data about actions performed on issues such as labels being
added or removed, assignments, milestone changes, comments, and state
transitions. The endpoint returns a comprehensive event object
containing metadata like the event type, actor who triggered the event,
creation timestamp, and relevant context specific to that event type,
making it useful for tracking the complete history and audit trail of
changes made to issues within a repository.
tags:
- Events
- Get
- Issues
operationId: getAnIssueEvent
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/events#get-an-issue-event
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- name: event_id
in: path
required: true
schema:
type: integer
example: 42
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/issue-event'
examples:
default:
$ref: '#/components/examples/issue-event'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'410':
$ref: '#/components/responses/gone'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: events
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-18'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/issues/{issue_number}:
get:
summary: GitHub Get an Issue
description: >-
The API returns a [`301 Moved Permanently`
status](https://docs.github.com/[email protected]/rest/guides/best-practices-for-using-the-rest-api#follow-redirects)
if the issue was
[transferred](https://docs.github.com/[email protected]/articles/transferring-an-issue-to-another-repository/)
to another repository. If
the issue was transferred to or deleted from a repository where the
authenticated user lacks read access, the API
returns a `404 Not Found` status. If the issue was deleted from a
repository where the authenticated user has read
access, the API returns a `410 Gone` status. To receive webhook events
for transferred and deleted issues, subscribe
to the
[`issues`](https://docs.github.com/[email protected]/webhooks/event-payloads/#issues)
webhook.
**Note**: GitHub's REST API considers every pull request an issue, but
not every issue is a pull request. For this
reason, "Issues" endpoints may return both issues and pull requests in
the response. You can identify pull requests by
the `pull_request` key. Be aware that the `id` of a pull request
returned from "Issues" endpoints will be an _issue id_. To find out the
pull
request id, use the "[List pull
requests](https://docs.github.com/[email protected]/rest/pulls/pulls#list-pull-requests)"
endpoint.
This endpoint supports the following custom media types. For more
information, see "[Media
types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types)."
- **`application/vnd.github.raw+json`**: Returns the raw markdown body.
Response will include `body`. This is the default if you do not pass any
specific media type.
- **`application/vnd.github.text+json`**: Returns a text only
representation of the markdown body. Response will include `body_text`.
- **`application/vnd.github.html+json`**: Returns HTML rendered from the
body's markdown. Response will include `body_html`.
- **`application/vnd.github.full+json`**: Returns raw, text, and HTML
representations. Response will include `body`, `body_text`, and
`body_html`.
tags:
- Get
- Issues
operationId: getAnIssue
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/issues#get-an-issue
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/issue-number'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/issue'
examples:
default:
$ref: '#/components/examples/issue'
'301':
$ref: '#/components/responses/moved_permanently'
'304':
$ref: '#/components/responses/not_modified'
'404':
$ref: '#/components/responses/not_found'
'410':
$ref: '#/components/responses/gone'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: issues
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-18'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update an Issue
description: >-
Issue owners and users with push access can edit an issue.
This endpoint supports the following custom media types. For more
information, see "[Media
types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types)."
- **`application/vnd.github.raw+json`**: Returns the raw markdown body.
Response will include `body`. This is the default if you do not pass any
specific media type.
- **`application/vnd.github.text+json`**: Returns a text only
representation of the markdown body. Response will include `body_text`.
- **`application/vnd.github.html+json`**: Returns HTML rendered from the
body's markdown. Response will include `body_html`.
- **`application/vnd.github.full+json`**: Returns raw, text, and HTML
representations. Response will include `body`, `body_text`, and
`body_html`.
tags:
- Issues
- Update
operationId: updateAnIssue
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/issues#update-an-issue
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/issue-number'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
title:
oneOf:
- type: string
- type: integer
description: The title of the issue.
nullable: true
body:
type: string
description: The contents of the issue.
nullable: true
assignee:
type: string
nullable: true
description: >-
Username to assign to this issue. **This field is
deprecated.**
state:
type: string
description: The open or closed state of the issue.
enum:
- open
- closed
state_reason:
type: string
enum:
- completed
- not_planned
- reopened
nullable: true
description: >-
The reason for the state change. Ignored unless `state` is
changed.
example: not_planned
milestone:
oneOf:
- type: string
- type: integer
description: >-
# --- truncated at 32 KB (6589 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-issues-api-openapi.yml