@octokit/openapi

{ "openapi": "3.0.3", "info": { "version": "21.0.0", "title": "GitHub's official OpenAPI spec + Octokit extension", "description": "OpenAPI specs from https://github.com/github/rest-api-description with the 'x-octokit' extension required by the Octokit SDKs", "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" }, "termsOfService": "https://docs.github.com/articles/github-terms-of-service", "contact": { "name": "Support", "url": "https://github.com/octokit/openapi" }, "x-github-plan": "api.github.com" }, "tags": [ { "name": "actions", "description": "Endpoints to manage GitHub Actions using the REST API." }, { "name": "activity", "description": "Activity APIs provide access to notifications, subscriptions, and timelines." }, { "name": "apps", "description": "Information for integrations and installations." }, { "name": "billing", "description": "Monitor charges and usage from Actions and Packages." }, { "name": "checks", "description": "Rich interactions with checks run by your integrations." }, { "name": "code-scanning", "description": "Retrieve code scanning alerts from a repository." }, { "name": "codes-of-conduct", "description": "Insight into codes of conduct for your communities." }, { "name": "emojis", "description": "List emojis available to use on GitHub." }, { "name": "dependabot", "description": "Endpoints to manage Dependabot." }, { "name": "dependency-graph", "description": "Endpoints to access Dependency Graph features." }, { "name": "gists", "description": "View, modify your gists." }, { "name": "git", "description": "Raw Git functionality." }, { "name": "gitignore", "description": "View gitignore templates" }, { "name": "issues", "description": "Interact with GitHub Issues." }, { "name": "licenses", "description": "View various OSS licenses." }, { "name": "markdown", "description": "Render GitHub flavored markdown" }, { "name": "merge-queue", "description": "Interact with GitHub Merge Queues." }, { "name": "meta", "description": "Endpoints that give information about the API." }, { "name": "migrations", "description": "Move projects to or from GitHub." }, { "name": "oidc", "description": "Endpoints to manage GitHub OIDC configuration using the REST API." }, { "name": "orgs", "description": "Interact with GitHub Orgs." }, { "name": "packages", "description": "Manage packages for authenticated users and organizations." }, { "name": "projects-classic", "description": "Interact with GitHub Projects (classic)." }, { "name": "pulls", "description": "Interact with GitHub Pull Requests." }, { "name": "rate-limit", "description": "Check your current rate limit status" }, { "name": "reactions", "description": "Interact with reactions to various GitHub entities." }, { "name": "repos", "description": "Interact with GitHub Repos." }, { "name": "search", "description": "Look for stuff on GitHub." }, { "name": "secret-scanning", "description": "Retrieve secret scanning alerts from a repository." }, { "name": "teams", "description": "Interact with GitHub Teams." }, { "name": "users", "description": "Interact with and view information about users and also current user." }, { "name": "codespaces", "description": "Endpoints to manage Codespaces using the REST API." }, { "name": "copilot", "description": "Endpoints to manage Copilot using the REST API." }, { "name": "security-advisories", "description": "Manage security advisories." }, { "name": "interactions", "description": "Owner or admin management of users interactions." }, { "name": "classroom", "description": "Interact with GitHub Classroom." }, { "name": "desktop", "description": "Desktop specific endpoints." }, { "name": "enterprise-teams", "description": "Endpoints to manage GitHub Enterprise Teams." }, { "name": "enterprise-team-memberships", "description": "Endpoints to manage GitHub Enterprise Team memberships." }, { "name": "enterprise-team-organizations", "description": "Endpoints to manage GitHub Enterprise Team organization assignments." }, { "name": "code-security", "description": "Endpoints to manage Code security using the REST API." }, { "name": "private-registries", "description": "Manage private registry configurations." }, { "name": "hosted-compute", "description": "Manage hosted compute networking resources." }, { "name": "credentials", "description": "Revoke compromised or leaked GitHub credentials." }, { "name": "campaigns", "description": "Endpoints to manage campaigns via the REST API." }, { "name": "projects", "description": "Endpoints to manage Projects using the REST API." } ], "servers": [ { "url": "https://api.github.com" } ], "externalDocs": { "description": "GitHub v3 REST API", "url": "https://docs.github.com/rest/" }, "paths": { "/": { "get": { "summary": "GitHub API Root", "description": "Get Hypermedia links to resources accessible in GitHub's REST API", "tags": [ "meta" ], "operationId": "meta/root", "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_user_url": { "type": "string", "format": "uri-template" }, "current_user_authorizations_html_url": { "type": "string", "format": "uri-template" }, "authorizations_url": { "type": "string", "format": "uri-template" }, "code_search_url": { "type": "string", "format": "uri-template" }, "commit_search_url": { "type": "string", "format": "uri-template" }, "emails_url": { "type": "string", "format": "uri-template" }, "emojis_url": { "type": "string", "format": "uri-template" }, "events_url": { "type": "string", "format": "uri-template" }, "feeds_url": { "type": "string", "format": "uri-template" }, "followers_url": { "type": "string", "format": "uri-template" }, "following_url": { "type": "string", "format": "uri-template" }, "gists_url": { "type": "string", "format": "uri-template" }, "hub_url": { "type": "string", "format": "uri-template", "deprecated": true }, "issue_search_url": { "type": "string", "format": "uri-template" }, "issues_url": { "type": "string", "format": "uri-template" }, "keys_url": { "type": "string", "format": "uri-template" }, "label_search_url": { "type": "string", "format": "uri-template" }, "notifications_url": { "type": "string", "format": "uri-template" }, "organization_url": { "type": "string", "format": "uri-template" }, "organization_repositories_url": { "type": "string", "format": "uri-template" }, "organization_teams_url": { "type": "string", "format": "uri-template" }, "public_gists_url": { "type": "string", "format": "uri-template" }, "rate_limit_url": { "type": "string", "format": "uri-template" }, "repository_url": { "type": "string", "format": "uri-template" }, "repository_search_url": { "type": "string", "format": "uri-template" }, "current_user_repositories_url": { "type": "string", "format": "uri-template" }, "starred_url": { "type": "string", "format": "uri-template" }, "starred_gists_url": { "type": "string", "format": "uri-template" }, "topic_search_url": { "type": "string", "format": "uri-template" }, "user_url": { "type": "string", "format": "uri-template" }, "user_organizations_url": { "type": "string", "format": "uri-template" }, "user_repositories_url": { "type": "string", "format": "uri-template" }, "user_search_url": { "type": "string", "format": "uri-template" } }, "required": [ "current_user_url", "current_user_authorizations_html_url", "authorizations_url", "code_search_url", "commit_search_url", "emails_url", "emojis_url", "events_url", "feeds_url", "followers_url", "following_url", "gists_url", "issue_search_url", "issues_url", "keys_url", "label_search_url", "notifications_url", "organization_url", "organization_repositories_url", "organization_teams_url", "public_gists_url", "rate_limit_url", "repository_url", "repository_search_url", "current_user_repositories_url", "starred_url", "starred_gists_url", "user_url", "user_organizations_url", "user_repositories_url", "user_search_url" ] }, "examples": { "default": { "value": { "current_user_url": "https://api.github.com/user", "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}", "authorizations_url": "https://api.github.com/authorizations", "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}", "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}", "emails_url": "https://api.github.com/user/emails", "emojis_url": "https://api.github.com/emojis", "events_url": "https://api.github.com/events", "feeds_url": "https://api.github.com/feeds", "followers_url": "https://api.github.com/user/followers", "following_url": "https://api.github.com/user/following{/target}", "gists_url": "https://api.github.com/gists{/gist_id}", "hub_url": "https://api.github.com/hub", "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}", "issues_url": "https://api.github.com/issues", "keys_url": "https://api.github.com/user/keys", "label_search_url": "https://api.github.com/search/labels?q={query}&repository_id={repository_id}{&page,per_page}", "notifications_url": "https://api.github.com/notifications", "organization_url": "https://api.github.com/orgs/{org}", "organization_repositories_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}", "organization_teams_url": "https://api.github.com/orgs/{org}/teams", "public_gists_url": "https://api.github.com/gists/public", "rate_limit_url": "https://api.github.com/rate_limit", "repository_url": "https://api.github.com/repos/{owner}/{repo}", "repository_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}", "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}", "starred_url": "https://api.github.com/user/starred{/owner}{/repo}", "starred_gists_url": "https://api.github.com/gists/starred", "topic_search_url": "https://api.github.com/search/topics?q={query}{&page,per_page}", "user_url": "https://api.github.com/users/{user}", "user_organizations_url": "https://api.github.com/user/orgs", "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}", "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}" } } } } } } }, "x-github": { "githubCloudOnly": false, "enabledForGitHubApps": true, "category": "meta", "subcategory": "meta" }, "externalDocs": { "description": "API method documentation", "url": "https://docs.github.com/rest/meta/meta#github-api-root" }, "x-octokit": {} } }, "/advisories": { "get": { "summary": "List global security advisories", "description": "Lists all global security advisories that match the specified parameters. If no other parameters are defined, the request will return only GitHub-reviewed advisories that are not malware.\n\nBy default, all responses will exclude advisories for malware, because malware are not standard vulnerabilities. To list advisories for malware, you must include the `type` parameter in your request, with the value `malware`. For more information about the different types of security advisories, see \"[About the GitHub Advisory database](https://docs.github.com/code-security/security-advisories/global-security-advisories/about-the-github-advisory-database#about-types-of-security-advisories).\"", "tags": [ "security-advisories" ], "operationId": "security-advisories/list-global-advisories", "externalDocs": { "description": "API method documentation", "url": "https://docs.github.com/rest/security-advisories/global-advisories#list-global-security-advisories" }, "parameters": [ { "name": "ghsa_id", "in": "query", "description": "If specified, only advisories with this GHSA (GitHub Security Advisory) identifier will be returned.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "If specified, only advisories of this type will be returned. By default, a request with no other parameters defined will only return reviewed advisories that are not malware.", "schema": { "type": "string", "enum": [ "reviewed", "malware", "unreviewed" ], "default": "reviewed" } }, { "name": "cve_id", "description": "If specified, only advisories with this CVE (Common Vulnerabilities and Exposures) identifier will be returned.", "in": "query", "schema": { "type": "string" } }, { "name": "ecosystem", "in": "query", "description": "If specified, only advisories for these ecosystems will be returned.", "schema": { "type": "string", "description": "The package's language or package management ecosystem.", "enum": [ "rubygems", "npm", "pip", "maven", "nuget", "composer", "go", "rust", "erlang", "actions", "pub", "other", "swift" ] } }, { "name": "severity", "in": "query", "description": "If specified, only advisories with these severities will be returned.", "schema": { "type": "string", "enum": [ "unknown", "low", "medium", "high", "critical" ] } }, { "name": "cwes", "in": "query", "description": "If specified, only advisories with these Common Weakness Enumerations (CWEs) will be returned.\n\nExample: `cwes=79,284,22` or `cwes[]=79&cwes[]=284&cwes[]=22`", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, { "name": "is_withdrawn", "in": "query", "description": "Whether to only return advisories that have been withdrawn.", "schema": { "type": "boolean" } }, { "name": "affects", "in": "query", "description": "If specified, only return advisories that affect any of `package` or `package@version`. A maximum of 1000 packages can be specified.\nIf the query parameter causes the URL to exceed the maximum URL length supported by your client, you must specify fewer packages.\n\nExample: `affects=package1,package2@1.0.0,package3@2.0.0` or `affects[]=package1&affects[]=package2@1.0.0`", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "maxItems": 1000, "items": { "type": "string" } } ] } }, { "name": "published", "in": "query", "description": "If specified, only return advisories that were published on a date or date range.\n\nFor more information on the syntax of the date range, see \"[Understanding the search syntax](https://docs.github.com/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates).\"", "schema": { "type": "string" } }, { "name": "updated", "in": "query", "description": "If specified, only return advisories that were updated on a date or date range.\n\nFor more information on the syntax of the date range, see \"[Understanding the search syntax](https://docs.github.com/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates).\"", "schema": { "type": "string" } }, { "name": "modified", "description": "If specified, only show advisories that were updated or published on a date or date range.\n\nFor more information on the syntax of the date range, see \"[Understanding the search syntax](https://docs.github.com/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates).\"", "in": "query", "schema": { "type": "string" } }, { "name": "epss_percentage", "in": "query", "description": "If specified, only return advisories that have an EPSS percentage score that matches the provided value.\nThe EPSS percentage represents the likelihood of a CVE being exploited.", "schema": { "type": "string" } }, { "name": "epss_percentile", "in": "query", "description": "If specified, only return advisories that have an EPSS percentile score that matches the provided value.\nThe EPSS percentile represents the relative rank of the CVE's likelihood of being exploited compared to other CVEs.", "schema": { "type": "string" } }, { "name": "before", "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "after", "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "description": "The direction to sort the results by.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "per_page", "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "sort", "description": "The property to sort the results by.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "updated", "published", "epss_percentage", "epss_percentile" ], "default": "published" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "array", "items": { "description": "A GitHub Security Advisory.", "type": "object", "properties": { "ghsa_id": { "type": "string", "description": "The GitHub Security Advisory ID.", "readOnly": true }, "cve_id": { "type": "string", "description": "The Common Vulnerabilities and Exposures (CVE) ID.", "nullable": true, "readOnly": true }, "url": { "type": "string", "description": "The API URL for the advisory.", "readOnly": true }, "html_url": { "type": "string", "format": "uri", "description": "The URL for the advisory.", "readOnly": true }, "repository_advisory_url": { "type": "string", "format": "uri", "description": "The API URL for the repository advisory.", "readOnly": true, "nullable": true }, "summary": { "type": "string", "description": "A short summary of the advisory.", "maxLength": 1024 }, "description": { "type": "string", "description": "A detailed description of what the advisory entails.", "maxLength": 65535, "nullable": true }, "type": { "type": "string", "description": "The type of advisory.", "readOnly": true, "enum": [ "reviewed", "unreviewed", "malware" ] }, "severity": { "type": "string", "description": "The severity of the advisory.", "enum": [ "critical", "high", "medium", "low", "unknown" ] }, "source_code_location": { "type": "string", "format": "uri", "description": "The URL of the advisory's source code.", "nullable": true }, "identifiers": { "type": "array", "nullable": true, "readOnly": true, "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of identifier.", "enum": [ "CVE", "GHSA" ] }, "value": { "type": "string", "description": "The identifier value." } }, "required": [ "type", "value" ] } }, "references": { "type": "array", "nullable": true, "items": { "type": "string", "description": "URLs with more information regarding the advisory." } }, "published_at": { "type": "string", "format": "date-time", "description": "The date and time of when the advisory was published, in ISO 8601 format.", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time of when the advisory was last updated, in ISO 8601 format.", "readOnly": true }, "github_reviewed_at": { "type": "string", "format": "date-time", "description": "The date and time of when the advisory was reviewed by GitHub, in ISO 8601 format.", "readOnly": true, "nullable": true }, "nvd_published_at": { "type": "string", "format": "date-time", "description": "The date and time when the advisory was published in the National Vulnerability Database, in ISO 8601 format.\nThis field is only populated when the advisory is imported from the National Vulnerability Database.", "readOnly": true, "nullable": true }, "withdrawn_at": { "type": "string", "format": "date-time", "description": "The date and time of when the advisory was withdrawn, in ISO 8601 format.", "readOnly": true, "nullable": true }, "vulnerabilities": { "type": "array", "description": "The products and respective version ranges affected by the advisory.", "nullable": true, "items": { "description": "A vulnerability describing the product and its affected versions within a GitHub Security Advisory.", "type": "object", "properties": { "package": { "description": "The name of the package affected by the vulnerability.", "type": "object", "nullable": true, "properties": { "ecosystem": { "type": "string", "description": "The package's language or package management ecosystem.", "enum": [ "rubygems", "npm", "pip", "maven", "nuget", "composer", "go", "rust", "erlang", "actions", "pub", "other", "swift" ] }, "name": { "type": "string", "description": "The unique package name within its ecosystem.", "nullable": true } }, "required": [ "ecosystem", "name" ] }, "vulnerable_version_range": { "type": "string", "description": "The range of the package versions affected by the vulnerability.", "nullable": true }, "first_patched_version": { "type": "string", "description": "The package version that resolves the vulnerability.", "nullable": true }, "vulnerable_functions": { "type": "array", "description": "The functions in the package that are affected by the vulnerability.", "nullable": true, "readOnly": true, "items": { "type": "string" } } }, "required": [ "package", "vulnerable_version_range", "first_patched_version", "vulnerable_functions" ] } }, "cvss": { "type": "object", "nullable": true, "properties": { "vector_string": { "type": "string", "description": "The CVSS vector.", "nullable": true }, "score": { "type": "number", "description": "The CVSS score.", "minimum": 0, "maximum": 10, "nullable": true, "readOnly": true } }, "required": [ "vector_string", "score" ] }, "cvss_severities": { "type": "object", "nullable": true, "properties": { "cvss_v3": { "type": "object", "nullable": true, "properties": { "vector_string": { "type": "string", "description": "The CVSS 3 vector string.", "nullable": true }, "score": { "type": "number", "description": "The CVSS 3 score.", "minimum": 0, "maximum": 10, "nullable": true, "readOnly": true } }, "required": [ "vector_string", "score" ] }, "cvss_v4": { "type": "object", "nullable": true, "properties": { "vector_string": { "type": "string", "description": "The CVSS 4 vector string.", "nullable": true }, "score": { "type": "number", "description": "The CVSS 4 score.", "minimum": 0, "maximum": 10, "nullable": true, "readOnly": true } }, "required": [ "vector_string", "score" ] } } }, "epss": { "type": "object", "nullable": true, "readOnly": true, "description": "The EPSS scores as calculated by the [Exploit Prediction Scoring System](https://www.first.org/epss).", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "percentile": { "type": "number", "minimum": 0, "maximum": 100 } } }, "cwes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "cwe_id": { "type": "string", "description": "The Common Weakness Enumeration (CWE) identifier." }, "name": { "type": "string", "description": "The name of the CWE.", "readOnly": true } }, "required": [ "cwe_id", "name" ] } }, "credits": { "type": "array", "description": "The users who contributed to the advisory.", "nullable": true, "readOnly": true, "items": { "type": "object", "properties": { "user": { "title": "Simple User", "description": "A GitHub user.", "type": "object", "properties": { "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" }, "login": { "type": "string", "example": "octocat" }, "id": { "type": "integer", "format": "int64", "example": 1 }, "node_id": { "type": "string", "example": "MDQ6VXNlcjE=" }, "avatar_url": { "type": "string", "format": "uri", "example": "https://github.com/images/error/octocat_happy.gif" }, "gravatar_id": { "type": "string", "example": "41d064eb2195891e12d0413f63227ea7", "nullable": true }, "url": { "type": "string", "format": "uri", "example": "https://api.github.com/users/octocat" }, "html_url": { "type": "string", "format": "uri", "example": "https://github.com/octocat" }, "followers_url": { "type": "string", "format": "uri", "example": "https://api.github.com/users/octocat/followers" }, "following_url": { "type": "string", "example": "https://api.github.com/users/octocat/following{/other_user}" }, "gists_url": { "type": "string", "example": "https://api.github.com/users/octocat/gists{/gist_id}" }, "starred_url": { "type": "string", "example": "https://api.github.com/users/octocat/starred{/owner}{/repo}" }, "subscriptions_url": { "type": "string", "format": "uri", "example": "https://api.github.com/users/octocat/subscriptions" }, "organizations_url": { "type": "string", "format": "uri", "example": "https://api.github.com/users/octocat/orgs" }, "repos_url": { "type": "string", "format": "uri", "example": "https://api.github.com/users/octocat/repos" }, "events_url": { "type": "string", "example": "https://api.github.com/users/octocat/events{/privacy}" }, "received_events_url": { "type": "string", "format": "uri", "example": "https://api.github.com/users/octocat/received_events" }, "type": { "type": "string", "example": "User" }, "site_admin": { "type": "boolean" }, "starred_at": { "type": "string", "example": "\"2020-07-09T00:17:55Z\"" }, "user_view_type": { "type": "string", "example": "public" } }, "required": [ "avatar_url", "events_url", "followers_url", "following_url", "gists_url", "gravatar_id", "html_url", "id", "node_id", "login", "organizations_url", "received_events_url", "repos_url", "site_admin", "starred_url", "subscriptions_url", "type", "url" ] }, "type": { "type": "string", "description": "The type of credit the user is receiving.", "enum": [ "analyst", "finder", "reporter", "coordinator", "remediation_developer", "remediation_reviewer", "remediation_verifier", "tool", "sponsor", "other" ] } }, "required": [ "user", "type" ] } } }, "required": [ "ghsa_id", "cve_id", "url", "html_url", "repository_advisory_url", "summary", "description", "type", "severity", "source_code_location", "identifiers", "references", "published_at", "updated_at", "github_reviewed_at", "nvd_published_at", "withdrawn_at", "vulnerabilities", "cvss", "cwes", "credits" ], "additionalProperties": false } }, "examples": { "default": { "value": [ { "id": 1, "ghsa_id": "GHSA-abcd-1234-efgh", "cve_id": "CVE-2050-00000", "url": "https://api.github.com/advisories/GHSA-abcd-1234-efgh", "html_url": "https://github.com/advisories/GHSA-abcd-1234-efgh", "repository_advisory_url": "https://api