REST API endpoints for check suites

Use the REST API to manage check suites.

Note

Write permission for the REST API to interact with checks is only available to GitHub Apps. OAuth apps and authenticated users can view check runs and check suites, but they are not able to create them. If you aren't building a GitHub App, you might be interested in using the REST API to interact with commit statuses.

Note

A GitHub App usually only receives one check_suite event per commit SHA, even if you push the commit SHA to more than one branch. To find out when a commit SHA is pushed to a branch, you can subscribe to branch create events.

Note

Most endpoints use Authorization: Bearer <YOUR-TOKEN> and Accept: application/vnd.github+json headers, plus X-GitHub-Api-Version: 2026-03-10. Curl examples below omit these standard headers for brevity.

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".
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.

OAuth apps and personal access tokens (classic) cannot use this endpoint.

Parameters

Headers

Path and query parameters

Body parameters

HTTP response status codes

Code examples

Example 1: Status Code 200

Request:

curl -L \
  -X POST \
  https://api.github.com/repos/OWNER/REPO/check-suites \
  -d '{
  "head_sha": "d6fde92930d4715a2b49857d24b940956b26d2d3"
}'

Response schema (Status: 200):

Example 2: Status Code 201

Request:

curl -L \
  -X POST \
  https://api.github.com/repos/OWNER/REPO/check-suites \
  -d '{
  "head_sha": "d6fde92930d4715a2b49857d24b940956b26d2d3"
}'

Response schema (Status: 201):

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.
You must have admin permissions in the repository to set preferences for check suites.

Parameters

Headers

Path and query parameters

Body parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X PATCH \
  https://api.github.com/repos/OWNER/REPO/check-suites/preferences \
  -d '{
  "auto_trigger_checks": [
    {
      "app_id": 4,
      "setting": false
    }
  ]
}'

Response schema (Status: 200):

Get a check suite

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

Gets a single check suite using its id.
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.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X GET \
  https://api.github.com/repos/OWNER/REPO/check-suites/CHECK_SUITE_ID

Response schema (Status: 200):

Same response schema as Create a check suite.

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

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X POST \
  https://api.github.com/repos/OWNER/REPO/check-suites/CHECK_SUITE_ID/rerequest

Response schema (Status: 201):

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.
Note

The endpoints to manage checks only look 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.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X GET \
  https://api.github.com/repos/OWNER/REPO/commits/REF/check-suites

Response schema (Status: 200):