English
No results found.

Explore by product

REST API
  • Get started
  • Account and profile
  • Authentication
  • Repositories
  • GitHub
  • Enterprise administrators
  • Billing and payments
  • Organizations
  • Code security
  • GitHub Issues
  • GitHub Actions
  • GitHub Codespaces
  • GitHub Packages
  • Search on GitHub
  • Developers
  • REST API
  • GraphQL API
  • GitHub CLI
  • GitHub Discussions
  • GitHub Sponsors
  • Building communities
  • GitHub Pages
  • Education
  • GitHub Desktop
  • Atom
  • Electron
  • CodeQL
  • npm
    • English
  • English
  • 简体中文 (Simplified Chinese)
  • 日本語 (Japanese)
  • Español (Spanish)
  • Português do Brasil (Portuguese)

    • This version of GitHub Enterprise was discontinued on 2021-09-23. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

    Article version

    In this article

    Apps

    The GitHub Apps API enables you to get high-level information about a GitHub App as well as specific information about installations of the app. To learn more about GitHub Apps, see "Authenticating as a GitHub App."

    This page lists endpoints that you can access while authenticated as a GitHub App. See "Authenticating as a GitHub App" to learn more.

    When authenticated as a GitHub App, the GitHub Apps API enables you to get high-level information about a GitHub App as well as specific information about installations of an app.

    You can access REST API v3 endpoints while authenticated as a GitHub App. These endpoints have a "Notes" section that contains a bullet point that says "Works with GitHub Apps." You can also access these endpoints while authenticated as a user.

    A subset of REST API v3 endpoints requires authenticating as a GitHub App installation. See Installations for a list of these endpoints.

    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 /app

    Code samples

    Shell
    curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/app
    JavaScript (@octokit/core.js)
    await octokit.request('GET /app')

    Response

    Status: 200 OK
    {
  "id": 1,
  "slug": "octoapp",
  "node_id": "MDExOkludGVncmF0aW9uMQ==",
  "owner": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": true
  },
  "name": "Octocat App",
  "description": "",
  "external_url": "https://example.com",
  "html_url": "https://github.com/apps/octoapp",
  "created_at": "2017-07-08T16:18:44-04:00",
  "updated_at": "2017-07-08T16:18:44-04:00",
  "permissions": {
    "metadata": "read",
    "contents": "read",
    "issues": "write",
    "single_file": "write"
  },
  "events": [
    "push",
    "pull_request"
  ]
}

    Notes

    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 /app-manifests/{code}/conversions

    Parameters

    Name Type In Description
    accept string header

    Setting to application/vnd.github.v3+json is recommended.
    code string path

    Code samples

    Shell
    curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/app-manifests/CODE/conversions
    JavaScript (@octokit/core.js)
    await octokit.request('POST /app-manifests/{code}/conversions', {
  code: 'code'
})

    Response

    Status: 201 Created
    {
  "id": 1,
  "slug": "octoapp",
  "node_id": "MDxOkludGVncmF0aW9uMQ==",
  "owner": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": true
  },
  "name": "Octocat App",
  "description": "",
  "external_url": "https://example.com",
  "html_url": "https://github.com/apps/octoapp",
  "created_at": "2017-07-08T16:18:44-04:00",
  "updated_at": "2017-07-08T16:18:44-04:00",
  "permissions": {
    "metadata": "read",
    "contents": "read",
    "issues": "write",
    "single_file": "write"
  },
  "events": [
    "push",
    "pull_request"
  ],
  "client_id": "Iv1.8a61f9b3a7aba766",
  "client_secret": "1726be1638095a19edd134c77bde3aa2ece1e5d8",
  "webhook_secret": "e340154128314309424b7c8e90325147d99fdafa",
  "pem": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAuEPzOUE+kiEH1WLiMeBytTEF856j0hOVcSUSUkZxKvqczkWM\n9vo1gDyC7ZXhdH9fKh32aapba3RSsp4ke+giSmYTk2mGR538ShSDxh0OgpJmjiKP\nX0Bj4j5sFqfXuCtl9SkH4iueivv4R53ktqM+n6hk98l6hRwC39GVIblAh2lEM4L/\n6WvYwuQXPMM5OG2Ryh2tDZ1WS5RKfgq+9ksNJ5Q9UtqtqHkO+E63N5OK9sbzpUUm\noNaOl3udTlZD3A8iqwMPVxH4SxgATBPAc+bmjk6BMJ0qIzDcVGTrqrzUiywCTLma\nszdk8GjzXtPDmuBgNn+o6s02qVGpyydgEuqmTQIDAQABAoIBACL6AvkjQVVLn8kJ\ndBYznJJ4M8ECo+YEgaFwgAHODT0zRQCCgzd+Vxl4YwHmKV2Lr+y2s0drZt8GvYva\nKOK8NYYZyi15IlwFyRXmvvykF1UBpSXluYFDH7KaVroWMgRreHcIys5LqVSIb6Bo\ngDmK0yBLPp8qR29s2b7ScZRtLaqGJiX+j55rNzrZwxHkxFHyG9OG+u9IsBElcKCP\nkYCVE8ZdYexfnKOZbgn2kZB9qu0T/Mdvki8yk3I2bI6xYO24oQmhnT36qnqWoCBX\nNuCNsBQgpYZeZET8mEAUmo9d+ABmIHIvSs005agK8xRaP4+6jYgy6WwoejJRF5yd\nNBuF7aECgYEA50nZ4FiZYV0vcJDxFYeY3kYOvVuKn8OyW+2rg7JIQTremIjv8FkE\nZnwuF9ZRxgqLxUIfKKfzp/5l5LrycNoj2YKfHKnRejxRWXqG+ZETfxxlmlRns0QG\nJ4+BYL0CoanDSeA4fuyn4Bv7cy/03TDhfg/Uq0Aeg+hhcPE/vx3ebPsCgYEAy/Pv\neDLssOSdeyIxf0Brtocg6aPXIVaLdus+bXmLg77rJIFytAZmTTW8SkkSczWtucI3\nFI1I6sei/8FdPzAl62/JDdlf7Wd9K7JIotY4TzT7Tm7QU7xpfLLYIP1bOFjN81rk\n77oOD4LsXcosB/U6s1blPJMZ6AlO2EKs10UuR1cCgYBipzuJ2ADEaOz9RLWwi0AH\nPza2Sj+c2epQD9ZivD7Zo/Sid3ZwvGeGF13JyR7kLEdmAkgsHUdu1rI7mAolXMaB\n1pdrsHureeLxGbRM6za3tzMXWv1Il7FQWoPC8ZwXvMOR1VQDv4nzq7vbbA8z8c+c\n57+8tALQHOTDOgQIzwK61QKBgERGVc0EJy4Uag+VY8J4m1ZQKBluqo7TfP6DQ7O8\nM5MX73maB/7yAX8pVO39RjrhJlYACRZNMbK+v/ckEQYdJSSKmGCVe0JrGYDuPtic\nI9+IGfSorf7KHPoMmMN6bPYQ7Gjh7a++tgRFTMEc8956Hnt4xGahy9NcglNtBpVN\n6G8jAoGBAMCh028pdzJa/xeBHLLaVB2sc0Fe7993WlsPmnVE779dAz7qMscOtXJK\nfgtriltLSSD6rTA9hUAsL/X62rY0wdXuNdijjBb/qvrx7CAV6i37NK1CjABNjsfG\nZM372Ac6zc1EqSrid2IjET1YqyIW2KGLI1R2xbQc98UGlt48OdWu\n-----END RSA PRIVATE KEY-----\n"
}

    Resource not found

    Status: 404 Not Found

    Validation failed

    Status: 422 Unprocessable Entity

    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 /app/installations

    Parameters

    Name Type In Description
    accept string header

    Setting to application/vnd.github.v3+json is recommended.
    per_page integer query

    Results per page (max 100)

    Default: 30
    page integer query

    Page number of the results to fetch.

    Default: 1
    since string query

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

    Code samples

    Shell
    curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/app/installations
    JavaScript (@octokit/core.js)
    await octokit.request('GET /app/installations')

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

    Status: 200 OK
    [
  {
    "id": 1,
    "account": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "access_tokens_url": "https://api.github.com/installations/1/access_tokens",
    "repositories_url": "https://api.github.com/installation/repositories",
    "html_url": "https://github.com/organizations/github/settings/installations/1",
    "app_id": 1,
    "target_id": 1,
    "target_type": "Organization",
    "permissions": {
      "checks": "write",
      "metadata": "read",
      "contents": "read"
    },
    "events": [
      "push",
      "pull_request"
    ],
    "single_file_name": "config.yaml",
    "repository_selection": "selected",
    "created_at": "2017-07-08T16:18:44-04:00",
    "updated_at": "2017-07-08T16:18:44-04:00",
    "app_slug": "github-actions"
  }
]

    Notes

    Get an installation for the authenticated app

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

    You must use a JWT to access this endpoint.

    get /app/installations/{installation_id}

    Parameters

    Name Type In Description
    accept string header

    Setting to application/vnd.github.v3+json is recommended.
    installation_id integer path

    installation_id parameter

    Code samples

    Shell
    curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/app/installations/42
    JavaScript (@octokit/core.js)
    await octokit.request('GET /app/installations/{installation_id}', {
  installation_id: 42
})

    Response

    Status: 200 OK
    {
  "id": 1,
  "account": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "access_tokens_url": "https://api.github.com/installations/1/access_tokens",
  "repositories_url": "https://api.github.com/installation/repositories",
  "html_url": "https://github.com/organizations/github/settings/installations/1",
  "app_id": 1,
  "target_id": 1,
  "target_type": "Organization",
  "permissions": {
    "checks": "write",
    "metadata": "read",
    "contents": "read"
  },
  "events": [
    "push",
    "pull_request"
  ],
  "single_file_name": "config.yaml",
  "repository_selection": "selected",
  "created_at": "2017-07-08T16:18:44-04:00",
  "updated_at": "2017-07-08T16:18:44-04:00",
  "app_slug": "github-actions"
}

    Resource not found

    Status: 404 Not Found

    Preview header missing

    Status: 415 Unsupported Media Type

    Notes

    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 /app/installations/{installation_id}

    Parameters

    Name Type In Description
    accept string header

    Setting to application/vnd.github.v3+json is recommended.
    installation_id integer path

    installation_id parameter

    Code samples

    Shell
    curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/app/installations/42
    JavaScript (@octokit/core.js)
    await octokit.request('DELETE /app/installations/{installation_id}', {
  installation_id: 42
})

    Response

    Status: 204 No Content

    Resource not found

    Status: 404 Not Found

    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 /app/installations/{installation_id}/access_tokens

    Parameters

    Name Type In Description
    accept string header

    Setting to application/vnd.github.v3+json is recommended.
    installation_id integer path

    installation_id parameter
    repositories array of strings body

    List of repository names that the token should have access to
    repository_ids array of integers body

    List of repository IDs that the token should have access to
    permissions object body

    The permissions granted to the user-to-server access token.
    Properties of the permissions object
    actions (string)

    The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts. Can be one of: read or write.
    administration (string)

    The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation. Can be one of: read or write.
    checks (string)

    The level of permission to grant the access token for checks on code. Can be one of: read or write.
    content_references (string)

    The level of permission to grant the access token for notification of content references and creation content attachments. Can be one of: read or write.
    contents (string)

    The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges. Can be one of: read or write.
    deployments (string)

    The level of permission to grant the access token for deployments and deployment statuses. Can be one of: read or write.
    environments (string)

    The level of permission to grant the access token for managing repository environments. Can be one of: read or write.
    issues (string)

    The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones. Can be one of: read or write.
    metadata (string)

    The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata. Can be one of: read or write.
    packages (string)

    The level of permission to grant the access token for packages published to GitHub Packages. Can be one of: read or write.
    pages (string)

    The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds. Can be one of: read or write.
    pull_requests (string)

    The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges. Can be one of: read or write.
    repository_hooks (string)

    The level of permission to grant the access token to manage the post-receive hooks for a repository. Can be one of: read or write.
    repository_projects (string)

    The level of permission to grant the access token to manage repository projects, columns, and cards. Can be one of: read, write, or admin.
    secret_scanning_alerts (string)

    The level of permission to grant the access token to view and manage secret scanning alerts. Can be one of: read or write.
    secrets (string)

    The level of permission to grant the access token to manage repository secrets. Can be one of: read or write.
    security_events (string)

    The level of permission to grant the access token to view and manage security events like code scanning alerts. Can be one of: read or write.
    single_file (string)

    The level of permission to grant the access token to manage just a single file. Can be one of: read or write.
    statuses (string)

    The level of permission to grant the access token for commit statuses. Can be one of: read or write.
    vulnerability_alerts (string)

    The level of permission to grant the access token to retrieve Dependabot alerts. Can be one of: read.
    workflows (string)

    The level of permission to grant the access token to update GitHub Actions workflow files. Can be one of: write.
    members (string)

    The level of permission to grant the access token for organization teams and members. Can be one of: read or write.
    organization_administration (string)

    The level of permission to grant the access token to manage access to an organization. Can be one of: read or write.
    organization_hooks (string)

    The level of permission to grant the access token to manage the post-receive hooks for an organization. Can be one of: read or write.
    organization_plan (string)

    The level of permission to grant the access token for viewing an organization's plan. Can be one of: read.
    organization_projects (string)

    The level of permission to grant the access token to manage organization projects, columns, and cards. Can be one of: read, write, or admin.
    organization_packages (string)

    The level of permission to grant the access token for organization packages published to GitHub Packages. Can be one of: read or write.
    organization_secrets (string)

    The level of permission to grant the access token to manage organization secrets. Can be one of: read or write.
    organization_self_hosted_runners (string)

    The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization. Can be one of: read or write.
    organization_user_blocking (string)

    The level of permission to grant the access token to view and manage users blocked by the organization. Can be one of: read or write.
    team_discussions (string)

    The level of permission to grant the access token to manage team discussions and related comments. Can be one of: read or write.

    Code samples

    Shell
    curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/app/installations/42/access_tokens \
  -d '{"repositories":["repositories"]}'
    JavaScript (@octokit/core.js)
    await octokit.request('POST /app/installations/{installation_id}/access_tokens', {