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.2.0
info:
title: Github Issues API
version: 1.1.4
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
description: 'Operations tagged Issues across 4 of this provider''s published API definitions: github-openapi.yml, github-organizations-openapi.yml, github-repo-issues-api-openapi.yml, github-repo-tags-api-openapi.yml. Each path carries the servers of the definition it was published in.'
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
- url: '{protocol}://{hostname}'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
tags:
- name: Issues
description: Interact with GitHub Issues.
paths:
/issues:
get:
summary: GitHub List Issues Assigned to the Authenticated User
description: 'List issues assigned to the authenticated user across all visible repositories including owned repositories, member
repositories, and organization repositories. You can use the `filter` query parameter to fetch issues that are not
necessarily assigned to you.
**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: issues/list
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/issues/issues#list-issues-assigned-to-the-authenticated-user
parameters:
- name: filter
description: Indicates which sorts of issues to return. `assigned` means issues assigned to you. `created` means issues created by you. `mentioned` means issues mentioning you. `subscribed` means issues you're subscribed to updates for. `all` or `repos` means all issues you can see, regardless of participation or creation.
in: query
required: false
schema:
type: string
enum:
- assigned
- created
- mentioned
- subscribed
- repos
- all
default: assigned
example: assigned
- name: state
description: Indicates the state of the issues to return.
in: query
required: false
schema:
type: string
enum:
- open
- closed
- all
default: open
example: open
- $ref: '#/components/parameters/labels'
- name: sort
description: What to sort results by.
in: query
required: false
schema:
type: string
enum:
- created
- updated
- comments
default: created
example: created
- $ref: '#/components/parameters/direction'
- $ref: '#/components/parameters/since'
- name: collab
in: query
required: false
schema:
type: boolean
example: true
- name: orgs
in: query
required: false
schema:
type: boolean
example: true
- name: owned
in: query
required: false
schema:
type: boolean
example: true
- name: pulls
in: query
required: false
schema:
type: boolean
example: true
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/issue'
examples:
default:
$ref: '#/components/examples/issue-with-repo-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: issues
subcategory: issues
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
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
/orgs/{org}/issues:
get:
summary: GitHub List Organization Issues Assigned to the Authenticated User
description: 'List issues in an organization assigned to the authenticated user.
**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: issues/list-for-org
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/issues/issues#list-organization-issues-assigned-to-the-authenticated-user
parameters:
- $ref: '#/components/parameters/org'
- name: filter
description: Indicates which sorts of issues to return. `assigned` means issues assigned to you. `created` means issues created by you. `mentioned` means issues mentioning you. `subscribed` means issues you're subscribed to updates for. `all` or `repos` means all issues you can see, regardless of participation or creation.
in: query
required: false
schema:
type: string
enum:
- assigned
- created
- mentioned
- subscribed
- repos
- all
default: assigned
example: assigned
- name: state
description: Indicates the state of the issues to return.
in: query
required: false
schema:
type: string
enum:
- open
- closed
- all
default: open
example: open
- $ref: '#/components/parameters/labels'
- name: sort
description: What to sort results by.
in: query
required: false
schema:
type: string
enum:
- created
- updated
- comments
default: created
example: created
- $ref: '#/components/parameters/direction'
- $ref: '#/components/parameters/since'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/issue'
examples:
default:
$ref: '#/components/examples/issue-with-repo-items'
headers:
Link:
$ref: '#/components/headers/link'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: issues
subcategory: issues
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
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
/repos/{owner}/{repo}/assignees:
get:
summary: GitHub List Assignees
description: Lists the [available assignees](https://docs.github.com/enterprise-server@3.9/articles/assigning-issues-and-pull-requests-to-other-github-users/) for issues in a repository.
tags:
- Issues
operationId: issues/list-assignees
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/issues/assignees#list-assignees
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
headers:
Link:
$ref: '#/components/headers/link'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: assignees
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
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
/repos/{owner}/{repo}/assignees/{assignee}:
get:
summary: GitHub Check if a User Can Be Assigned
description: 'Checks if a user has permission to be assigned to an issue in this repository.
If the `assignee` can be assigned to issues in the repository, a `204` header with no content is returned.
Otherwise a `404` status code is returned.'
tags:
- Issues
operationId: issues/check-user-can-be-assigned
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/issues/assignees#check-if-a-user-can-be-assigned
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- name: assignee
in: path
required: true
schema:
type: string
example: example_value
responses:
'204':
description: If the `assignee` can be assigned to issues in the repository, a `204` header with no content is returned.
'404':
description: Otherwise a `404` status code is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/basic-error'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: assignees
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
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
/repos/{owner}/{repo}/issues:
get:
summary: GitHub List Repository Issues
description: 'List issues in a repository. Only open issues will be listed.
**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: issues/list-for-repo
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/issues/issues#list-repository-issues
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- name: milestone
description: If an `integer` is passed, it should refer to a milestone by its `number` field. If the string `*` is passed, issues with any milestone are accepted. If the string `none` is passed, issues without milestones are returned.
in: query
required: false
schema:
type: string
example: example_value
- name: state
description: Indicates the state of the issues to return.
in: query
required: false
schema:
type: string
enum:
- open
- closed
- all
default: open
example: open
- name: assignee
description: Can be the name of a user. Pass in `none` for issues with no assigned user, and `*` for issues assigned to any user.
in: query
required: false
schema:
type: string
example: example_value
- name: creator
description: The user that created the issue.
in: query
required: false
schema:
type: string
example: example_value
- name: mentioned
description: A user that's mentioned in the issue.
in: query
required: false
schema:
type: string
example: example_value
- $ref: '#/components/parameters/labels'
- name: sort
description: What to sort results by.
in: query
required: false
schema:
type: string
enum:
- created
- updated
- comments
default: created
example: created
- $ref: '#/components/parameters/direction'
- $ref: '#/components/parameters/since'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/issue'
examples:
default:
$ref: '#/components/examples/issue-items'
headers:
Link:
$ref: '#/components/headers/link'
'301':
$ref: '#/components/responses/moved_permanently'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: issues
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create an Issue
description: 'Any user with pull access to a repository can create an issue. If [issues are disabled in the repository](https://docs.github.com/enterprise-server@3.9/articles/disabling-issues/), the API returns a `410 Gone` status.
This endpoint triggers [notifications](https://docs.github.com/enterprise-server@3.9/github/managing-subscriptions-and-notifications-on-github/about-notifications). Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/enterprise-server@3.9/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits)"
and "[Best practices for using the REST API](https://docs.github.com/enterprise-server@3.9/rest/guides/best-practices-for-using-the-rest-api)."
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: issues/create
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/issues/issues#create-an-issue
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
oneOf:
- type: string
- type: integer
description: The title of the issue.
body:
type: string
description: The contents of the issue.
assignee:
type:
- string
- 'null'
description: 'Login for the user that this issue should be assigned to. _NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise. **This field is deprecated.**_'
milestone:
oneOf:
- type: string
- type: integer
description: 'The `number` of the milestone to associate this issue with. _NOTE: Only users with push access can set the milestone for new issues. The milestone is silently dropped otherwise._'
labels:
type: array
description: 'Labels to associate with this issue. _NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise._'
items:
oneOf:
- type: string
- type: object
properties:
id:
type: integer
name:
type: string
description:
type:
- string
- 'null'
color:
type:
- string
- 'null'
assignees:
type: array
description: 'Logins for Users to assign to this issue. _NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise._'
items:
type: string
required:
- title
examples:
default:
value:
title: Found a bug
body: I'm having a problem with this.
assignees:
- octocat
milestone: 1
labels:
- bug
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/issue'
examples:
default:
$ref: '#/components/examples/issue'
headers:
Location:
example: https://api.github.com/repos/octocat/Hello-World/issues/1347
schema:
type: string
'400':
$ref: '#/components/responses/bad_request'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'410':
$ref: '#/components/responses/gone'
'422':
$ref: '#/components/responses/validation_failed'
'503':
$ref: '#/components/responses/service_unavailable'
x-github:
triggersNotification: true
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: issues
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
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
/repos/{owner}/{repo}/issues/comments:
get:
summary: GitHub List Issue Comments for a 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: issues/list-comments-for-repo
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'
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-microcks-operation:
delay: 0
dispatcher: FALLBACK
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
/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: issues/get-comment
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'
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-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: issues/update-comment
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'
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-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: issues/delete-comment
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'
- $r
# --- truncated at 32 KB (417 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-issues-api-openapi.yml