GitHub v3 REST API

Get a check suite

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

Gets a single check suite using its id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check suites. OAuth Apps and authenticated users must have the repo scope to get check suites in a private repository.

get
http://HOSTNAME/api/v3/repos/{owner}/{repo}/check-suites/{check_suite_id}

Path Parameters

ownerstringrequired
repostringrequired
check_suite_idintegerrequired

check_suite_id parameter

Response

200 application/json

Response

CheckSuite

A suite of checks performed on the code of a given code change

idintegerrequired

Example:5

node_idstringrequired

Example:MDEwOkNoZWNrU3VpdGU1

head_branchstring | nullrequired

Example:master

head_shastringrequired

The SHA of the head commit that is being checked.

Example:009b8a3a9ccbb128af87f9b1c0f4c62e8a304f6d

statusstring | nullrequired

Allowed values:queuedin_progresscompleted

Example:completed

conclusionstring | nullrequired

Allowed values:successfailureneutralcancelledskippedtimed_outaction_required

Example:neutral

urlstring | nullrequired

Example:https://api.github.com/repos/github/hello-world/check-suites/5

beforestring | nullrequired

Example:146e867f55c26428e5f9fade55a9bbf5e95a7912

afterstring | nullrequired

Example:d6fde92930d4715a2b49857d24b940956b26d2d3

pull_requestsarray | null[object]required
Show Child Parameters
appobject | nullrequired

GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.

Show Child Parameters
repositoryobjectrequired

Minimal Repository

Show Child Parameters
created_atstring | null(date-time)required
updated_atstring | null(date-time)required
head_commitobjectrequired

Simple Commit

Show Child Parameters
latest_check_runs_countintegerrequired
check_runs_urlstringrequired
rerequestableboolean
runs_rerequestableboolean
get/repos/{owner}/{repo}/check-suites/{check_suite_id}
 
200 application/json

List check runs in a check suite

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

Lists check runs for a check suite using its id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the repo scope to get check runs in a private repository.

get
http://HOSTNAME/api/v3/repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs

Query Parameters

check_namestring

Returns check runs with the specified name.

statusstring

Returns check runs with the specified status. Can be one of queued, in_progress, or completed.

Allowed values:queuedin_progresscompleted

filterstring

Filters check runs by their completed_at timestamp. Can be one of latest (returning the most recent check runs) or all.

Allowed values:latestall

Default:latest

per_pageinteger

Results per page (max 100)

Default:30

pageinteger

Page number of the results to fetch.

Default:1

Path Parameters

ownerstringrequired
repostringrequired
check_suite_idintegerrequired

check_suite_id parameter

Response

200 application/json

Response

total_countintegerrequired
check_runsarray[object]required

A check performed on the code of a given code change

Show Child Parameters
get/repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs
 
200 application/json

Rerequest a check suite

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.

To rerequest a check suite, your GitHub App must have the checks:read permission on a private repository or pull access to a public repository.

post
http://HOSTNAME/api/v3/repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequest

Path Parameters

ownerstringrequired
repostringrequired
check_suite_idintegerrequired

check_suite_id parameter

Response

201 application/json

Response

object
* Additional properties are NOT allowed.
post/repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequest
 
201 application/json

List check runs for a Git reference

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

Lists check runs for a commit ref. The ref can be a SHA, branch name, or a tag name. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the repo scope to get check runs in a private repository.

get
http://HOSTNAME/api/v3/repos/{owner}/{repo}/commits/{ref}/check-runs

Query Parameters

check_namestring

Returns check runs with the specified name.

statusstring

Returns check runs with the specified status. Can be one of queued, in_progress, or completed.

Allowed values:queuedin_progresscompleted

filterstring

Filters check runs by their completed_at timestamp. Can be one of latest (returning the most recent check runs) or all.

Allowed values:latestall

Default:latest

per_pageinteger

Results per page (max 100)

Default:30

pageinteger

Page number of the results to fetch.

Default:1

app_idinteger

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Response

200 application/json

Response

total_countintegerrequired
check_runsarray[object]required

A check performed on the code of a given code change

Show Child Parameters
get/repos/{owner}/{repo}/commits/{ref}/check-runs
 
200 application/json

List check suites for a Git reference

Note: The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

Lists check suites for a commit ref. The ref can be a SHA, branch name, or a tag name. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to list check suites. OAuth Apps and authenticated users must have the repo scope to get check suites in a private repository.

get
http://HOSTNAME/api/v3/repos/{owner}/{repo}/commits/{ref}/check-suites

Query Parameters

app_idinteger

Filters check suites by GitHub App id.

Example:1

check_namestring

Returns check runs with the specified name.

per_pageinteger

Results per page (max 100)

Default:30

pageinteger

Page number of the results to fetch.

Default:1

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Response

200 application/json

Response

total_countintegerrequired
check_suitesarray[object]required

A suite of checks performed on the code of a given code change

Show Child Parameters
get/repos/{owner}/{repo}/commits/{ref}/check-suites
 
200 application/json