← All tags

Checks API Reference

Rich interactions with checks run by your integrations.

12 endpoints tagged checks, each listing its parameters and possible responses. Search or scroll the index below to jump to a specific endpoint.

No endpoints match your search.

Create a check run

POST /repos/{owner}/{repo}/check-runs

Creates a new check run for a specific commit in a repository.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
201	Response	yes

Get a check run

GET /repos/{owner}/{repo}/check-runs/{check_run_id}

Gets a single check run using its id.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`check_run_id`	path	yes	The unique identifier of the check run.

Responses

Status	Description	Has JSON body
200	Response	yes

Update a check run

PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}

Updates a check run for a specific commit in a repository.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`check_run_id`	path	yes	The unique identifier of the check run.

Responses

Status	Description	Has JSON body
200	Response	yes

List check run annotations

GET /repos/{owner}/{repo}/check-runs/{check_run_id}/annotations

Lists annotations for a check run using the annotation id.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`check_run_id`	path	yes	The unique identifier of the check run.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

Rerequest a check run

POST /repos/{owner}/{repo}/check-runs/{check_run_id}/rerequest

Triggers GitHub to rerequest an existing check run, without pushing new code to a repository. This endpoint will trigger the check_run webhook event with the action rerequested. When a check run is rerequested, the status of the check suite it belongs to is reset to queued and the conclusion is cleared. The check run itself is not updated. GitHub apps recieving the check_run webhook with the rerequested action should then decide if the check run should be reset or updated and call the update check_run endpoint to update the check_run if desired.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`check_run_id`	path	yes	The unique identifier of the check run.

Responses

Status	Description	Has JSON body
201	Response	yes
403	Forbidden if the check run is not rerequestable or doesn't belong to the authenticated GitHub App	yes
422	Validation error if the check run is not rerequestable	yes
404	Resource not found	yes

Create a check suite

POST /repos/{owner}/{repo}/check-suites

Creates a check suite manually. By default, check suites are automatically created when you create a check run. You only need to use this endpoint for manually creating check suites when you've disabled automatic creation using "Update repository preferences for check suites".

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
200	Response when the suite already exists	yes
201	Response when the suite was created	yes

Update repository preferences for check suites

PATCH /repos/{owner}/{repo}/check-suites/preferences

Changes the default automatic flow when creating check suites. By default, a check suite is automatically created each time code is pushed to a repository. When you disable the automatic creation of check suites, you can manually Create a check suite.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
200	Response	yes

Get a check suite

GET /repos/{owner}/{repo}/check-suites/{check_suite_id}

Gets a single check suite using its id.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`check_suite_id`	path	yes	The unique identifier of the check suite.

Responses

Status	Description	Has JSON body
200	Response	yes

List check runs in a check suite

GET /repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs

Lists check runs for a check suite using its id.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`check_suite_id`	path	yes	The unique identifier of the check suite.
`check_name`	query	no	Returns check runs with the specified `name`.
`status`	query	no	Returns check runs with the specified `status`.
`filter`	query	no	Filters check runs by their `completed_at` timestamp. `latest` returns the most recent check runs.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

Rerequest a check suite

POST /repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequest

Triggers GitHub to rerequest an existing check suite, without pushing new code to a repository. This endpoint will trigger the check_suite webhook event with the action rerequested. When a check suite is rerequested, its status is reset to queued and the conclusion is cleared.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`check_suite_id`	path	yes	The unique identifier of the check suite.

Responses

Status	Description	Has JSON body
201	Response	yes

List check runs for a Git reference

GET /repos/{owner}/{repo}/commits/{ref}/check-runs

Lists check runs for a commit ref. The ref can be a SHA, branch name, or a tag name.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`ref`	path	yes	The commit reference. Can be a commit SHA, branch name (`heads/BRANCH_NAME`), or tag name (`tags/TAG_NAME`). For more information, see "Git References" in the Git documentation.
`check_name`	query	no	Returns check runs with the specified `name`.
`status`	query	no	Returns check runs with the specified `status`.
`filter`	query	no	Filters check runs by their `completed_at` timestamp. `latest` returns the most recent check runs.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
`app_id`	query	no

Responses

Status	Description	Has JSON body
200	Response	yes

List check suites for a Git reference

GET /repos/{owner}/{repo}/commits/{ref}/check-suites

Lists check suites for a commit ref. The ref can be a SHA, branch name, or a tag name.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`ref`	path	yes	The commit reference. Can be a commit SHA, branch name (`heads/BRANCH_NAME`), or tag name (`tags/TAG_NAME`). For more information, see "Git References" in the Git documentation.
`app_id`	query	no	Filters check suites by GitHub App `id`.
`check_name`	query	no	Returns check runs with the specified `name`.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes