Apps API Reference

Get the authenticated app

GET /app

Returns the GitHub App associated with the authentication credentials used. To see how many app installations are associated with this GitHub App, see the installations_count in the response. For more details about your app's installations, see the "List installations for the authenticated app" endpoint.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
200	Response	yes

Create a GitHub App from a manifest

POST /app-manifests/{code}/conversions

Use this endpoint to complete the handshake necessary when implementing the GitHub App Manifest flow. When you create a GitHub App with the manifest flow, you receive a temporary code used to retrieve the GitHub App's id, pem (private key), and webhook_secret.

Parameters

Name	In	Required	Description
`code`	path	yes

Responses

Status	Description	Has JSON body
201	Response	yes
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes

Get a webhook configuration for an app

GET /app/hook/config

Returns the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see "Creating a GitHub App."

Parameters

No parameters.

Responses

Status	Description	Has JSON body
200	Response	yes

Update a webhook configuration for an app

PATCH /app/hook/config

Updates the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see "Creating a GitHub App."

Parameters

No parameters.

Responses

Status	Description	Has JSON body
200	Response	yes

List deliveries for an app webhook

GET /app/hook/deliveries

Returns a list of webhook deliveries for the webhook configured for a GitHub App.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`cursor`	query	no	Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the `link` header for the next and previous page cursors.
`status`	query	no	Returns webhook deliveries filtered by delivery outcome classification based on `status_code` range. A `status` of `success` returns deliveries with a `status_code` in the 200-399 range (inclusive). A `status` of `failure` returns deliveries with a `status_code` in the 400-599 range (inclusive).

Responses

Status	Description	Has JSON body
200	Response	yes
400	Bad Request	yes
422	Validation failed, or the endpoint has been spammed.	yes

Get a delivery for an app webhook

GET /app/hook/deliveries/{delivery_id}

Returns a delivery for the webhook configured for a GitHub App.

Parameters

Name	In	Required	Description
`delivery_id`	path	yes

Responses

Status	Description	Has JSON body
200	Response	yes
400	Bad Request	yes
422	Validation failed, or the endpoint has been spammed.	yes

Redeliver a delivery for an app webhook

POST /app/hook/deliveries/{delivery_id}/attempts

Redeliver a delivery for the webhook configured for a GitHub App.

Parameters

Name	In	Required	Description
`delivery_id`	path	yes

Responses

Status	Description	Has JSON body
202	Accepted	yes
400	Bad Request	yes
422	Validation failed, or the endpoint has been spammed.	yes

List installation requests for the authenticated app

GET /app/installation-requests

Lists all the pending installation requests for the authenticated GitHub App.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	List of integration installation requests	yes
304	Not modified	no
401	Requires authentication	yes

List installations for the authenticated app

GET /app/installations

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

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
`since`	query	no	Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`outdated`	query	no

Responses

Status	Description	Has JSON body
200	The permissions the installation has are included under the `permissions` key.	yes

Get an installation for the authenticated app

GET /app/installations/{installation_id}

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

Parameters

Name	In	Required	Description
`installation_id`	path	yes	The unique identifier of the installation.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes

Delete an installation for the authenticated app

DELETE /app/installations/{installation_id}

Uninstalls a GitHub App on a user, organization, or enterprise 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.

Parameters

Name	In	Required	Description
`installation_id`	path	yes	The unique identifier of the installation.

Responses

Status	Description	Has JSON body
204	Response	no
404	Resource not found	yes

Create an installation access token for an app

POST /app/installations/{installation_id}/access_tokens

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.

Parameters

Name	In	Required	Description
`installation_id`	path	yes	The unique identifier of the installation.

Responses

Status	Description	Has JSON body
201	Response	yes
403	Forbidden	yes
401	Requires authentication	yes
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes

Suspend an app installation

PUT /app/installations/{installation_id}/suspended

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

Parameters

Name	In	Required	Description
`installation_id`	path	yes	The unique identifier of the installation.

Responses

Status	Description	Has JSON body
204	Response	no
404	Resource not found	yes

Unsuspend an app installation

DELETE /app/installations/{installation_id}/suspended

Removes a GitHub App installation suspension.

Parameters

Name	In	Required	Description
`installation_id`	path	yes	The unique identifier of the installation.

Responses

Status	Description	Has JSON body
204	Response	no
404	Resource not found	yes

Delete an app authorization

DELETE /applications/{client_id}/grant

OAuth and GitHub application owners can revoke a grant for their application and a specific user. You must provide a valid OAuth access_token as an input parameter and the grant for the token's owner will be deleted.

Parameters

Name	In	Required	Description
`client_id`	path	yes	The client ID of the GitHub app.

Responses

Status	Description	Has JSON body
204	Response	no
422	Validation failed, or the endpoint has been spammed.	yes

Check a token

POST /applications/{client_id}/token

OAuth applications and GitHub applications with OAuth authorizations can use this API method for checking OAuth token validity without exceeding the normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. Invalid tokens will return 404 NOT FOUND.

Parameters

Name	In	Required	Description
`client_id`	path	yes	The client ID of the GitHub app.

Responses

Status	Description	Has JSON body
200	Response	yes
422	Validation failed, or the endpoint has been spammed.	yes
404	Resource not found	yes

Reset a token

PATCH /applications/{client_id}/token

OAuth applications and GitHub applications with OAuth authorizations can use this API method to reset a valid OAuth token without end-user involvement. Applications must save the "token" property in the response because changes take effect immediately. Invalid tokens will return 404 NOT FOUND.

Parameters

Name	In	Required	Description
`client_id`	path	yes	The client ID of the GitHub app.

Responses

Status	Description	Has JSON body
200	Response	yes
422	Validation failed, or the endpoint has been spammed.	yes

Delete an app token

DELETE /applications/{client_id}/token

OAuth or GitHub application owners can revoke a single token for an OAuth application or a GitHub application with an OAuth authorization.

Parameters

Name	In	Required	Description
`client_id`	path	yes	The client ID of the GitHub app.

Responses

Status	Description	Has JSON body
204	Response	no
422	Validation failed, or the endpoint has been spammed.	yes

Create a scoped access token

POST /applications/{client_id}/token/scoped

Use a non-scoped user access token to create a repository-scoped and/or permission-scoped user access token. You can specify

Parameters

Name	In	Required	Description
`client_id`	path	yes	The client ID of the GitHub app.

Responses

Status	Description	Has JSON body
200	Response	yes
401	Requires authentication	yes
403	Forbidden	yes
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes

Get an app

GET /apps/{app_slug}

Parameters

Name	In	Required	Description
`app_slug`	path	yes

Responses

Status	Description	Has JSON body
200	Response	yes
403	Forbidden	yes
404	Resource not found	yes

List repositories accessible to the app installation

GET /installation/repositories

List repositories that an app installation can access.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
403	Forbidden	yes
304	Not modified	no
401	Requires authentication	yes

Revoke an installation access token

DELETE /installation/token

Revokes the installation token you're using to authenticate as an installation and access this endpoint.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
204	Response	no

Get a subscription plan for an account

GET /marketplace_listing/accounts/{account_id}

Shows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

Parameters

Name	In	Required	Description
`account_id`	path	yes	account_id parameter

Responses

Status	Description	Has JSON body
200	Response	yes
404	Not Found when the account has not purchased the listing	yes
401	Requires authentication	yes

List plans

GET /marketplace_listing/plans

Lists all plans that are part of your GitHub Marketplace listing.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes
401	Requires authentication	yes

List accounts for a plan

GET /marketplace_listing/plans/{plan_id}/accounts

Returns user and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

Parameters

Name	In	Required	Description
`plan_id`	path	yes	The unique identifier of the plan.
`sort`	query	no	The property to sort the results by.
`direction`	query	no	To return the oldest accounts first, set to `asc`. Ignored without the `sort` parameter.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes
401	Requires authentication	yes

Get a subscription plan for an account (stubbed)

GET /marketplace_listing/stubbed/accounts/{account_id}

Shows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

Parameters

Name	In	Required	Description
`account_id`	path	yes	account_id parameter

Responses

Status	Description	Has JSON body
200	Response	yes
404	Not Found when the account has not purchased the listing	no
401	Requires authentication	yes

List plans (stubbed)

GET /marketplace_listing/stubbed/plans

Lists all plans that are part of your GitHub Marketplace listing.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
401	Requires authentication	yes

List accounts for a plan (stubbed)

GET /marketplace_listing/stubbed/plans/{plan_id}/accounts

Returns repository and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

Parameters

Name	In	Required	Description
`plan_id`	path	yes	The unique identifier of the plan.
`sort`	query	no	The property to sort the results by.
`direction`	query	no	To return the oldest accounts first, set to `asc`. Ignored without the `sort` parameter.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
401	Requires authentication	yes

Get an organization installation for the authenticated app

GET /orgs/{org}/installation

Enables an authenticated GitHub App to find the organization's installation information.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.

Responses

Status	Description	Has JSON body
200	Response	yes

Get a repository installation for the authenticated app

GET /repos/{owner}/{repo}/installation

Enables an authenticated GitHub App to find the repository's installation information. The installation's account type will be either an organization or a user account, depending which account the repository belongs to.

Parameters

Name	In	Required	Description
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
200	Response	yes
301	Moved permanently	yes
404	Resource not found	yes

List app installations accessible to the user access token

GET /user/installations

Lists installations of your GitHub App that the authenticated user has explicit permission (:read, :write, or :admin) to access.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	You can find the permissions for the installation under the `permissions` key.	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

List repositories accessible to the user access token

GET /user/installations/{installation_id}/repositories

List repositories that the authenticated user has explicit permission (:read, :write, or :admin) to access for an installation.

Parameters

Name	In	Required	Description
`installation_id`	path	yes	The unique identifier of the installation.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	The access the user has to each repository is included in the hash under the `permissions` key.	yes
404	Resource not found	yes
403	Forbidden	yes
304	Not modified	no

Add a repository to an app installation

PUT /user/installations/{installation_id}/repositories/{repository_id}

Add a single repository to an installation. The authenticated user must have admin access to the repository.

Parameters

Name	In	Required	Description
`installation_id`	path	yes	The unique identifier of the installation.
`repository_id`	path	yes	The unique identifier of the repository.

Responses

Status	Description	Has JSON body
204	Response	no
403	Forbidden	yes
304	Not modified	no
404	Resource not found	yes

Remove a repository from an app installation

DELETE /user/installations/{installation_id}/repositories/{repository_id}

Remove a single repository from an installation. The authenticated user must have admin access to the repository. The installation must have the repository_selection of selected.

Parameters

Name	In	Required	Description
`installation_id`	path	yes	The unique identifier of the installation.
`repository_id`	path	yes	The unique identifier of the repository.

Responses

Status	Description	Has JSON body
204	Response	no
403	Forbidden	yes
304	Not modified	no
404	Resource not found	yes
422	Returned when the application is installed on `all` repositories in the organization, or if this request would remove the last repository that the application has access to in the organization.	no

List subscriptions for the authenticated user

GET /user/marketplace_purchases

Lists the active subscriptions for the authenticated user.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
401	Requires authentication	yes
404	Resource not found	yes

List subscriptions for the authenticated user (stubbed)

GET /user/marketplace_purchases/stubbed

Lists the active subscriptions for the authenticated user.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
401	Requires authentication	yes

Get a user installation for the authenticated app

GET /users/{username}/installation

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

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
200	Response	yes