Search
K
GitHub v3 REST API

Get the authenticated 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.

You must use a JWT to access this endpoint.

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

Response

200 application/json

Response

GitHub app

GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.

idintegerrequired

Unique identifier of the GitHub app

Example:37

slugstring

The slug name of the GitHub app

Example:probot-owners

node_idstringrequired

Example:MDExOkludGVncmF0aW9uMQ==

ownerobject | nullrequired

Simple User

Show Child Parameters
namestringrequired

The name of the GitHub app

Example:Probot Owners

descriptionstring | nullrequired

Example:The description of the app.

external_urlstring(uri)required

Example:https://example.com

html_urlstring(uri)required

Example:https://github.com/apps/super-ci

created_atstring(date-time)required

Example:2017-07-08T16:18:44-04:00

updated_atstring(date-time)required

Example:2017-07-08T16:18:44-04:00

permissionsobjectrequired

The set of permissions for the GitHub app

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

Show Child Parameters
eventsarray[string]required

The list of events for the GitHub app

Example:["label","deployment"]

installations_countinteger

The number of installations associated with the GitHub app

Example:5

client_idstring

Example:"Iv1.25b5d1e65ffc4022"

client_secretstring

Example:"1d4b2097ac622ba702d19de498f005747a8b21d3"

webhook_secretstring | null

Example:"6fba8f2fc8a7e8f2cca5577eddd82ca7586b3b6b"

pemstring

Example:"-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEArYxrNYD/iT5CZVpRJu4rBKmmze3PVmT/gCo2ATUvDvZTPTey\nxcGJ3vvrJXazKk06pN05TN29o98jrYz4cengG3YGsXPNEpKsIrEl8NhbnxapEnM9\nJCMRe0P5JcPsfZlX6hmiT7136GRWiGOUba2X9+HKh8QJVLG5rM007TBER9/z9mWm\nrJuNh+m5l320oBQY/Qq3A7wzdEfZw8qm/mIN0FCeoXH1L6B8xXWaAYBwhTEh6SSn\nZHlO1Xu1JWDmAvBCi0RO5aRSKM8q9QEkvvHP4yweAtK3N8+aAbZ7ovaDhyGz8r6r\nzhU1b8Uo0Z2ysf503WqzQgIajr7Fry7/kUwpgQIDAQABAoIBADwJp80Ko1xHPZDy\nfcCKBDfIuPvkmSW6KumbsLMaQv1aGdHDwwTGv3t0ixSay8CGlxMRtRDyZPib6SvQ\n6OH/lpfpbMdW2ErkksgtoIKBVrDilfrcAvrNZu7NxRNbhCSvN8q0s4ICecjbbVQh\nnueSdlA6vGXbW58BHMq68uRbHkP+k+mM9U0mDJ1HMch67wlg5GbayVRt63H7R2+r\nVxcna7B80J/lCEjIYZznawgiTvp3MSanTglqAYi+m1EcSsP14bJIB9vgaxS79kTu\noiSo93leJbBvuGo8QEiUqTwMw4tDksmkLsoqNKQ1q9P7LZ9DGcujtPy4EZsamSJT\ny8OJt0ECgYEA2lxOxJsQk2kI325JgKFjo92mQeUObIvPfSNWUIZQDTjniOI6Gv63\nGLWVFrZcvQBWjMEQraJA9xjPbblV8PtfO87MiJGLWCHFxmPz2dzoedN+2Coxom8m\nV95CLz8QUShuao6u/RYcvUaZEoYs5bHcTmy5sBK80JyEmafJPtCQVxMCgYEAy3ar\nZr3yv4xRPEPMat4rseswmuMooSaK3SKub19WFI5IAtB/e7qR1Rj9JhOGcZz+OQrl\nT78O2OFYlgOIkJPvRMrPpK5V9lslc7tz1FSh3BZMRGq5jSyD7ETSOQ0c8T2O/s7v\nbeEPbVbDe4mwvM24XByH0GnWveVxaDl51ABD65sCgYB3ZAspUkOA5egVCh8kNpnd\nSd6SnuQBE3ySRlT2WEnCwP9Ph6oPgn+oAfiPX4xbRqkL8q/k0BdHQ4h+zNwhk7+h\nWtPYRAP1Xxnc/F+jGjb+DVaIaKGU18MWPg7f+FI6nampl3Q0KvfxwX0GdNhtio8T\nTj1E+SnFwh56SRQuxSh2gwKBgHKjlIO5NtNSflsUYFM+hyQiPiqnHzddfhSG+/3o\nm5nNaSmczJesUYreH5San7/YEy2UxAugvP7aSY2MxB+iGsiJ9WD2kZzTUlDZJ7RV\nUzWsoqBR+eZfVJ2FUWWvy8TpSG6trh4dFxImNtKejCR1TREpSiTV3Zb1dmahK9GV\nrK9NAoGAbBxRLoC01xfxCTgt5BDiBcFVh4fp5yYKwavJPLzHSpuDOrrI9jDn1oKN\nonq5sDU1i391zfQvdrbX4Ova48BN+B7p63FocP/MK5tyyBoT8zQEk2+vWDOw7H/Z\nu5dTCPxTIsoIwUw1I+7yIxqJzLPFgR2gVBwY1ra/8iAqCj+zeBw=\n-----END RSA PRIVATE KEY-----\n"

get/app
 
200 application/json

Create a GitHub App from a manifest

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.

post
{protocol}://{hostname}/api/v3/app-manifests/{code}/conversions

Path Parameters

codestringrequired

Body

application/json
object
* Additional properties are NOT allowed.

Response

application/json

Response

GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.

* Additional properties are allowed.
idintegerrequired

Unique identifier of the GitHub app

Example:37

slugstring

The slug name of the GitHub app

Example:probot-owners

node_idstringrequired

Example:MDExOkludGVncmF0aW9uMQ==

ownerobject | nullrequired

Simple User

Show Child Parameters
namestringrequired

The name of the GitHub app

Example:Probot Owners

descriptionstring | nullrequired

Example:The description of the app.

external_urlstring(uri)required

Example:https://example.com

html_urlstring(uri)required

Example:https://github.com/apps/super-ci

created_atstring(date-time)required

Example:2017-07-08T16:18:44-04:00

updated_atstring(date-time)required

Example:2017-07-08T16:18:44-04:00

permissionsobjectrequired

The set of permissions for the GitHub app

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

Show Child Parameters
eventsarray[string]required

The list of events for the GitHub app

Example:["label","deployment"]

installations_countinteger

The number of installations associated with the GitHub app

Example:5

client_idstringrequired

Example:"Iv1.25b5d1e65ffc4022"

client_secretstringrequired

Example:"1d4b2097ac622ba702d19de498f005747a8b21d3"

webhook_secretstring | nullrequired

Example:"6fba8f2fc8a7e8f2cca5577eddd82ca7586b3b6b"

pemstringrequired

Example:"-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEArYxrNYD/iT5CZVpRJu4rBKmmze3PVmT/gCo2ATUvDvZTPTey\nxcGJ3vvrJXazKk06pN05TN29o98jrYz4cengG3YGsXPNEpKsIrEl8NhbnxapEnM9\nJCMRe0P5JcPsfZlX6hmiT7136GRWiGOUba2X9+HKh8QJVLG5rM007TBER9/z9mWm\nrJuNh+m5l320oBQY/Qq3A7wzdEfZw8qm/mIN0FCeoXH1L6B8xXWaAYBwhTEh6SSn\nZHlO1Xu1JWDmAvBCi0RO5aRSKM8q9QEkvvHP4yweAtK3N8+aAbZ7ovaDhyGz8r6r\nzhU1b8Uo0Z2ysf503WqzQgIajr7Fry7/kUwpgQIDAQABAoIBADwJp80Ko1xHPZDy\nfcCKBDfIuPvkmSW6KumbsLMaQv1aGdHDwwTGv3t0ixSay8CGlxMRtRDyZPib6SvQ\n6OH/lpfpbMdW2ErkksgtoIKBVrDilfrcAvrNZu7NxRNbhCSvN8q0s4ICecjbbVQh\nnueSdlA6vGXbW58BHMq68uRbHkP+k+mM9U0mDJ1HMch67wlg5GbayVRt63H7R2+r\nVxcna7B80J/lCEjIYZznawgiTvp3MSanTglqAYi+m1EcSsP14bJIB9vgaxS79kTu\noiSo93leJbBvuGo8QEiUqTwMw4tDksmkLsoqNKQ1q9P7LZ9DGcujtPy4EZsamSJT\ny8OJt0ECgYEA2lxOxJsQk2kI325JgKFjo92mQeUObIvPfSNWUIZQDTjniOI6Gv63\nGLWVFrZcvQBWjMEQraJA9xjPbblV8PtfO87MiJGLWCHFxmPz2dzoedN+2Coxom8m\nV95CLz8QUShuao6u/RYcvUaZEoYs5bHcTmy5sBK80JyEmafJPtCQVxMCgYEAy3ar\nZr3yv4xRPEPMat4rseswmuMooSaK3SKub19WFI5IAtB/e7qR1Rj9JhOGcZz+OQrl\nT78O2OFYlgOIkJPvRMrPpK5V9lslc7tz1FSh3BZMRGq5jSyD7ETSOQ0c8T2O/s7v\nbeEPbVbDe4mwvM24XByH0GnWveVxaDl51ABD65sCgYB3ZAspUkOA5egVCh8kNpnd\nSd6SnuQBE3ySRlT2WEnCwP9Ph6oPgn+oAfiPX4xbRqkL8q/k0BdHQ4h+zNwhk7+h\nWtPYRAP1Xxnc/F+jGjb+DVaIaKGU18MWPg7f+FI6nampl3Q0KvfxwX0GdNhtio8T\nTj1E+SnFwh56SRQuxSh2gwKBgHKjlIO5NtNSflsUYFM+hyQiPiqnHzddfhSG+/3o\nm5nNaSmczJesUYreH5San7/YEy2UxAugvP7aSY2MxB+iGsiJ9WD2kZzTUlDZJ7RV\nUzWsoqBR+eZfVJ2FUWWvy8TpSG6trh4dFxImNtKejCR1TREpSiTV3Zb1dmahK9GV\nrK9NAoGAbBxRLoC01xfxCTgt5BDiBcFVh4fp5yYKwavJPLzHSpuDOrrI9jDn1oKN\nonq5sDU1i391zfQvdrbX4Ova48BN+B7p63FocP/MK5tyyBoT8zQEk2+vWDOw7H/Z\nu5dTCPxTIsoIwUw1I+7yIxqJzLPFgR2gVBwY1ra/8iAqCj+zeBw=\n-----END RSA PRIVATE KEY-----\n"

post/app-manifests/{code}/conversions

Body

{}
 
application/json

Get a webhook configuration for an app

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

You must use a JWT to access this endpoint.

get
{protocol}://{hostname}/api/v3/app/hook/config

Response

200 application/json

Response

Webhook Configuration

Configuration object of the webhook

urlstring(uri)

The URL to which the payloads will be delivered.

Example:https://example.com/webhook

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

Example:"json"

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

Example:"********"

insecure_sslOne Of
Variant 1string

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

Example:"0"

get/app/hook/config
 
200 application/json

Update a webhook configuration for an app

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

You must use a JWT to access this endpoint.

patch
{protocol}://{hostname}/api/v3/app/hook/config

Body

application/json
urlstring(uri)

The URL to which the payloads will be delivered.

Example:https://example.com/webhook

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

Example:"json"

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

Example:"********"

insecure_sslOne Of
Variant 1string

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

Example:"0"

Response

200 application/json

Response

Webhook Configuration

Configuration object of the webhook

urlstring(uri)

The URL to which the payloads will be delivered.

Example:https://example.com/webhook

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

Example:"json"

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

Example:"********"

insecure_sslOne Of
Variant 1string

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

Example:"0"

patch/app/hook/config

Body

{ "content_type": "json", "insecure_ssl": "0", "secret": "********", "url": "https://example.com/webhook" }
 
200 application/json

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