GitHub v3 REST API

List installations for the authenticated app

You must use a JWT to access this endpoint.

The permissions the installation has are included under the permissions key.

get
{protocol}://{hostname}/api/v3/app/installations

Query Parameters

per_pageinteger

Results per page (max 100)

Default:30

pageinteger

Page number of the results to fetch.

Default:1

sincestring(date-time)

Only show notifications updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

outdatedstring

Response

200 application/json

The permissions the installation has are included under the permissions key.

Installation

idintegerrequired

The ID of the installation.

Example:1

accountAny Of
required
Simple Userobject

Simple User

Show Child Parameters
repository_selectionstringrequired

Describe whether all repositories have been selected or there’s a selection involved

Allowed values:allselected

access_tokens_urlstring(uri)required

Example:https://api.github.com/installations/1/access_tokens

repositories_urlstring(uri)required

Example:https://api.github.com/installation/repositories

html_urlstring(uri)required

Example:https://github.com/organizations/github/settings/installations/1

app_idintegerrequired

Example:1

target_idintegerrequired

The ID of the user or organization this token is being scoped to.

target_typestringrequired

Example:Organization

permissionsobjectrequired

The permissions granted to the user-to-server access token.

Example:{"contents":"read","issues":"read","deployments":"write","single_file":"read"}

Show Child Parameters
eventsarray[string]required
created_atstring(date-time)required
updated_atstring(date-time)required
single_file_namestring | nullrequired

Example:config.yaml

has_multiple_single_filesboolean

Example:true

single_file_pathsarray[string]

Example:["config.yml",".github/issue_TEMPLATE.md"]

app_slugstringrequired

Example:github-actions

suspended_byobject | nullrequired

Simple User

Show Child Parameters
suspended_atstring | null(date-time)required
contact_emailstring | null

Example:"test_13f1e99741e3e004@d7e1eb0bc0a1ba12.com"

get/app/installations
 
200 application/json

Get an installation for the authenticated app

Enables an authenticated GitHub App to find an installation’s information using the installation id.

You must use a JWT to access this endpoint.

get
{protocol}://{hostname}/api/v3/app/installations/{installation_id}

Path Parameters

installation_idintegerrequired

installation_id parameter

Response

application/json

Response

Installation

Installation

idintegerrequired

The ID of the installation.

Example:1

accountAny Of
required
Simple Userobject

Simple User

Show Child Parameters
repository_selectionstringrequired

Describe whether all repositories have been selected or there’s a selection involved

Allowed values:allselected

access_tokens_urlstring(uri)required

Example:https://api.github.com/installations/1/access_tokens

repositories_urlstring(uri)required

Example:https://api.github.com/installation/repositories

html_urlstring(uri)required

Example:https://github.com/organizations/github/settings/installations/1

app_idintegerrequired

Example:1

target_idintegerrequired

The ID of the user or organization this token is being scoped to.

target_typestringrequired

Example:Organization

permissionsobjectrequired

The permissions granted to the user-to-server access token.

Example:{"contents":"read","issues":"read","deployments":"write","single_file":"read"}

Show Child Parameters
eventsarray[string]required
created_atstring(date-time)required
updated_atstring(date-time)required
single_file_namestring | nullrequired

Example:config.yaml

has_multiple_single_filesboolean

Example:true

single_file_pathsarray[string]

Example:["config.yml",".github/issue_TEMPLATE.md"]

app_slugstringrequired

Example:github-actions

suspended_byobject | nullrequired

Simple User

Show Child Parameters
suspended_atstring | null(date-time)required
contact_emailstring | null

Example:"test_13f1e99741e3e004@d7e1eb0bc0a1ba12.com"

get/app/installations/{installation_id}
 
application/json

Delete an installation for the authenticated app

Uninstalls a GitHub App on a user, organization, or business account. If you prefer to temporarily suspend an app’s access to your account’s resources, then we recommend the “Suspend an app installation” endpoint.

You must use a JWT to access this endpoint.

delete
{protocol}://{hostname}/api/v3/app/installations/{installation_id}

Path Parameters

installation_idintegerrequired

installation_id parameter

Response

Response

delete/app/installations/{installation_id}
 

Create an installation access token for an app

Creates an installation access token that enables a GitHub App to make authenticated API requests for the app’s installation on an organization or individual account. Installation tokens expire one hour from the time you create them. Using an expired token produces a status code of 401 - Unauthorized, and requires creating a new installation token. By default the installation token has access to all repositories that the installation can access. To restrict the access to specific repositories, you can provide the repository_ids when creating the token. When you omit repository_ids, the response does not contain the repositories key.

You must use a JWT to access this endpoint.

post
{protocol}://{hostname}/api/v3/app/installations/{installation_id}/access_tokens

Path Parameters

installation_idintegerrequired

installation_id parameter

Body

application/json
repositoriesarray[string]

List of repository names that the token should have access to

Example:rails

repository_idsarray[integer]

List of repository IDs that the token should have access to

Example:[1]

permissionsobject

The permissions granted to the user-to-server access token.

Example:{"contents":"read","issues":"read","deployments":"write","single_file":"read"}

Show Child Parameters

Response

application/json

Response

Installation Token

Authentication token for a GitHub App installed on a user or org.

tokenstringrequired
expires_atstringrequired
permissionsobject

The permissions granted to the user-to-server access token.

Example:{"contents":"read","issues":"read","deployments":"write","single_file":"read"}

Show Child Parameters
repository_selectionstring

Allowed values:allselected

repositoriesarray[object]

A git repository

Show Child Parameters
single_filestring

Example:README.md

has_multiple_single_filesboolean

Example:true

single_file_pathsarray[string]

Example:["config.yml",".github/issue_TEMPLATE.md"]

post/app/installations/{installation_id}/access_tokens

Body

{}
 
application/json

Suspend an app installation

Suspends a GitHub App on a user, organization, or business account, which blocks the app from accessing the account’s resources. When a GitHub App is suspended, the app’s access to the GitHub Enterprise Server API or webhook events is blocked for that account.

You must use a JWT to access this endpoint.

put
{protocol}://{hostname}/api/v3/app/installations/{installation_id}/suspended

Path Parameters

installation_idintegerrequired

installation_id parameter

Response

Response

put/app/installations/{installation_id}/suspended