openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Specific API
description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App
installations.'
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:
- name: Specific
paths:
/authorizations/clients/{client_id}:
put:
summary: GitHub Get or Create an Authorization Forspecific App
description: '**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).
**Warning:** Apps must use the [web application flow](https://docs.github.com/enterprise-server@3.9/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to obtain OAuth tokens that work with GitHub Enterprise Server SAML organizations. OAuth tokens created using the Authorizations API will be unable to access GitHub Enterprise Server SAML organizations. For more information, see the [blog post](https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api).
Creates a new authorization for the specified OAuth application, only if an authorization for that application doesn''t already exist for the user. The URL includes the 20 character client ID for the OAuth app that is requesting the token. It returns the user''s existing authorization for the application if one is present. Otherwise, it creates and returns a new one.
If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "[Working with two-factor authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#working-with-two-factor-authentication)."
**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).'
tags:
- Specific
operationId: getOrCreateAnAuthorizationForspecificApp
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#Get or Create-an-authorization-for-a-specific-app
parameters:
- $ref: '#/components/parameters/oauth-client-id'
requestBody:
required: true
content:
application/json:
schema:
properties:
client_secret:
description: The OAuth app client secret for which to create the token.
maxLength: 40
type: string
scopes:
description: A list of scopes that this authorization is in.
type: array
items:
type: string
example:
- public_repo
- user
nullable: true
note:
description: A note to remind you what the OAuth token is for.
type: string
example: Update all gems
note_url:
description: A URL to remind you what app the OAuth token is for.
type: string
fingerprint:
description: A unique string to distinguish an authorization from others created for the same client ID and user.
type: string
required:
- client_secret
type: object
examples:
default:
summary: Create an authorization for an app
value:
client_secret: 3ef4ad510c59ad37bac6bb4f80047fb3aee3cc7f
scopes:
- public_repo
note: optional note
note_url: http://optional/note/url
responses:
'200':
description: if returning an existing token
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
response-if-returning-an-existing-token:
$ref: '#/components/examples/authorization-response-if-returning-an-existing-token-2'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'201':
description: '**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).'
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
removalDate: '2020-11-13'
deprecationDate: '2020-02-14'
category: oauth-authorizations
subcategory: oauth-authorizations
deprecated: true
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/authorizations/clients/{client_id}/{fingerprint}:
put:
summary: GitHub Get or Create an Authorization Forspecific App and Fingerprint
description: '**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).
**Warning:** Apps must use the [web application flow](https://docs.github.com/enterprise-server@3.9/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to obtain OAuth tokens that work with GitHub Enterprise Server SAML organizations. OAuth tokens created using the Authorizations API will be unable to access GitHub Enterprise Server SAML organizations. For more information, see the [blog post](https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api).
This method will create a new authorization for the specified OAuth application, only if an authorization for that application and fingerprint do not already exist for the user. The URL includes the 20 character client ID for the OAuth app that is requesting the token. `fingerprint` is a unique string to distinguish an authorization from others created for the same client ID and user. It returns the user''s existing authorization for the application if one is present. Otherwise, it creates and returns a new one.
If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "[Working with two-factor authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#working-with-two-factor-authentication)."'
tags:
- Specific
operationId: getOrCreateAnAuthorizationForspecificAppAndFingerprint
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#Get or Create-an-authorization-for-a-specific-app-and-fingerprint
parameters:
- $ref: '#/components/parameters/oauth-client-id'
- name: fingerprint
in: path
required: true
schema:
type: string
example: example_value
requestBody:
required: true
content:
application/json:
schema:
properties:
client_secret:
description: The OAuth app client secret for which to create the token.
maxLength: 40
type: string
scopes:
description: A list of scopes that this authorization is in.
type: array
items:
type: string
example:
- public_repo
- user
nullable: true
note:
description: A note to remind you what the OAuth token is for.
type: string
example: Update all gems
note_url:
description: A URL to remind you what app the OAuth token is for.
type: string
required:
- client_secret
type: object
examples:
default:
summary: Create an authorization for an app and fingerprint
value:
client_secret: 3ef4ad510c59ad37bac6bb4f80047fb3aee3cc7f
scopes:
- public_repo
note: optional note
note_url: http://optional/note/url
responses:
'200':
description: if returning an existing token
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
response-if-returning-an-existing-token:
$ref: '#/components/examples/authorization-response-if-returning-an-existing-token'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'201':
description: Response if returning a new token
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization-3'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
removalDate: '2020-11-13'
deprecationDate: '2020-02-14'
category: oauth-authorizations
subcategory: oauth-authorizations
deprecated: true
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/commits/{ref}/status:
get:
summary: GitHub Get the Combined Status for Specific Reference
description: 'Users with pull access in a repository can access a combined view of commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name.
Additionally, a combined `state` is returned. The `state` is one of:
* **failure** if any of the contexts report as `error` or `failure`
* **pending** if there are no statuses or a context is `pending`
* **success** if the latest status for all contexts is `success`'
tags:
- Specific
operationId: getTheCombinedStatusForSpecificReference
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/commits/statuses#get-the-combined-status-for-a-specific-reference
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/commit-ref'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/combined-commit-status'
examples:
default:
$ref: '#/components/examples/combined-commit-status'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: commits
subcategory: statuses
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
nullable-simple-user:
title: Simple User
description: A GitHub user.
type: object
properties:
name:
nullable: true
type: string
example: octocat
email:
nullable: true
type: string
example: octocat@github.com
login:
type: string
example: octocat
id:
type: integer
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
example: true
starred_at:
type: string
example: '"2020-07-09T00:17:55Z"'
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
nullable: true
simple-user_2:
title: Simple User
description: GitHub user.
type: object
properties:
name:
type: string
example: octocat
email:
type: string
example: octocat@github.com
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
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
example: true
starred_at:
type: string
example: '"2020-07-09T00:17:55Z"'
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
code-of-conduct:
title: Code Of Conduct
description: Code Of Conduct
type: object
properties:
key:
type: string
example: contributor_covenant
name:
type: string
example: Contributor Covenant
url:
type: string
format: uri
example: https://api.github.com/codes_of_conduct/contributor_covenant
body:
type: string
example: "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.\n\n## Our Standards\n\nExamples of behavior that contributes to creating a positive environment include:\n\n* Using welcoming and inclusive language\n* Being respectful of differing viewpoints and experiences\n* Gracefully accepting constructive criticism\n* Focusing on what is best for the community\n* Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n* The use of sexualized language or imagery and unwelcome sexual attention or advances\n* Trolling, insulting/derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or electronic address, without explicit permission\n* Other conduct which could reasonably be considered inappropriate in a professional setting\n\n## Our Responsibilities\n\nProject maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.\n\n## Scope\n\nThis Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address,\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [EMAIL]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/).\n"
html_url:
type: string
format: uri
example: https://api.github.com/repos/octocat/Hello-World
required:
- url
- html_url
- key
- name
basic-error:
title: Basic Error
description: Basic Error
type: object
properties:
message:
type: string
example: Example body text
documentation_url:
type: string
example: https://api.github.com/repos/octocat/Hello-World
url:
type: string
example: https://api.github.com/repos/octocat/Hello-World
status:
type: string
example: open
combined-commit-status:
title: Combined Commit Status
description: Combined Commit Status
type: object
properties:
state:
type: string
example: open
statuses:
type: array
items:
$ref: '#/components/schemas/simple-commit-status'
sha:
type: string
example: abc123def456789012345678901234567890
total_count:
type: integer
example: 42
repository:
$ref: '#/components/schemas/minimal-repository'
commit_url:
type: string
format: uri
example: https://api.github.com/repos/octocat/Hello-World
url:
type: string
format: uri
example: https://api.github.com/repos/octocat/Hello-World
required:
- state
- sha
- total_count
- statuses
- repository
- commit_url
- url
validation-error:
title: Validation Error
description: Validation Error
type: object
required:
- message
- documentation_url
properties:
message:
type: string
example: Example body text
documentation_url:
type: string
example: https://api.github.com/repos/octocat/Hello-World
errors:
type: array
items:
type: object
required:
- code
properties:
resource:
type: string
field:
type: string
message:
type: string
code:
type: string
index:
type: integer
value:
oneOf:
- type: string
nullable: true
- type: integer
nullable: true
- type: array
nullable: true
items:
type: string
nullable-scoped-installation:
title: Scoped Installation
type: object
properties:
permissions:
$ref: '#/components/schemas/app-permissions'
repository_selection:
description: Describe whether all repositories have been selected or there's a selection involved
type: string
enum:
- all
- selected
example: all
single_file_name:
type: string
example: config.yaml
nullable: true
has_multiple_single_files:
type: boolean
example: true
single_file_paths:
type: array
items:
type: string
example:
- config.yml
- .github/issue_TEMPLATE.md
repositories_url:
type: string
format: uri
example: https://api.github.com/users/octocat/repos
account:
$ref: '#/components/schemas/simple-user'
required:
- permissions
- repository_selection
- single_file_name
- repositories_url
- account
nullable: true
app-permissions:
title: App Permissions
type: object
description: The permissions granted to the user access token.
properties:
actions:
type: string
description: The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts.
enum:
- read
- write
example: read
administration:
type: string
description: The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation.
enum:
- read
- write
example: read
checks:
type: string
description: The level of permission to grant the access token for checks on code.
enum:
- read
- write
example: read
codespaces:
type: string
description: The level of permission to grant the access token to create, edit, delete, and list Codespaces.
enum:
- read
- write
example: read
contents:
type: string
description: The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges.
enum:
- read
- write
example: read
dependabot_secrets:
type: string
description: The leve of permission to grant the access token to manage Dependabot secrets.
enum:
- read
- write
example: read
deployments:
type: string
description: The level of permission to grant the access token for deployments and deployment statuses.
enum:
- read
- write
example: read
environments:
type: string
description: The level of permission to grant the access token for managing repository environments.
enum:
- read
- write
example: read
issues:
type: string
description: The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones.
enum:
- read
- write
example: read
metadata:
type: string
description: The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata.
enum:
- read
- write
example: read
packages:
type: string
description: The level of permission to grant the access token for packages published to GitHub Packages.
enum:
- read
- write
example: read
pages:
type: string
description: The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds.
enum:
- read
- write
example: read
pull_requests:
type: string
description: The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges.
enum:
- read
- write
example: read
repository_hooks:
type: string
description: The level of permission to grant the access token to manage the post-receive hooks for a repository.
enum:
- r
# --- truncated at 32 KB (668 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-specific-api-openapi.yml