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 Application About Issues API
description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App
installations.'
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
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
tags:
- name: Issues
paths:
/repos/{owner}/{repo}/issues/events/{event_id}:
get:
summary: GitHub Get an Issue Event
description: The Get An Issue Event operation retrieves detailed information about a specific event that occurred on an issue within a GitHub repository. By providing the repository owner, repository name, and a unique event ID through the endpoint path parameters, this API returns comprehensive data about that particular issue event, such as when it was created, the type of event (like labeled, assigned, closed, etc.), the actor who triggered the event, and any associated metadata. This is useful for tracking the complete history and timeline of changes made to issues, enabling developers and project managers to audit issue activity, understand workflow patterns, and maintain detailed records of how issues evolved over time within their projects.
tags:
- Issues
operationId: getAnIssueEvent
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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
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
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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/enterprise-server@3.9/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
operationId: listIssueCommentsForRepository
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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
operationId: getAnIssueComment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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
operationId: updateAnIssueComment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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:
- Issues
operationId: deleteAnIssueComment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/rest/issues/comments#get-an-issue-comment).
tags:
- Issues
operationId: listReactionsForAnIssueComment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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/enterprise-server@3.9/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:
- Issues
operationId: createReactionForAnIssueComment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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/enterprise-server@3.9/rest/issues/comments#get-an-issue-comment).'
tags:
- Issues
operationId: deleteAnIssueCommentReaction
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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:
- Issues
operationId: listIssueEventsForRepository
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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/{issue_number}:
get:
summary: GitHub Get an Issue
description: 'The API returns a [`301 Moved Permanently` status](https://docs.github.com/enterprise-server@3.9/rest/guides/best-practices-for-using-the-rest-api#follow-redirects) if the issue was
[transferred](https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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/enterprise-server@3.9/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/enterprise-server@3.9/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
operationId: getAnIssue
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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
operationId: updateAnIssue
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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: The `number` of the milestone to associate this issue with or use `null` to remove the current milestone. Only users with push access can set the milestone for issues. Without push access to the repository, milestone changes are silently dropped.
nullable: true
labels:
type: array
description: Labels to associate with this issue. Pass one or more labels to _replace_ the set of labels on this issue. Send an empty array (`[]`) to clear all labels from the issue. Only users with push access can set labels for issues. Without push access to the repository, label changes are silently dropped.
items:
oneOf:
- type: string
- type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
nullable: true
color:
type: string
nullable: true
assignees:
type: array
description: Usernames to assign to this issue. Pass one or more user logins to _replace_ the set of assignees on this issue. Send an empty array (`[]`) to clear all assignees from the issue. Only users with push access can set assignees for new issues. Without push access to the repository, assignee changes are silently dropped.
items:
type: string
examples:
default:
value:
title: Found a bug
body: I'm having a problem with this.
assignees:
- octocat
milestone: 1
state: open
labels:
- bug
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/issue'
examples:
default:
$ref: '#/components/examples/issue'
'301':
$ref: '#/components/responses/moved_permanently'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
# --- truncated at 32 KB (903 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-issues-api-openapi.yml