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

Operations 12

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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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 · GitHub 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}.

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://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-checks-api-openapi.yml
⚙
AsyncAPI
https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/asyncapi/github-webhooks-asyncapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/json-schema/github-check-run-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/json-schema/github-check-suite-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/json-schema/github-check-annotation-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/json-schema/github-check-suite-preference-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/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-checks-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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:
  version: 1.1.4
  title: GitHub v3 REST Checks API
  description: GitHub's v3 REST API.
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  x-github-plan: ghes
  x-github-release: 3.9
servers:
- url: '{protocol}://{hostname}/api/v3'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: HOSTNAME
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: http
tags:


# --- truncated at 32 KB (135 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-checks-api-openapi.yml