GitHub

GitHub Checks API

The GitHub Checks API lets you create and manage check runs and check suites that report detailed status, annotations, and results for commits. It enables CI/CD tools and integrations to report build and test results directly on pull requests with rich output including summaries, text, images, and per-line annotations.

GitHub OpenAPI
Business capability
Continuous Integration Management BC-4210.10

Operations 14

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /repos/{owner}/{repo}/check-runs Create a check run for a commit · Create a check run #
Ask an LLM
“How does my app report a CI result against a specific commit?”
“Can I create a check run that already has a conclusion and an output summary?”
Tell an agent
Create a check run named {name} on commit {head_sha} in {owner}/{repo}.
Start check {name} for commit {head_sha} in {owner}/{repo} with status {status}.
GET /repos/{owner}/{repo}/check-runs/{check_run_id} Get a check run · Get a check run #
Ask an LLM
“What's the status and conclusion of a specific check run?”
“Can I look up a single check run by its id?”
Tell an agent
Get check run {check_run_id} in {owner}/{repo}.
Show whether check run {check_run_id} in {owner}/{repo} passed or failed.
PATCH /repos/{owner}/{repo}/check-runs/{check_run_id} Update or complete a check run · Update a check run #
Ask an LLM
“How do I mark an in-progress check run as completed with a conclusion?”
“Can I add more output or action buttons to an existing check run?”
Tell an agent
Complete check run {check_run_id} in {owner}/{repo} with conclusion {conclusion}.
Set existing check run {check_run_id} in {owner}/{repo} to status {status}.
GET /repos/{owner}/{repo}/check-runs/{check_run_id}/annotations List annotations on a check run · List check run annotations #
Ask an LLM
“What line-level warnings or failures did a check run annotate?”
“Which files and lines were flagged by a particular check run?”
Tell an agent
List the annotations for check run {check_run_id} in {owner}/{repo}.
Show the flagged files and lines from check run {check_run_id} in {owner}/{repo}.
POST /repos/{owner}/{repo}/check-runs/{check_run_id}/rerequest Re-run a single check run · Rerequest a check run #
Ask an LLM
“Can I re-run one failed check without pushing new code?”
“What event fires when a single check run is re-requested?”
Tell an agent
Re-run check run {check_run_id} in {owner}/{repo}.
Rerequest only the single check run {check_run_id} on {owner}/{repo} without a new push.
POST /repos/{owner}/{repo}/check-suites Create a check suite manually · Create a check suite #
Ask an LLM
“When would I need to create a check suite by hand instead of letting it happen automatically?”
“Can I create a check suite for a commit after turning off automatic creation?”
Tell an agent
Create a check suite for commit {head_sha} in {owner}/{repo}.
Manually open a new check suite on {head_sha} in repository {owner}/{repo}.
PATCH /repos/{owner}/{repo}/check-suites/preferences Change automatic check suite creation for a repo · Update repository preferences for check suites #
Ask an LLM
“Can I stop check suites from being created automatically on every push?”
“How do I turn automatic check suite creation back on for an app in a repository?”
Tell an agent
Set the check suite auto-trigger preferences for {owner}/{repo} to {auto_trigger_checks}.
Turn off automatic check suite creation in {owner}/{repo} for the apps in {auto_trigger_checks}.
GET /repos/{owner}/{repo}/check-suites/{check_suite_id} Get a check suite · Get a check suite #
Ask an LLM
“What's the overall status and conclusion of a check suite?”
“Can I fetch one check suite by its id?”
Tell an agent
Get check suite {check_suite_id} in {owner}/{repo}.
Show the status and conclusion of check suite {check_suite_id} in {owner}/{repo}.
GET /repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs List the check runs in a check suite · List check runs in a check suite #
Ask an LLM
“Which check runs belong to a given check suite?”
“Can I filter a suite's check runs by name or status?”
Tell an agent
List the check runs in check suite {check_suite_id} of {owner}/{repo}.
Show {status} runs named {check_name} inside suite {check_suite_id} of {owner}/{repo}.
POST /repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequest Re-run an entire check suite · Rerequest a check suite #
Ask an LLM
“Can I re-run every check in a suite without pushing a new commit?”
“How do I retrigger a whole check suite after a flaky failure?”
Tell an agent
Re-run check suite {check_suite_id} in {owner}/{repo}.
Rerequest the whole suite {check_suite_id} on {owner}/{repo} without a new push.
GET /repos/{owner}/{repo}/commits/{ref}/check-runs List check runs for a commit, branch or tag · List check runs for a Git reference #
Ask an LLM
“Did all the checks pass on the latest commit of my branch?”
“Can I see check runs for a tag or branch name rather than a commit SHA?”
Tell an agent
List the check runs for {ref} in {owner}/{repo}.
Show {status} check runs named {check_name} on ref {ref} in {owner}/{repo}.
GET /repos/{owner}/{repo}/commits/{ref}/check-suites List check suites for a commit, branch or tag · List check suites for a Git reference #
Ask an LLM
“Which check suites ran against a given commit, branch or tag?”
“Can I narrow a ref's check suites down to one app?”
Tell an agent
List the check suites for {ref} in {owner}/{repo}.
Show check suites created by app {app_id} on ref {ref} in {owner}/{repo}.
GET /orgs/{org}/teams/{team_slug}/projects/{project_id} GitHub Check Team Permissions for Project #
GET /teams/{team_id}/projects/{project_id} GitHub Check Team Permissions for Project (legacy) #

Documentation

📖
Documentation
https://docs.github.com/en/rest/apps
📖
Documentation
https://docs.github.com/en/rest/codes-of-conduct/codes-of-conduct
📖
Documentation
https://docs.github.com/en/rest/emojis
📖
Documentation
https://docs.github.com/en/rest/gitignore
📖
Documentation
https://docs.github.com/en/rest/apps/installations
📖
Documentation
https://docs.github.com/en/rest/enterprise-admin
📖
Documentation
https://docs.github.com/en/rest/activity/events
📖
Documentation
https://docs.github.com/en/rest/orgs
📖
Documentation
https://docs.github.com/en/rest/rate-limit
📖
Documentation
https://docs.github.com/en/enterprise-cloud@latest/rest/scim
📖
Documentation
https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api
📖
Documentation
https://docs.github.com/en/rest/teams
📖
Documentation
https://docs.github.com/en/rest/meta/meta
📖
Documentation
https://docs.github.com/en/rest/actions
📖
Documentation
https://docs.github.com/en/rest/branches
📖
Documentation
https://docs.github.com/en/rest/code-scanning
📖
Documentation
https://docs.github.com/en/rest/collaborators
📖
Documentation
https://docs.github.com/en/rest/dependabot
📖
Documentation
https://docs.github.com/en/rest/webhooks
📖
Documentation
https://docs.github.com/en/rest/pulls
📖
Documentation
https://docs.github.com/en/rest/git/tags
📖
Documentation
https://docs.github.com/en/rest/repos/autolinks
📖
Documentation
https://docs.github.com/en/rest/collaborators/invitations
📖
Documentation
https://docs.github.com/en/rest/checks

Specifications

⚙
OpenAPI
https://artifacts.apis.io/github/openapi/github-checks-api-openapi.yml
⚙
AsyncAPI
https://artifacts.apis.io/github/asyncapi/github-webhooks-asyncapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/github/json-schema/github-check-run-schema.json
📊
JSONSchema
https://artifacts.apis.io/github/json-schema/github-check-suite-schema.json
📊
JSONSchema
https://artifacts.apis.io/github/json-schema/github-check-annotation-schema.json
📊
JSONSchema
https://artifacts.apis.io/github/json-schema/github-check-suite-preference-schema.json
📊
JSONSchema
https://artifacts.apis.io/github/json-schema/github-empty-object-schema.json

Other Resources

🔗
Reference
https://docs.github.com/en/webhooks/webhook-events-and-payloads

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/github:github-checks-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

github-checks-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Github Checks API
  version: 1.1.4
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  x-github-plan: api.github.com
  description: 'Operations tagged checks across 2 of this provider''s published API definitions: github-github-full.yml, github-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.github.com
tags:


# --- truncated at 32 KB (177 KB total) ---
# Full source: https://artifacts.apis.io/github/openapi/github-checks-api-openapi.yml