GitHub Issues API (Portfolio Scope) (1.0.0)

Download OpenAPI specification:

License: MIT

Evidence-based OpenAPI 3.0.3 specification for a tested subset of the GitHub Issues REST API.

Scope:

Only the endpoints and behaviors documented in this file are in scope.
This is not GitHub's complete REST API surface.

Evidence approach:

Non-trivial behavioral claims include a "Verified in: Test #X" line that maps to the Postman test suite and evidence packets.

GitHub REST API documentation (official).

Issues

Repository issues (includes pull requests in list results).

List repository issues

List issues for a repository.

Default behavior:

Defaults to state=open when state is omitted.
Default per_page is 30.
Results may include pull requests.

Pagination:

Use per_page and page.

Verified in: Test #1, Test #2, Test #11, Test #12, Test #13

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.

query Parameters

per_page	integer Default: 30 Results per page. Behavior: Default: 30 when omitted. (Test #1) Maximum effective page size: 100. (Test #13) Values >100 are silently capped to 100. (Test #43) Values <=0 default to 30. (Test #44, Test #45)
page	integer >= 0 Default: 1 Page number of results to fetch. Behavior: Default: 1 when omitted. (Test #12) page=0 is treated as page 1. (Test #46) Very high page values may return 422. (Test #47)
state	string Default: "open" Enum: "open" "closed" "all" Filter issues by state. Defaults: If omitted, GitHub defaults to `open`. Verified in: Test #1, Test #2, Test #3, Test #4
labels	string Examples: labels=bug - labels=bug,extension - Filter issues by labels. Format: Comma-separated label names (for example: `bug,help wanted`). Behavior: Multiple labels use AND semantics (issue must have all specified labels). A non-existent label returns `200 OK` with an empty array. Verified in: Test #14, Test #15
assignee	string Examples: assignee=hoxyq - assignee=none - assignee=* - Filter issues by assignee. Accepted values: A username (for example: `octocat`). `none` for issues with no assignee. `*` for issues assigned to any user. Verified in: Test #16
creator	string Filter by the issue creator username. (Verified in: Test #17)
mentioned	string Filter by a user mentioned in the issue body or comments. (Verified in: Test #18)
sort	string Default: "created" Enum: "created" "updated" "comments" Examples: sort=created - Sort by creation date (newest first by default) sort=updated - Sort by last update (most recently updated first) sort=comments - Sort by comment count (most commented first) Sort issues. Allowed values: `created`, `updated`, `comments`. Fallback: If `sort` is invalid, GitHub falls back to `created`. Verified in: Test #17, Test #18, Test #19, Test #77
direction	string Default: "desc" Enum: "asc" "desc" Sort direction. Defaults: If omitted, GitHub defaults to `desc`. Verified in: Test #20, Test #21
since	string <date-time> Only issues updated at or after this time are returned. Observed in tests as ISO 8601 `date-time` (e.g., `2024-01-01T00:00:00Z`). (Verified in: Test #23)

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Responses

Response samples

200
401
403
404
422

Content type

application/json

Example

Default behavior (open issues, 30 results)

[{"number": 35400,
"title": "Example issue title",
"state": "open",
"labels": [ ],
"assignees": [ ],
"comments": 8,
"created_at": "2025-12-21T16:57:38Z",
"updated_at": "2025-12-21T17:20:22Z"
}
]

Create an issue

Create a new issue.

Required:

title is required.

Validation:

Missing title returns 422.

Empty arrays:

labels: [] is accepted and returned as labels: [].
assignees: [] is accepted and returned as assignees: [] with assignee: null.

Verified in: Test #6, Test #7, Test #37, Test #38, Test #54, Test #55

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Request Body schema: application/json
required

title required	string non-empty The title of the issue.
body	string Markdown-supported issue body.
labels	Array of strings Label names to apply. Observed: labels applied successfully when the caller has permission. (Verified in: Test #7) Observed: GitHub accepts `labels: []` during issue creation and returns `labels: []` in the created issue response. (Verified in: Test #54)
assignees	Array of strings Usernames to assign to this issue. Observed: assignees applied successfully when caller has permission. (Verified in: Test #7) Observed: GitHub accepts `assignees: []` during issue creation and returns `assignees: []` and `assignee: null` in the created issue response. (Verified in: Test #55)

Responses

Request samples

Payload

Content type

application/json

Example

Create issue minimal request

Minimal create request. Verified in: Test #6

{"title": "Test Issue"
}

Response samples

201
401
403
404
422

Content type

application/json

Minimal create response excerpt. Verified in: Test #6

{"number": 1,
"title": "Test Issue",
"state": "open",
"labels": [ ],
"assignees": [ ],
"assignee": null,
"body": null,
"created_at": "2025-12-12T05:42:46Z",
"updated_at": "2025-12-12T05:42:46Z",
"state_reason": null,
"comments": 0
}

Get an issue

Retrieve a single issue by number.

Notes:

Returns a JSON object (not an array).
Issue responses may include pull request metadata when the issue is a pull request.
The body representation fields depend on the Accept header (see Accept parameter).

Verified in: Test #5, Test #31, Test #32, Test #33, Test #34

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.
issue_number required	string^[0-9]+$ Example: 1 Issue number.

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Responses

Response samples

200
404

Content type

application/json

Example

Example issue (facebook/react

{"number": 1,
"title": "Run each test in its own <iframe>",
"state": "closed",
"body": "This is not blocking the initial launch...",
"created_at": "2013-05-29T20:20:53Z",
"updated_at": "2025-12-19T20:59:36Z",
"closed_at": "2013-06-03T17:58:02Z",
"pull_request": {"url": "https://api.github.com/repos/facebook/react/pulls/1"
},
"labels": [ ],
"assignees": [ ],
"comments": 5
}

Update an issue

Partially update an issue (PATCH semantics).

Common updates:

Update title only.
Close issue using state=closed with state_reason=completed or state_reason=not_planned.
Close issue using state=closed without state_reason returns state_reason=completed.
Reopen issue using state=open returns state_reason=reopened.

Empty arrays:

labels: [] clears labels.
assignees: [] clears assignees and sets assignee: null.

Validation:

Invalid state can return 422 validation errors.
Setting state_reason=reopened while closing (state=closed) returns 422.

Permissions:

Update attempts without sufficient repository permissions return 403 Forbidden.

Verified in: Test #8, Test #9, Test #41, Test #56, Test #57, Test #60, Test #61, Test #62, Test #63, Test #67, Test #79

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.
issue_number required	string^[0-9]+$ Example: 1 Issue number.

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Request Body schema: application/json
required

title	string New issue title.
body	string New issue body.
state	string Enum: "open" "closed" Issue state.
state_reason	string Enum: "completed" "not_planned" "reopened" Reason for closing or reopening an issue. Observed behavior: Closing with `state_reason=completed` or `state_reason=not_planned` is accepted. Reopening returns `state_reason=reopened`. Closing without a `state_reason` returns `state_reason=completed`. Validation: `state_reason=reopened` is invalid when closing (`state=closed`) and returns 422. Verified in: Test #60, Test #61, Test #62, Test #63, Test #79
labels	Array of strings Label names to set on the issue (replace semantics). Observed: Sending `labels: []` clears all labels; response returns `labels: []`. (Verified in: Test #75) Observed: Update attempts without sufficient repository permissions return 403 Forbidden (not a silent drop). (Verified in: Test #67)
assignees	Array of strings Usernames to assign to this issue (replace semantics). Observed: Sending `assignees: []` clears all assignees; response returns `assignees: []` and `assignee: null`. (Verified in: Test #76) Observed: Update attempts without sufficient repository permissions return 403 Forbidden. (Verified in: Test #67)

Responses

Request samples

Payload

Content type

application/json

Example

Update only the title

{"title": "Updated Title via API - Test #8"
}

Response samples

200
401
403
404
422

Content type

application/json

Example

Close issue with state_reason=completed (response)

Response excerpt after closing. Verified in: Test #60

{"number": 2,
"state": "closed",
"state_reason": "completed",
"closed_at": "2026-01-06T22:17:22Z",
"updated_at": "2026-01-06T22:17:22Z",
"title": "Test Issue - All Fields",
"labels": [ ],
"assignees": [ ],
"comments": 2,
"created_at": "2025-12-13T06:20:04Z"
}

IssueComments

Issue comments (list/create on an issue, and comment CRUD by id).

List comments on an issue

List comments for an issue.

Behavior:

Returns an array of comment objects.

Filters:

since filters by updated_at timestamp.

Pagination:

Use per_page and page.

Verified in: Test #10, Test #29, Test #30

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.
issue_number required	string^[0-9]+$ Example: 1 Issue number.

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Responses

Response samples

200
404

Content type

application/json

[{"id": 0,
"node_id": "string",
"url": "http://example.com",
"html_url": "http://example.com",
"issue_url": "http://example.com",
"reactions": { },
"performed_via_github_app": { },
"body": "string",
"user": {"login": "string",
"id": 0,
"html_url": "http://example.com",
"type": "string"
},
"author_association": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]

Create a comment on an issue

Create a comment on an issue.

Required:

body is required.

Validation:

Missing or empty body returns 422.

Verified in: Test #23, Test #24, Test #64

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.
issue_number required	string^[0-9]+$ Example: 1 Issue number.

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Request Body schema: application/json
required

body

required

string non-empty

The contents of the comment (Markdown supported).

Responses

Request samples

Payload

Content type

application/json

Example

Create a comment

{"body": "Thanks! Reproduced on the latest version."
}

Response samples

201
401
403
404
422

Content type

application/json

Basic create-comment response excerpt. Verified in: Test #26

{"id": 3673471450,
"body": "This is a test comment created via API.",
"created_at": "2025-12-19T04:51:40Z",
"updated_at": "2025-12-19T04:51:40Z",
"url": "https://api.github.com/repos/derrickscottux-collab/github-api-testing/issues/comments/3673471450",
"html_url": "https://github.com/derrickscottux-collab/github-api-testing/issues/2#issuecomment-3673471450",
"issue_url": "https://api.github.com/repos/derrickscottux-collab/github-api-testing/issues/2",
"user": {"login": "derrickscottux-collab",
"id": 243489198
}
}

Get an issue comment

Retrieve a single issue comment by comment ID.

Verified in: Test #25

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.
comment_id required	integer >= 1 Issue comment id.

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Responses

Response samples

200
404

Content type

application/json

{"id": 0,
"node_id": "string",
"url": "http://example.com",
"html_url": "http://example.com",
"issue_url": "http://example.com",
"reactions": { },
"performed_via_github_app": { },
"body": "string",
"user": {"login": "string",
"id": 0,
"html_url": "http://example.com",
"type": "string"
},
"author_association": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

Update an issue comment

Update an issue comment.

Required:

body is required.

Validation:

Missing or empty body returns 422.

Verified in: Test #26, Test #65

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.
comment_id required	integer >= 1 Issue comment id.

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Request Body schema: application/json
required

body

required

string non-empty

Updated comment body (Markdown supported).

Responses

Request samples

Payload

Content type

application/json

{"body": "string"
}

Response samples

200
401
403
404
422

Content type

application/json

{"id": 0,
"node_id": "string",
"url": "http://example.com",
"html_url": "http://example.com",
"issue_url": "http://example.com",
"reactions": { },
"performed_via_github_app": { },
"body": "string",
"user": {"login": "string",
"id": 0,
"html_url": "http://example.com",
"type": "string"
},
"author_association": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

Delete an issue comment

Delete an issue comment.

Observed:

Returns 204 No Content on success.

Verified in: Test #27

Authorizations:

GitHubToken

path Parameters

owner required	string Example: facebook Repository owner (organization or user).
repo required	string Example: react Repository name.
comment_id required	integer >= 1 Issue comment id.

header Parameters

Accept

string

Default: application/vnd.github+json

Example: application/vnd.github+json

Optional media type for GitHub REST API responses.

Tested variants:

application/vnd.github+json (default): returns body only.
application/vnd.github.text+json: returns body_text only.
application/vnd.github.html+json: returns body_html only.
application/vnd.github.full+json: returns body, body_text, and body_html.

Verified in: Test #31, Test #32, Test #33, Test #34

X-GitHub-Api-Version

string

Default: 2022-11-28

Example: 2022-11-28

Optional GitHub API version header.

Notes:

Tests used X-GitHub-Api-Version: 2022-11-28.
Responses also include x-github-api-version-selected indicating the selected version.

Verified in: Test #1

Responses

Response samples

401
403
404

Content type

application/json

{"message": "Requires authentication",
"documentation_url": "https://docs.github.com/rest",
"status": "401"
}

GitHub Issues API (Portfolio Scope) (1.0.0)

Issues

List repository issues

Authorizations:

path Parameters

query Parameters

header Parameters

Responses

Response samples

Create an issue

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get an issue

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Update an issue

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

IssueComments

List comments on an issue

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Create a comment on an issue

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get an issue comment

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Update an issue comment

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete an issue comment

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required