Explore by product

REST API
English

This version of GitHub Enterprise was discontinued on 2020-11-12. 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: Enterprise Server 2.19
Free, Pro, and Team Enterprise Server 2.22 Enterprise Server 2.21 Enterprise Server 2.20 Enterprise Server 2.19 GitHub AE
Article version: Enterprise Server 2.19
Free, Pro, and Team Enterprise Server 2.22 Enterprise Server 2.21 Enterprise Server 2.20 Enterprise Server 2.19 GitHub AE

Repositories

In this article

List organization repositories

Lists repositories for the specified organization.

get /orgs/{org}/repos

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notices

org string path
type string query

Specifies the types of repositories you want returned. Can be one of all, public, private, forks, sources, member, internal. Default: all. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, type can also be internal.
sort string query

Can be one of created, updated, pushed, full_name.
direction string query

Can be one of asc or desc. Default: when using full_name: asc, otherwise desc
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/repos
JavaScript (@octokit/core.js) 
await octokit.request('GET /orgs/{org}/repos', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "mirror_url": "git:git.example.com/octocat/Hello-World",
    "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "language": null,
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "is_template": true,
    "topics": [
      "octocat",
      "atom",
      "electron",
      "api"
    ],
    "has_issues": true,
    "has_projects": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "archived": false,
    "disabled": false,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    },
    "template_repository": null,
    "subscribers_count": 42,
    "network_count": 0,
    "anonymous_access_enabled": false,
    "license": {
      "key": "mit",
      "name": "MIT License",
      "spdx_id": "MIT",
      "url": "https://api.github.com/licenses/mit",
      "node_id": "MDc6TGljZW5zZW1pdA=="
    }
  }
]

Notes

Preview notices

You can set the visibility of a repository using the new visibility parameter in the Repositories API, and get a repository's visibility with a new response key. For more information, see the blog post.

To access repository visibility during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.nebula-preview+json

The is_template and template_repository keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.baptiste-preview+json

Create an organization repository

Creates a new repository in the specified organization. The authenticated user must be a member of the organization.

OAuth scope requirements

When using OAuth, authorizations must include:

  • public_repo scope or repo scope to create a public repository
  • repo scope to create a private repository
post /orgs/{org}/repos

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notices

org string path
name string body

Required. The name of the repository.
description string body

A short description of the repository.
homepage string body

A URL with more information about the repository.
private boolean body

Either true to create a private repository or false to create a public one.
visibility string body

Can be public or private. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, visibility can also be internal. For more information, see "Creating an internal repository" in the GitHub Help documentation.
The visibility parameter overrides the private parameter when you use both parameters with the nebula-preview preview header.
has_issues boolean body

Either true to enable issues for this repository or false to disable them.

Default: true
has_projects boolean body

Either true to enable projects for this repository or false to disable them. Note: If you're creating a repository in an organization that has disabled repository projects, the default is false, and if you pass true, the API returns an error.

Default: true
has_wiki boolean body

Either true to enable the wiki for this repository or false to disable it.

Default: true
is_template boolean body

Either true to make this repo available as a template repository or false to prevent it.
team_id integer body

The id of the team that will be granted access to this repository. This is only valid when creating a repository in an organization.
auto_init boolean body

Pass true to create an initial commit with empty README.
gitignore_template string body

Desired language or platform .gitignore template to apply. Use the name of the template without the extension. For example, "Haskell".
license_template string body

Choose an open source license template that best suits your needs, and then use the license keyword as the license_template string. For example, "mit" or "mpl-2.0".
allow_squash_merge boolean body

Either true to allow squash-merging pull requests, or false to prevent squash-merging.

Default: true
allow_merge_commit boolean body

Either true to allow merging pull requests with a merge commit, or false to prevent merging pull requests with merge commits.

Default: true
allow_rebase_merge boolean body

Either true to allow rebase-merging pull requests, or false to prevent rebase-merging.

Default: true
delete_branch_on_merge boolean body

Either true to allow automatically deleting head branches when pull requests are merged, or false to prevent automatic deletion.

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/repos \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /orgs/{org}/repos', {
  org: 'org',
  name: 'name'
})

Default response

Status: 201 Created
{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "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
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World",
  "description": "This your first repo!",
  "fork": false,
  "url": "https://api.github.com/repos/octocat/Hello-World",
  "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
  "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
  "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
  "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
  "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
  "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
  "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
  "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
  "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
  "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
  "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
  "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
  "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
  "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
  "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
  "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
  "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
  "git_url": "git:github.com/octocat/Hello-World.git",
  "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
  "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
  "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
  "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
  "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
  "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
  "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
  "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
  "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
  "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
  "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
  "ssh_url": "git@github.com:octocat/Hello-World.git",
  "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
  "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
  "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
  "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
  "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
  "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
  "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "mirror_url": "git:git.example.com/octocat/Hello-World",
  "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
  "svn_url": "https://svn.github.com/octocat/Hello-World",
  "homepage": "https://github.com",
  "forks": 9,
  "forks_count": 9,
  "stargazers_count": 80,
  "watchers_count": 80,
  "watchers": 80,
  "size": 108,
  "default_branch": "master",
  "open_issues": 0,
  "open_issues_count": 0,
  "is_template": true,
  "license": {
    "key": "mit",
    "name": "MIT License",
    "url": "https://api.github.com/licenses/mit",
    "spdx_id": "MIT",
    "node_id": "MDc6TGljZW5zZW1pdA==",
    "html_url": "https://api.github.com/licenses/mit"
  },
  "topics": [
    "octocat",
    "atom",
    "electron",
    "api"
  ],
  "has_issues": true,
  "has_projects": true,
  "has_wiki": true,
  "has_pages": false,
  "has_downloads": true,
  "archived": false,
  "disabled": false,
  "pushed_at": "2011-01-26T19:06:43Z",
  "created_at": "2011-01-26T19:01:12Z",
  "updated_at": "2011-01-26T19:14:43Z",
  "permissions": {
    "admin": false,
    "push": false,
    "pull": true
  },
  "allow_rebase_merge": true,
  "allow_squash_merge": true,
  "allow_merge_commit": true,
  "subscribers_count": 42,
  "network_count": 0,
  "anonymous_access_enabled": false
}

Forbidden

Status: 403 Forbidden

Validation failed

Status: 422 Unprocessable Entity

Notes

Preview notices

You can set the visibility of a repository using the new visibility parameter in the Repositories API, and get a repository's visibility with a new response key. For more information, see the blog post.

To access repository visibility during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.nebula-preview+json

The is_template and template_repository keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.baptiste-preview+json

Get a repository

When you pass the scarlet-witch-preview media type, requests to get a repository will also return the repository's code of conduct if it can be detected from the repository's code of conduct file.

The parent and source objects are present when the repository is a fork. parent is the repository this repository was forked from, source is the ultimate source for the network.

get /repos/{owner}/{repo}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notices

owner string path
repo string path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "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
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World",
  "description": "This your first repo!",
  "fork": false,
  "url": "https://api.github.com/repos/octocat/Hello-World",
  "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
  "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
  "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
  "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
  "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
  "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
  "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
  "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
  "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
  "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
  "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
  "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
  "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
  "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
  "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
  "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
  "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
  "git_url": "git:github.com/octocat/Hello-World.git",
  "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
  "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
  "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
  "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
  "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
  "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
  "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
  "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
  "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
  "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
  "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
  "ssh_url": "git@github.com:octocat/Hello-World.git",
  "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
  "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
  "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
  "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
  "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
  "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
  "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "mirror_url": "git:git.example.com/octocat/Hello-World",
  "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
  "svn_url": "https://svn.github.com/octocat/Hello-World",
  "homepage": "https://github.com",
  "forks_count": 9,
  "forks": 9,
  "stargazers_count": 80,
  "watchers_count": 80,
  "watchers": 80,
  "size": 108,
  "default_branch": "master",
  "open_issues_count": 0,
  "open_issues": 0,
  "is_template": true,
  "topics": [
    "octocat",
    "atom",
    "electron",
    "api"
  ],
  "has_issues": true,
  "has_projects": true,
  "has_wiki": true,
  "has_pages": false,
  "has_downloads": true,
  "archived": false,
  "disabled": false,
  "pushed_at": "2011-01-26T19:06:43Z",
  "created_at": "2011-01-26T19:01:12Z",
  "updated_at": "2011-01-26T19:14:43Z",
  "permissions": {
    "pull": true,
    "push": false,
    "admin": false
  },
  "allow_rebase_merge": true,
  "allow_squash_merge": true,
  "allow_merge_commit": true,
  "subscribers_count": 42,
  "network_count": 0,
  "license": {
    "key": "mit",
    "name": "MIT License",
    "spdx_id": "MIT",
    "url": "https://api.github.com/licenses/mit",
    "node_id": "MDc6TGljZW5zZW1pdA=="
  },
  "organization": {
    "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": "Organization",
    "site_admin": false
  },
  "parent": {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "mirror_url": "git:git.example.com/octocat/Hello-World",
    "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "is_template": true,
    "topics": [
      "octocat",
      "atom",
      "electron",
      "api"
    ],
    "has_issues": true,
    "has_projects": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "archived": false,
    "disabled": false,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    },
    "allow_rebase_merge": true,
    "allow_squash_merge": true,
    "allow_merge_commit": true,
    "subscribers_count": 42,
    "network_count": 0,
    "license": {
      "key": "mit",
      "name": "MIT License",
      "url": "https://api.github.com/licenses/mit",
      "spdx_id": "MIT",
      "node_id": "MDc6TGljZW5zZW1pdA==",
      "html_url": "https://api.github.com/licenses/mit"
    },
    "forks": 1,
    "open_issues": 1,
    "watchers": 1,
    "anonymous_access_enabled": false
  },
  "source": {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "mirror_url": "git:git.example.com/octocat/Hello-World",
    "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "is_template": true,
    "topics": [
      "octocat",
      "atom",
      "electron",
      "api"
    ],
    "has_issues": true,
    "has_projects": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "archived": false,
    "disabled": false,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    },
    "allow_rebase_merge": true,
    "allow_squash_merge": true,
    "allow_merge_commit": true,
    "subscribers_count": 42,
    "network_count": 0,
    "license": {
      "key": "mit",
      "name": "MIT License",
      "url": "https://api.github.com/licenses/mit",
      "spdx_id": "MIT",
      "node_id": "MDc6TGljZW5zZW1pdA==",
      "html_url": "https://api.github.com/licenses/mit"
    },
    "forks": 1,
    "open_issues": 1,
    "watchers": 1,
    "anonymous_access_enabled": false
  },
  "anonymous_access_enabled": false
}

Response with scarlet-witch-preview media type

Status: 200 OK
{
  "id": 88760408,
  "node_id": "MDEwOlJlcG9zaXRvcnk4ODc2MDQwOA==",
  "name": "cosee",
  "full_name": "LindseyB/cosee",
  "disabled": false,
  "archived": false,
  "owner": {
    "login": "LindseyB",
    "id": 33750,
    "node_id": "MDQ6VXNlcjMzNzUw",
    "avatar_url": "https://avatars2.githubusercontent.com/u/33750?v=3",
    "gravatar_id": "",
    "url": "https://api.github.com/users/LindseyB",
    "html_url": "https://github.com/LindseyB",
    "followers_url": "https://api.github.com/users/LindseyB/followers",
    "following_url": "https://api.github.com/users/LindseyB/following{/other_user}",
    "gists_url": "https://api.github.com/users/LindseyB/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/LindseyB/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/LindseyB/subscriptions",
    "organizations_url": "https://api.github.com/users/LindseyB/orgs",
    "repos_url": "https://api.github.com/users/LindseyB/repos",
    "events_url": "https://api.github.com/users/LindseyB/events{/privacy}",
    "received_events_url": "https://api.github.com/users/LindseyB/received_events",
    "type": "User",
    "site_admin": true
  },
  "private": false,
  "html_url": "https://github.com/LindseyB/cosee",
  "description": null,
  "fork": false,
  "license": {
    "key": "mit",
    "name": "MIT License",
    "url": "https://api.github.com/licenses/mit",
    "spdx_id": "MIT",
    "node_id": "MDc6TGljZW5zZW1pdA==",
    "html_url": "https://github.com/licenses/mit"
  },
  "url": "https://api.github.com/repos/LindseyB/cosee",
  "forks_url": "https://api.github.com/repos/LindseyB/cosee/forks",
  "keys_url": "https://api.github.com/repos/LindseyB/cosee/keys{/key_id}",
  "collaborators_url": "https://api.github.com/repos/LindseyB/cosee/collaborators{/collaborator}",
  "teams_url": "https://api.github.com/repos/LindseyB/cosee/teams",
  "hooks_url": "https://api.github.com/repos/LindseyB/cosee/hooks",
  "issue_events_url": "https://api.github.com/repos/LindseyB/cosee/issues/events{/number}",
  "events_url": "https://api.github.com/repos/LindseyB/cosee/events",
  "assignees_url": "https://api.github.com/repos/LindseyB/cosee/assignees{/user}",
  "branches_url": "https://api.github.com/repos/LindseyB/cosee/branches{/branch}",
  "tags_url": "https://api.github.com/repos/LindseyB/cosee/tags",
  "blobs_url": "https://api.github.com/repos/LindseyB/cosee/git/blobs{/sha}",
  "git_tags_url": "https://api.github.com/repos/LindseyB/cosee/git/tags{/sha}",
  "git_refs_url": "https://api.github.com/repos/LindseyB/cosee/git/refs{/sha}",
  "trees_url": "https://api.github.com/repos/LindseyB/cosee/git/trees{/sha}",
  "statuses_url": "https://api.github.com/repos/LindseyB/cosee/statuses/{sha}",
  "languages_url": "https://api.github.com/repos/LindseyB/cosee/languages",
  "stargazers_url": "https://api.github.com/repos/LindseyB/cosee/stargazers",
  "contributors_url": "https://api.github.com/repos/LindseyB/cosee/contributors",
  "subscribers_url": "https://api.github.com/repos/LindseyB/cosee/subscribers",
  "subscription_url": "https://api.github.com/repos/LindseyB/cosee/subscription",
  "commits_url": "https://api.github.com/repos/LindseyB/cosee/commits{/sha}",
  "git_commits_url": "https://api.github.com/repos/LindseyB/cosee/git/commits{/sha}",
  "comments_url": "https://api.github.com/repos/LindseyB/cosee/comments{/number}",
  "issue_comment_url": "https://api.github.com/repos/LindseyB/cosee/issues/comments{/number}",
  "contents_url": "https://api.github.com/repos/LindseyB/cosee/contents/{+path}",
  "compare_url": "https://api.github.com/repos/LindseyB/cosee/compare/{base}...{head}",
  "merges_url": "https://api.github.com/repos/LindseyB/cosee/merges",
  "archive_url": "https://api.github.com/repos/LindseyB/cosee/{archive_format}{/ref}",
  "downloads_url": "https://api.github.com/repos/LindseyB/cosee/downloads",
  "issues_url": "https://api.github.com/repos/LindseyB/cosee/issues{/number}",
  "pulls_url": "https://api.github.com/repos/LindseyB/cosee/pulls{/number}",
  "milestones_url": "https://api.github.com/repos/LindseyB/cosee/milestones{/number}",
  "notifications_url": "https://api.github.com/repos/LindseyB/cosee/notifications{?since,all,participating}",
  "labels_url": "https://api.github.com/repos/LindseyB/cosee/labels{/name}",
  "releases_url": "https://api.github.com/repos/LindseyB/cosee/releases{/id}",
  "deployments_url": "https://api.github.com/repos/LindseyB/cosee/deployments",
  "pushed_at": "2011-01-26T19:06:43Z",
  "created_at": "2011-01-26T19:01:12Z",
  "updated_at": "2011-01-26T19:14:43Z",
  "git_url": "git://github.com/LindseyB/cosee.git",
  "ssh_url": "git@github.com=>LindseyB/cosee.git",
  "clone_url": "https://github.com/LindseyB/cosee.git",
  "svn_url": "https://github.com/LindseyB/cosee",
  "homepage": null,
  "size": 1,
  "stargazers_count": 0,
  "watchers_count": 0,
  "language": null,
  "has_issues": true,
  "has_projects": true,
  "has_downloads": true,
  "has_wiki": true,
  "has_pages": false,
  "forks_count": 0,
  "mirror_url": null,
  "open_issues_count": 0,
  "forks": 0,
  "open_issues": 0,
  "watchers": 0,
  "default_branch": "master",
  "network_count": 0,
  "subscribers_count": 0
}

Moved permanently

Status: 301 Moved Permanently

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Notes

Preview notices

You can set the visibility of a repository using the new visibility parameter in the Repositories API, and get a repository's visibility with a new response key. For more information, see the blog post.

To access repository visibility during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.nebula-preview+json

The Codes of Conduct API is currently available for developers to preview.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.scarlet-witch-preview+json

Update a repository

Note: To edit a repository's topics, use the Replace all repository topics endpoint.

patch /repos/{owner}/{repo}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notices

owner string path
repo string path
name string body

The name of the repository.
description string body

A short description of the repository.
homepage string body

A URL with more information about the repository.
private boolean body

Either true to make the repository private or false to make it public. Default: false.
Note: You will get a 422 error if the organization restricts changing repository visibility to organization owners and a non-owner tries to change the value of private. Note: You will get a 422 error if the organization restricts changing repository visibility to organization owners and a non-owner tries to change the value of private.
visibility string body

Can be public or private. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, visibility can also be internal. The visibility parameter overrides the private parameter when you use both along with the nebula-preview preview header.
has_issues boolean body

Either true to enable issues for this repository or false to disable them.

Default: true
has_projects boolean body

Either true to enable projects for this repository or false to disable them. Note: If you're creating a repository in an organization that has disabled repository projects, the default is false, and if you pass true, the API returns an error.

Default: true
has_wiki boolean body

Either true to enable the wiki for this repository or false to disable it.

Default: true
is_template boolean body

Either true to make this repo available as a template repository or false to prevent it.
default_branch string body

Updates the default branch for this repository.
allow_squash_merge boolean body

Either true to allow squash-merging pull requests, or false to prevent squash-merging.

Default: true
allow_merge_commit boolean body

Either true to allow merging pull requests with a merge commit, or false to prevent merging pull requests with merge commits.

Default: true
allow_rebase_merge boolean body

Either true to allow rebase-merging pull requests, or false to prevent rebase-merging.

Default: true
delete_branch_on_merge boolean body

Either true to allow automatically deleting head branches when pull requests are merged, or false to prevent automatic deletion.
archived boolean body

true to archive this repository. Note: You cannot unarchive repositories through the API.

Code samples

Shell 
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js) 
await octokit.request('PATCH /repos/{owner}/{repo}', {
  owner: 'octocat',
  repo: 'hello-world',
  name: 'name'
})

Default response

Status: 200 OK
{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "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
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World",
  "description": "This your first repo!",
  "fork": false,
  "url": "https://api.github.com/repos/octocat/Hello-World",
  "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
  "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
  "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
  "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
  "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
  "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
  "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
  "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
  "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
  "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
  "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
  "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
  "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
  "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
  "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
  "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
  "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
  "git_url": "git:github.com/octocat/Hello-World.git",
  "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
  "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
  "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
  "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
  "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
  "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
  "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
  "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
  "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
  "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
  "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
  "ssh_url": "git@github.com:octocat/Hello-World.git",
  "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
  "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
  "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
  "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
  "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
  "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
  "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "mirror_url": "git:git.example.com/octocat/Hello-World",
  "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
  "svn_url": "https://svn.github.com/octocat/Hello-World",
  "homepage": "https://github.com",
  "license": {
    "key": "mit",
    "name": "MIT License",
    "url": "https://api.github.com/licenses/mit",
    "spdx_id": "MIT",
    "node_id": "MDc6TGljZW5zZW1pdA==",
    "html_url": "https://github.com/licenses/mit"
  },
  "forks_count": 9,
  "forks": 9,
  "stargazers_count": 80,
  "watchers_count": 80,
  "watchers": 80,
  "size": 108,
  "default_branch": "master",
  "open_issues_count": 0,
  "open_issues": 0,
  "is_template": true,
  "topics": [
    "octocat",
    "atom",
    "electron",
    "api"
  ],
  "has_issues": true,
  "has_projects": true,
  "has_wiki": true,
  "has_pages": false,
  "has_downloads": true,
  "archived": false,
  "disabled": false,
  "pushed_at": "2011-01-26T19:06:43Z",
  "created_at": "2011-01-26T19:01:12Z",
  "updated_at": "2011-01-26T19:14:43Z",
  "permissions": {
    "pull": true,
    "push": false,
    "admin": false
  },
  "allow_rebase_merge": true,
  "allow_squash_merge": true,
  "allow_merge_commit": true,
  "subscribers_count": 42,
  "network_count": 0,
  "organization": {
    "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": "Organization",
    "site_admin": false
  },
  "parent": {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "mirror_url": "git:git.example.com/octocat/Hello-World",
    "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "is_template": true,
    "topics": [
      "octocat",
      "atom",
      "electron",
      "api"
    ],
    "has_issues": true,
    "has_projects": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "archived": false,
    "disabled": false,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    },
    "allow_rebase_merge": true,
    "allow_squash_merge": true,
    "allow_merge_commit": true,
    "subscribers_count": 42,
    "network_count": 0,
    "license": {
      "key": "mit",
      "name": "MIT License",
      "url": "https://api.github.com/licenses/mit",
      "spdx_id": "MIT",
      "node_id": "MDc6TGljZW5zZW1pdA==",
      "html_url": "https://api.github.com/licenses/mit"
    },
    "forks": 1,
    "open_issues": 1,
    "watchers": 1,
    "anonymous_access_enabled": false
  },
  "source": {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "mirror_url": "git:git.example.com/octocat/Hello-World",
    "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "is_template": true,
    "topics": [
      "octocat",
      "atom",
      "electron",
      "api"
    ],
    "has_issues": true,
    "has_projects": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "archived": false,
    "disabled": false,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    },
    "allow_rebase_merge": true,
    "allow_squash_merge": true,
    "allow_merge_commit": true,
    "subscribers_count": 42,
    "network_count": 0,
    "license": {
      "key": "mit",
      "name": "MIT License",
      "url": "https://api.github.com/licenses/mit",
      "spdx_id": "MIT",
      "node_id": "MDc6TGljZW5zZW1pdA==",
      "html_url": "https://api.github.com/licenses/mit"
    },
    "forks": 1,
    "open_issues": 1,
    "watchers": 1,
    "anonymous_access_enabled": false
  },
  "anonymous_access_enabled": false
}

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes

Preview notices

You can set the visibility of a repository using the new visibility parameter in the Repositories API, and get a repository's visibility with a new response key. For more information, see the blog post.

To access repository visibility during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.nebula-preview+json

The is_template and template_repository keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.baptiste-preview+json

Delete a repository

Deleting a repository requires admin access. If OAuth is used, the delete_repo scope is required.

If an organization owner has configured the organization to prevent members from deleting organization-owned repositories, you will get a 403 Forbidden response.

delete /repos/{owner}/{repo}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default Response

Status: 204 No Content

If an organization owner has configured the organization to prevent members from deleting organization owned repositories a member will get this response

Status: 403 Forbidden
{
  "message": "Organization members cannot delete repositories.",
  "documentation_url": "https://docs.github.com/enterprise-server@2.19/rest/reference/repos#delete-a-repository"
}

Resource not found

Status: 404 Not Found

Notes

List repository contributors

Lists contributors to the specified repository and sorts them by the number of commits per contributor in descending order. This endpoint may return information that is a few hours old because the GitHub REST API v3 caches contributor data to improve performance.

GitHub identifies contributors by author email address. This endpoint groups contribution counts by GitHub user, which includes all associated email addresses. To improve performance, only the first 500 author email addresses in the repository link to GitHub users. The rest will appear as anonymous contributors without associated GitHub user information.

get /repos/{owner}/{repo}/contributors

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
anon string query

Set to 1 or true to include anonymous contributors in results.
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/contributors
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/contributors', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response if repository contains content

Status: 200 OK
[
  {
    "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,
    "contributions": 32
  }
]

Response if repository is empty

Status: 204 No Content

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Notes

List repository languages

Lists languages for the specified repository. The value shown for each language is the number of bytes of code written in that language.

get /repos/{owner}/{repo}/languages

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/languages
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/languages', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
{
  "C": 78769,
  "Python": 7769
}

Notes

get /repos/{owner}/{repo}/tags

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/tags
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/tags', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
[
  {
    "name": "v0.1",
    "commit": {
      "sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc",
      "url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
    },
    "zipball_url": "https://github.com/octocat/Hello-World/zipball/v0.1",
    "tarball_url": "https://github.com/octocat/Hello-World/tarball/v0.1",
    "node_id": "MDQ6VXNlcjE="
  }
]

Notes

get /repos/{owner}/{repo}/teams

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/teams
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/teams', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/teams/1",
    "html_url": "https://api.github.com/teams/justice-league",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "privacy": "closed",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos",
    "parent": null
  }
]

Notes

get /repos/{owner}/{repo}/topics

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.mercy-preview+json" \
  https://api.github.com/repos/octocat/hello-world/topics
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/topics', {
  owner: 'octocat',
  repo: 'hello-world',
  mediaType: {
    previews: [
      'mercy'
    ]
  }
})

Default response

Status: 200 OK
{
  "names": [
    "octocat",
    "atom",
    "electron",
    "api"
  ]
}

Resource not found

Status: 404 Not Found

Preview header missing

Status: 415 Unsupported Media Type

Notes

Preview notice

The topics property for repositories on GitHub is currently available for developers to preview. To view the topics property in calls that return repository results, you must provide a custom media type in the Accept header:

application/vnd.github.mercy-preview+json
☝️ This header is required. 
put /repos/{owner}/{repo}/topics

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
names array of strings body

Required. An array of topics to add to the repository. Pass one or more topics to replace the set of existing topics. Send an empty array ([]) to clear all topics from the repository. Note: Topic names cannot contain uppercase letters.

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.mercy-preview+json" \
  https://api.github.com/repos/octocat/hello-world/topics \
  -d '{"names":["names"]}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/topics', {
  owner: 'octocat',
  repo: 'hello-world',
  names: [
    'names'
  ],
  mediaType: {
    previews: [
      'mercy'
    ]
  }
})

Default response

Status: 200 OK
{
  "names": [
    "octocat",
    "atom",
    "electron",
    "api"
  ]
}

Resource not found

Status: 404 Not Found

Preview header missing

Status: 415 Unsupported Media Type

Validation failed

Status: 422 Unprocessable Entity

Notes

Preview notice

The topics property for repositories on GitHub is currently available for developers to preview. To view the topics property in calls that return repository results, you must provide a custom media type in the Accept header:

application/vnd.github.mercy-preview+json
☝️ This header is required.

Transfer a repository

A transfer request will need to be accepted by the new owner when transferring a personal repository to another user. The response will contain the original owner, and the transfer will continue asynchronously. For more details on the requirements to transfer personal and organization-owned repositories, see about repository transfers.

post /repos/{owner}/{repo}/transfer

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
new_owner string body

Required: The username or organization name the repository will be transferred to.
team_ids array of integers body

ID of the team or teams to add to the repository. Teams can only be added to organization-owned repositories.

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/transfer \
  -d '{"new_owner":"new_owner"}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/transfer', {
  owner: 'octocat',
  repo: 'hello-world',
  new_owner: 'new_owner'
})

Default response

Status: 202 Accepted
{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "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
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World",
  "description": "This your first repo!",
  "fork": false,
  "url": "https://api.github.com/repos/octocat/Hello-World",
  "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
  "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
  "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
  "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
  "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
  "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
  "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
  "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
  "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
  "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
  "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
  "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
  "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
  "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
  "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
  "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
  "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
  "git_url": "git:github.com/octocat/Hello-World.git",
  "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
  "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
  "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
  "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
  "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
  "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
  "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
  "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
  "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
  "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
  "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
  "ssh_url": "git@github.com:octocat/Hello-World.git",
  "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
  "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
  "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
  "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
  "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
  "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
  "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "mirror_url": "git:git.example.com/octocat/Hello-World",
  "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
  "svn_url": "https://svn.github.com/octocat/Hello-World",
  "homepage": "https://github.com",
  "forks": 9,
  "forks_count": 9,
  "stargazers_count": 80,
  "watchers_count": 80,
  "watchers": 80,
  "size": 108,
  "default_branch": "master",
  "open_issues": 0,
  "open_issues_count": 0,
  "is_template": true,
  "license": {
    "key": "mit",
    "name": "MIT License",
    "url": "https://api.github.com/licenses/mit",
    "spdx_id": "MIT",
    "node_id": "MDc6TGljZW5zZW1pdA==",
    "html_url": "https://api.github.com/licenses/mit"
  },
  "topics": [
    "octocat",
    "atom",
    "electron",
    "api"
  ],
  "has_issues": true,
  "has_projects": true,
  "has_wiki": true,
  "has_pages": false,
  "has_downloads": true,
  "archived": false,
  "disabled": false,
  "pushed_at": "2011-01-26T19:06:43Z",
  "created_at": "2011-01-26T19:01:12Z",
  "updated_at": "2011-01-26T19:14:43Z",
  "permissions": {
    "admin": false,
    "push": false,
    "pull": true
  },
  "allow_rebase_merge": true,
  "allow_squash_merge": true,
  "allow_merge_commit": true,
  "subscribers_count": 42,
  "network_count": 0,
  "anonymous_access_enabled": false
}

Notes

Enable vulnerability alerts

Enables dependency alerts and the dependency graph for a repository. The authenticated user must have admin access to the repository. For more information, see "About security alerts for vulnerable dependencies".

put /repos/{owner}/{repo}/vulnerability-alerts

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.dorian-preview+json" \
  https://api.github.com/repos/octocat/hello-world/vulnerability-alerts
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/vulnerability-alerts', {
  owner: 'octocat',
  repo: 'hello-world',
  mediaType: {
    previews: [
      'dorian'
    ]
  }
})

Default Response

Status: 204 No Content

Notes

Preview notice

Enabling and disabling dependency alerts for a repository using the REST API is currently available for developers to preview. To access these new endpoints during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.dorian-preview+json
☝️ This header is required.

Disable vulnerability alerts

Disables dependency alerts and the dependency graph for a repository. The authenticated user must have admin access to the repository. For more information, see "About security alerts for vulnerable dependencies".

delete /repos/{owner}/{repo}/vulnerability-alerts

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.dorian-preview+json" \
  https://api.github.com/repos/octocat/hello-world/vulnerability-alerts
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/vulnerability-alerts', {
  owner: 'octocat',
  repo: 'hello-world',
  mediaType: {
    previews: [
      'dorian'
    ]
  }
})

Default Response

Status: 204 No Content

Notes

Preview notice

Enabling and disabling dependency alerts for a repository using the REST API is currently available for developers to preview. To access these new endpoints during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.dorian-preview+json
☝️ This header is required.

Create a repository using a template

Creates a new repository using a repository template. Use the template_owner and template_repo route parameters to specify the repository to use as the template. The authenticated user must own or be a member of an organization that owns the repository. To check if a repository is available to use as a template, get the repository's information using the Get a repository endpoint and check that the is_template key is true.

OAuth scope requirements

When using OAuth, authorizations must include:

  • public_repo scope or repo scope to create a public repository
  • repo scope to create a private repository
post /repos/{template_owner}/{template_repo}/generate

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

template_owner string path
template_repo string path
owner string body

The organization or person who will own the new repository. To create a new repository in an organization, the authenticated user must be a member of the specified organization.
name string body

Required. The name of the new repository.
description string body

A short description of the new repository.
include_all_branches boolean body

Set to true to include the directory structure and files from all branches in the template repository, and not just the default branch. Default: false.
private boolean body

Either true to create a new private repository or false to create a new public one.

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.baptiste-preview+json" \
  https://api.github.com/repos/TEMPLATE_OWNER/TEMPLATE_REPO/generate \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{template_owner}/{template_repo}/generate', {
  template_owner: 'template_owner',
  template_repo: 'template_repo',
  name: 'name',
  mediaType: {
    previews: [
      'baptiste'
    ]
  }
})

Default response

Status: 201 Created
{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "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
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World",
  "description": "This your first repo!",
  "fork": false,
  "url": "https://api.github.com/repos/octocat/Hello-World",
  "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
  "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
  "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
  "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
  "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
  "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
  "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
  "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
  "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
  "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
  "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
  "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
  "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
  "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
  "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
  "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
  "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
  "git_url": "git:github.com/octocat/Hello-World.git",
  "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
  "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
  "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
  "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
  "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
  "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
  "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
  "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
  "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
  "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
  "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
  "ssh_url": "git@github.com:octocat/Hello-World.git",
  "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
  "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
  "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
  "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
  "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
  "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
  "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "mirror_url": "git:git.example.com/octocat/Hello-World",
  "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
  "svn_url": "https://svn.github.com/octocat/Hello-World",
  "homepage": "https://github.com",
  "forks_count": 9,
  "forks": 9,
  "stargazers_count": 80,
  "watchers_count": 80,
  "watchers": 80,
  "size": 108,
  "default_branch": "master",
  "open_issues_count": 0,
  "open_issues": 0,
  "is_template": false,
  "topics": [
    "octocat",
    "atom",
    "electron",
    "api"
  ],
  "has_issues": true,
  "has_projects": true,
  "has_wiki": true,
  "has_pages": false,
  "has_downloads": true,
  "archived": false,
  "disabled": false,
  "pushed_at": "2011-01-26T19:06:43Z",
  "created_at": "2011-01-26T19:01:12Z",
  "updated_at": "2011-01-26T19:14:43Z",
  "permissions": {
    "admin": false,
    "push": false,
    "pull": true
  },
  "allow_rebase_merge": true,
  "license": {
    "key": "mit",
    "name": "MIT License",
    "url": "https://api.github.com/licenses/mit",
    "spdx_id": "MIT",
    "node_id": "MDc6TGljZW5zZW1pdA==",
    "html_url": "https://github.com/licenses/mit"
  },
  "anonymous_access_enabled": false,
  "template_repository": {
    "anonymous_access_enabled": false
  }
}

Preview notice

Creating and using repository templates is currently available for developers to preview. To access this new endpoint during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.baptiste-preview+json
☝️ This header is required.

List public repositories

Lists all public repositories in the order that they were created.

Note: Pagination is powered exclusively by the since parameter. Use the Link header to get the URL for the next page of repositories.

get /repositories

Parameters

Name Type In Description
accept string header

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

since integer query

A repository ID. Only return repositories with an ID greater than this ID.
visibility string query

Specifies the types of repositories to return. Can be one of all or public. Default: public.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repositories
JavaScript (@octokit/core.js) 
await octokit.request('GET /repositories')

Default response

Status: 200 OK
[
  {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks"
  }
]

Not modified

Status: 304 Not Modified

Validation failed

Status: 422 Unprocessable Entity

Notes

List repositories for the authenticated user

Lists repositories that the authenticated user has explicit permission (:read, :write, or :admin) to access.

The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.

get /user/repos

Parameters

Name Type In Description
accept string header

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

visibility string query

Can be one of all, public, or private.
affiliation string query

Comma-separated list of values. Can include:
* owner: Repositories that are owned by the authenticated user.
* collaborator: Repositories that the user has been added to as a collaborator.
* organization_member: Repositories that the user has access to through being a member of an organization. This includes every repository on every team that the user is on.
type string query

Can be one of all, owner, public, private, member. Default: all

Will cause a 422 error if used in the same request as visibility or affiliation. Will cause a 422 error if used in the same request as visibility or affiliation.
sort string query

Can be one of created, updated, pushed, full_name.
direction string query

Can be one of asc or desc. Default: asc when using full_name, otherwise desc
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.
since string query

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

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

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/repos
JavaScript (@octokit/core.js) 
await octokit.request('GET /user/repos')

Default response

Status: 200 OK
[
  {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "mirror_url": "git:git.example.com/octocat/Hello-World",
    "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "language": null,
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "is_template": true,
    "topics": [
      "octocat",
      "atom",
      "electron",
      "api"
    ],
    "has_issues": true,
    "has_projects": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "archived": false,
    "disabled": false,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    },
    "allow_rebase_merge": true,
    "template_repository": null,
    "allow_squash_merge": true,
    "allow_merge_commit": true,
    "subscribers_count": 42,
    "network_count": 0,
    "anonymous_access_enabled": false
  }
]

Not modified

Status: 304 Not Modified

Requires authentication

Status: 401 Unauthorized

Forbidden

Status: 403 Forbidden

Response definition missing

Status: 418 I'm A Teapot

Validation failed

Status: 422 Unprocessable Entity

Create a repository for the authenticated user

Creates a new repository for the authenticated user.

OAuth scope requirements

When using OAuth, authorizations must include:

  • public_repo scope or repo scope to create a public repository
  • repo scope to create a private repository
post /user/repos

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notices

name string body

Required. The name of the repository.
description string body

A short description of the repository.
homepage string body

A URL with more information about the repository.
private boolean body

Whether the repository is private or public.
has_issues boolean body

Whether issues are enabled.

Default: true
has_projects boolean body

Whether projects are enabled.

Default: true
has_wiki boolean body

Whether the wiki is enabled.

Default: true
team_id integer body

The id of the team that will be granted access to this repository. This is only valid when creating a repository in an organization.
auto_init boolean body

Whether the repository is initialized with a minimal README.
gitignore_template string body

The desired language or platform to apply to the .gitignore.
license_template string body

The license keyword of the open source license for this repository.
allow_squash_merge boolean body

Whether to allow squash merges for pull requests.

Default: true
allow_merge_commit boolean body

Whether to allow merge commits for pull requests.

Default: true
allow_rebase_merge boolean body

Whether to allow rebase merges for pull requests.

Default: true
delete_branch_on_merge boolean body

Whether to delete head branches when pull requests are merged
has_downloads boolean body

Whether downloads are enabled.

Default: true
is_template boolean body

Whether this repository acts as a template that can be used to generate new repositories.

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/repos \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /user/repos', {
  name: 'name'
})

Default response

Status: 201 Created
{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "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
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World",
  "description": "This your first repo!",
  "fork": false,
  "url": "https://api.github.com/repos/octocat/Hello-World",
  "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
  "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
  "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
  "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
  "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
  "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
  "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
  "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
  "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
  "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
  "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
  "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
  "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
  "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
  "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
  "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
  "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
  "git_url": "git:github.com/octocat/Hello-World.git",
  "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
  "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
  "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
  "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
  "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
  "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
  "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
  "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
  "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
  "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
  "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
  "ssh_url": "git@github.com:octocat/Hello-World.git",
  "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
  "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
  "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
  "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
  "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
  "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
  "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "mirror_url": "git:git.example.com/octocat/Hello-World",
  "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
  "svn_url": "https://svn.github.com/octocat/Hello-World",
  "homepage": "https://github.com",
  "forks": 9,
  "forks_count": 9,
  "stargazers_count": 80,
  "watchers_count": 80,
  "watchers": 80,
  "size": 108,
  "default_branch": "master",
  "open_issues": 0,
  "open_issues_count": 0,
  "is_template": true,
  "license": {
    "key": "mit",
    "name": "MIT License",
    "url": "https://api.github.com/licenses/mit",
    "spdx_id": "MIT",
    "node_id": "MDc6TGljZW5zZW1pdA==",
    "html_url": "https://api.github.com/licenses/mit"
  },
  "topics": [
    "octocat",
    "atom",
    "electron",
    "api"
  ],
  "has_issues": true,
  "has_projects": true,
  "has_wiki": true,
  "has_pages": false,
  "has_downloads": true,
  "archived": false,
  "disabled": false,
  "pushed_at": "2011-01-26T19:06:43Z",
  "created_at": "2011-01-26T19:01:12Z",
  "updated_at": "2011-01-26T19:14:43Z",
  "permissions": {
    "admin": false,
    "push": false,
    "pull": true
  },
  "allow_rebase_merge": true,
  "allow_squash_merge": true,
  "allow_merge_commit": true,
  "subscribers_count": 42,
  "network_count": 0,
  "anonymous_access_enabled": false
}

Not modified

Status: 304 Not Modified

Bad request

Status: 400 Bad Request

Requires authentication

Status: 401 Unauthorized

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Preview notices

You can set the visibility of a repository using the new visibility parameter in the Repositories API, and get a repository's visibility with a new response key. For more information, see the blog post.

To access repository visibility during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.nebula-preview+json

The is_template and template_repository keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.baptiste-preview+json

List repositories for a user

Lists public repositories for the specified user.

get /users/{username}/repos

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

username string path
type string query

Can be one of all, owner, member.
sort string query

Can be one of created, updated, pushed, full_name.
direction string query

Can be one of asc or desc. Default: asc when using full_name, otherwise desc
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/repos
JavaScript (@octokit/core.js) 
await octokit.request('GET /users/{username}/repos', {
  username: 'username'
})

Default response

Status: 200 OK
[
  {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "mirror_url": "git:git.example.com/octocat/Hello-World",
    "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "language": null,
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "is_template": true,
    "topics": [
      "octocat",
      "atom",
      "electron",
      "api"
    ],
    "has_issues": true,
    "has_projects": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "archived": false,
    "disabled": false,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    },
    "template_repository": null,
    "subscribers_count": 42,
    "network_count": 0,
    "anonymous_access_enabled": false,
    "license": {
      "key": "mit",
      "name": "MIT License",
      "spdx_id": "MIT",
      "url": "https://api.github.com/licenses/mit",
      "node_id": "MDc6TGljZW5zZW1pdA=="
    }
  }
]

Notes

Preview notice

You can set the visibility of a repository using the new visibility parameter in the Repositories API, and get a repository's visibility with a new response key. For more information, see the blog post.

To access repository visibility during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.nebula-preview+json

Branches

get /repos/{owner}/{repo}/branches

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
protected boolean query

Setting to true returns only protected branches. When set to false, only unprotected branches are returned. Omitting this parameter returns all branches.
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
[
  {
    "name": "master",
    "commit": {
      "sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc",
      "url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
    },
    "protected": true
  }
]

With protection

Status: 200 OK
[
  {
    "name": "master",
    "commit": {
      "sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc",
      "url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
    },
    "protected": true,
    "protection": {
      "enabled": true,
      "required_status_checks": {
        "enforcement_level": "non_admins",
        "contexts": [
          "ci-test",
          "linter"
        ]
      }
    },
    "protection_url": "https://api.github.com/repos/octocat/hello-world/branches/master/protection"
  }
]

Resource not found

Status: 404 Not Found

Notes

get /repos/{owner}/{repo}/branches/{branch}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default response

Status: 200 OK
{
  "name": "master",
  "commit": {
    "sha": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
    "node_id": "MDY6Q29tbWl0N2ZkMWE2MGIwMWY5MWIzMTRmNTk5NTVhNGU0ZDRlODBkOGVkZjExZA==",
    "commit": {
      "author": {
        "name": "The Octocat",
        "date": "2012-03-06T15:06:50-08:00",
        "email": "octocat@nowhere.com"
      },
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
      "message": "Merge pull request #6 from Spaceghost/patch-1\n\nNew line at end of file.",
      "tree": {
        "sha": "b4eecafa9be2f2006ce1b709d6857b07069b4608",
        "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/b4eecafa9be2f2006ce1b709d6857b07069b4608"
      },
      "committer": {
        "name": "The Octocat",
        "date": "2012-03-06T15:06:50-08:00",
        "email": "octocat@nowhere.com"
      },
      "verification": {
        "verified": false,
        "reason": "unsigned",
        "signature": null,
        "payload": null
      },
      "comment_count": 0
    },
    "author": {
      "gravatar_id": "",
      "avatar_url": "https://secure.gravatar.com/avatar/7ad39074b0584bc555d0417ae3e7d974?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png",
      "url": "https://api.github.com/users/octocat",
      "id": 583231,
      "login": "octocat",
      "node_id": "MDQ6VXNlcjE=",
      "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": true
    },
    "parents": [
      {
        "sha": "553c2077f0edc3d5dc5d17262f6aa498e69d6f8e",
        "url": "https://api.github.com/repos/octocat/Hello-World/commits/553c2077f0edc3d5dc5d17262f6aa498e69d6f8e"
      },
      {
        "sha": "762941318ee16e59dabbacb1b4049eec22f0d303",
        "url": "https://api.github.com/repos/octocat/Hello-World/commits/762941318ee16e59dabbacb1b4049eec22f0d303"
      }
    ],
    "url": "https://api.github.com/repos/octocat/Hello-World/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
    "committer": {
      "gravatar_id": "",
      "avatar_url": "https://secure.gravatar.com/avatar/7ad39074b0584bc555d0417ae3e7d974?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png",
      "url": "https://api.github.com/users/octocat",
      "id": 583231,
      "login": "octocat",
      "node_id": "MDQ6VXNlcjE=",
      "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": true
    },
    "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments"
  },
  "_links": {
    "html": "https://github.com/octocat/Hello-World/tree/master",
    "self": "https://api.github.com/repos/octocat/Hello-World/branches/master"
  },
  "protected": true,
  "protection": {
    "enabled": true,
    "required_status_checks": {
      "enforcement_level": "non_admins",
      "contexts": [
        "ci-test",
        "linter"
      ]
    }
  },
  "protection_url": "https://api.github.com/repos/octocat/hello-world/branches/master/protection"
}

Resource not found

Status: 404 Not Found

Preview header missing

Status: 415 Unsupported Media Type

Notes

Get branch protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

get /repos/{owner}/{repo}/branches/{branch}/protection

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection",
  "enabled": true,
  "required_status_checks": {
    "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks",
    "contexts": [
      "continuous-integration/travis-ci"
    ],
    "contexts_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts",
    "enforcement_level": "non_admins"
  },
  "enforce_admins": {
    "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/enforce_admins",
    "enabled": true
  },
  "required_pull_request_reviews": {
    "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_pull_request_reviews",
    "dismissal_restrictions": {
      "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions",
      "users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/users",
      "teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/teams",
      "users": [
        {
          "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
        }
      ],
      "teams": [
        {
          "id": 1,
          "node_id": "MDQ6VGVhbTE=",
          "url": "https://api.github.com/teams/1",
          "html_url": "https://api.github.com/teams/justice-league",
          "name": "Justice League",
          "slug": "justice-league",
          "description": "A great team.",
          "privacy": "closed",
          "permission": "admin",
          "members_url": "https://api.github.com/teams/1/members{/member}",
          "repositories_url": "https://api.github.com/teams/1/repos",
          "parent": null
        }
      ]
    },
    "dismiss_stale_reviews": true,
    "require_code_owner_reviews": true,
    "required_approving_review_count": 2
  },
  "restrictions": [
    {
      "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions",
      "users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/users",
      "teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/teams",
      "apps_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/teams",
      "users": [
        {
          "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
        }
      ],
      "teams": [
        {
          "id": 1,
          "node_id": "MDQ6VGVhbTE=",
          "url": "https://api.github.com/teams/1",
          "html_url": "https://api.github.com/teams/justice-league",
          "name": "Justice League",
          "slug": "justice-league",
          "description": "A great team.",
          "privacy": "closed",
          "permission": "admin",
          "members_url": "https://api.github.com/teams/1/members{/member}",
          "repositories_url": "https://api.github.com/teams/1/repos",
          "parent": null
        }
      ],
      "apps": [
        {
          "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",
            "hooks_url": "https://api.github.com/orgs/github/hooks",
            "issues_url": "https://api.github.com/orgs/github/issues",
            "members_url": "https://api.github.com/orgs/github/members{/member}",
            "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
            "avatar_url": "https://github.com/images/error/octocat_happy.gif",
            "description": "A great organization"
          },
          "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"
          ]
        }
      ]
    }
  ]
}

Resource not found

Status: 404 Not Found

Notes

Preview notice

The Protected Branches API now has a setting for requiring a specified number of approving pull request reviews before merging. This feature is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.luke-cage-preview+json

Update branch protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Protecting a branch requires admin or owner permissions to the repository.

Note: Passing new arrays of users and teams replaces their previous values.

Note: The list of users, apps, and teams in total is limited to 100 items.

put /repos/{owner}/{repo}/branches/{branch}/protection

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
branch string path

branch+ parameter
required_status_checks object or null body

Required. Require status checks to pass before merging. Set to null to disable.

Properties of the required_status_checks object
strict (boolean)

Required. Require branches to be up to date before merging.
contexts (array of strings)

Required. The list of status checks to require in order to merge into this branch
enforce_admins boolean or null body

Required. Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to null to disable.
required_pull_request_reviews object or null body

Required. Require at least one approving review on a pull request, before merging. Set to null to disable.

Properties of the required_pull_request_reviews object
dismissal_restrictions (object)

Specify which users and teams can dismiss pull request reviews. Pass an empty dismissal_restrictions object to disable. User and team dismissal_restrictions are only available for organization-owned repositories. Omit this parameter for personal repositories.
dismiss_stale_reviews (boolean)

Set to true if you want to automatically dismiss approving reviews when someone pushes a new commit.
require_code_owner_reviews (boolean)

Blocks merging pull requests until code owners review them.
required_approving_review_count (integer)

Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6.

Properties of the dismissal_restrictions object
users (array of strings)

The list of user logins with dismissal access
teams (array of strings)

The list of team slugs with dismissal access
restrictions object or null body

Required. Restrict who can push to the protected branch. User, app, and team restrictions are only available for organization-owned repositories. Set to null to disable.

Properties of the restrictions object
users (array of strings)

Required. The list of user logins with push access
teams (array of strings)

Required. The list of team slugs with push access
apps (array of strings)

The list of app slugs with push access
required_linear_history boolean body

Enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. Set to true to enforce a linear commit history. Set to false to disable a linear commit Git history. Your repository must allow squash merging or rebase merging before you can enable a linear commit history. Default: false. For more information, see "Requiring a linear commit history" in the GitHub Help documentation.
allow_force_pushes boolean or null body

Permits force pushes to the protected branch by anyone with write access to the repository. Set to true to allow force pushes. Set to false or null to block force pushes. Default: false. For more information, see "Enabling force pushes to a protected branch" in the GitHub Help documentation."
allow_deletions boolean body

Allows deletion of the protected branch by anyone with write access to the repository. Set to false to prevent deletion of the protected branch. Default: false. For more information, see "Enabling force pushes to a protected branch" in the GitHub Help documentation.

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection \
  -d '{"required_status_checks":{"strict":true,"contexts":["contexts"]},"enforce_admins":true,"required_pull_request_reviews":{"dismissal_restrictions":{"users":["users"],"teams":["teams"]},"dismiss_stale_reviews":true,"require_code_owner_reviews":true,"required_approving_review_count":42},"restrictions":{"users":["users"],"teams":["teams"],"apps":["apps"]}}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  required_status_checks: {
    strict: true,
    contexts: [
      'contexts'
    ]
  },
  enforce_admins: true,
  required_pull_request_reviews: {
    dismissal_restrictions: {
      users: [
        'users'
      ],
      teams: [
        'teams'
      ]
    },
    dismiss_stale_reviews: true,
    require_code_owner_reviews: true,
    required_approving_review_count: 42
  },
  restrictions: {
    users: [
      'users'
    ],
    teams: [
      'teams'
    ],
    apps: [
      'apps'
    ]
  }
})

Response

Status: 200 OK

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Preview header missing

Status: 415 Unsupported Media Type

Validation failed

Status: 422 Unprocessable Entity

Notes

Preview notice

The Protected Branches API now has a setting for requiring a specified number of approving pull request reviews before merging. This feature is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.luke-cage-preview+json

Delete branch protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

delete /repos/{owner}/{repo}/branches/{branch}/protection

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default Response

Status: 204 No Content

Forbidden

Status: 403 Forbidden

Notes

Get admin branch protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

get /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/enforce_admins
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/enforce_admins",
  "enabled": true
}

Notes

Set admin branch protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Adding admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.

post /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/enforce_admins
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/enforce_admins",
  "enabled": true
}

Notes

Delete admin branch protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Removing admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.

delete /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/enforce_admins
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

No content

Status: 204 No Content

Resource not found

Status: 404 Not Found

Notes

Get pull request review protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

get /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_pull_request_reviews
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Response

Status: 200 OK

Notes

Preview notice

The Protected Branches API now has a setting for requiring a specified number of approving pull request reviews before merging. This feature is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.luke-cage-preview+json

Update pull request review protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Updating pull request review enforcement requires admin or owner permissions to the repository and branch protection to be enabled.

Note: Passing new arrays of users and teams replaces their previous values.

patch /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
branch string path

branch+ parameter
dismissal_restrictions object body

Specify which users and teams can dismiss pull request reviews. Pass an empty dismissal_restrictions object to disable. User and team dismissal_restrictions are only available for organization-owned repositories. Omit this parameter for personal repositories.

Properties of the dismissal_restrictions object
users (array of strings)

The list of user logins with dismissal access
teams (array of strings)

The list of team slugs with dismissal access
dismiss_stale_reviews boolean body

Set to true if you want to automatically dismiss approving reviews when someone pushes a new commit.
require_code_owner_reviews boolean body

Blocks merging pull requests until code owners have reviewed.
required_approving_review_count integer body

Specifies the number of reviewers required to approve pull requests. Use a number between 1 and 6.

Code samples

Shell 
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_pull_request_reviews \
  -d '{"dismissal_restrictions":{"users":["users"],"teams":["teams"]}}'
JavaScript (@octokit/core.js) 
await octokit.request('PATCH /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  dismissal_restrictions: {
    users: [
      'users'
    ],
    teams: [
      'teams'
    ]
  }
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_pull_request_reviews",
  "dismissal_restrictions": {
    "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions",
    "users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/users",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/teams",
    "users": [
      {
        "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
      }
    ],
    "teams": [
      {
        "id": 1,
        "node_id": "MDQ6VGVhbTE=",
        "url": "https://api.github.com/teams/1",
        "html_url": "https://api.github.com/teams/justice-league",
        "name": "Justice League",
        "slug": "justice-league",
        "description": "A great team.",
        "privacy": "closed",
        "permission": "admin",
        "members_url": "https://api.github.com/teams/1/members{/member}",
        "repositories_url": "https://api.github.com/teams/1/repos",
        "parent": null
      }
    ]
  },
  "dismiss_stale_reviews": true,
  "require_code_owner_reviews": true,
  "required_approving_review_count": 2
}

Validation failed

Status: 422 Unprocessable Entity

Notes

Preview notice

The Protected Branches API now has a setting for requiring a specified number of approving pull request reviews before merging. This feature is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.luke-cage-preview+json

Delete pull request review protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

delete /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_pull_request_reviews
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

No content

Status: 204 No Content

Resource not found

Status: 404 Not Found

Notes

Get commit signature protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

When authenticated with admin or owner permissions to the repository, you can use this endpoint to check whether a branch requires signed commits. An enabled status of true indicates you must sign commits on this branch. For more information, see Signing commits with GPG in GitHub Help.

Note: You must enable branch protection to require signed commits.

get /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.zzzax-preview+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_signatures
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  mediaType: {
    previews: [
      'zzzax'
    ]
  }
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_signatures",
  "enabled": true
}

Resource not found

Status: 404 Not Found

Notes

Preview notice

Protected Branches API can now manage a setting for requiring signed commits. This feature is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.zzzax-preview+json
☝️ This header is required.

Create commit signature protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

When authenticated with admin or owner permissions to the repository, you can use this endpoint to require signed commits on a branch. You must enable branch protection to require signed commits.

post /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.zzzax-preview+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_signatures
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  mediaType: {
    previews: [
      'zzzax'
    ]
  }
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_signatures",
  "enabled": true
}

Resource not found

Status: 404 Not Found

Notes

Preview notice

Protected Branches API can now manage a setting for requiring signed commits. This feature is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.zzzax-preview+json
☝️ This header is required.

Delete commit signature protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

When authenticated with admin or owner permissions to the repository, you can use this endpoint to disable required signed commits on a branch. You must enable branch protection to require signed commits.

delete /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.zzzax-preview+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_signatures
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  mediaType: {
    previews: [
      'zzzax'
    ]
  }
})

No content

Status: 204 No Content

Resource not found

Status: 404 Not Found

Notes

Preview notice

Protected Branches API can now manage a setting for requiring signed commits. This feature is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.zzzax-preview+json
☝️ This header is required.

Get status checks protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

get /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks",
  "strict": true,
  "contexts": [
    "continuous-integration/travis-ci"
  ],
  "contexts_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts"
}

Resource not found

Status: 404 Not Found

Notes

Update status check protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Updating required status checks requires admin or owner permissions to the repository and branch protection to be enabled.

patch /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter
strict boolean body

Require branches to be up to date before merging.
contexts array of strings body

The list of status checks to require in order to merge into this branch

Code samples

Shell 
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks \
  -d '{"strict":true}'
JavaScript (@octokit/core.js) 
await octokit.request('PATCH /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  strict: true
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks",
  "strict": true,
  "contexts": [
    "continuous-integration/travis-ci"
  ],
  "contexts_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts"
}

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes

Remove status check protection

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

delete /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

No content

Status: 204 No Content

Notes

Get all status check contexts

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

get /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks/contexts
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Response

Status: 200 OK
[
  "continuous-integration/travis-ci"
]

Resource not found

Status: 404 Not Found

Notes

Add status check contexts

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

post /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks/contexts \
  -d '{"contexts":["contexts"]}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  contexts: [
    'contexts'
  ]
})

Response

Status: 200 OK
[
  "continuous-integration/travis-ci",
  "continuous-integration/jenkins"
]

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes

Set status check contexts

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

put /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks/contexts \
  -d '{"contexts":["contexts"]}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  contexts: [
    'contexts'
  ]
})

Response

Status: 200 OK
[
  "continuous-integration/travis-ci"
]

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes

Remove status check contexts

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

delete /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks/contexts \
  -d '{"contexts":["contexts"]}'
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  contexts: [
    'contexts'
  ]
})

Response

Status: 200 OK
[
  "continuous-integration/travis-ci"
]

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes

Get access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Lists who has access to this protected branch.

Note: Users, apps, and teams restrictions are only available for organization-owned repositories.

get /repos/{owner}/{repo}/branches/{branch}/protection/restrictions

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions",
  "users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/users",
  "teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/teams",
  "apps_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/teams",
  "users": [
    {
      "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
    }
  ],
  "teams": [
    {
      "id": 1,
      "node_id": "MDQ6VGVhbTE=",
      "url": "https://api.github.com/teams/1",
      "html_url": "https://api.github.com/teams/justice-league",
      "name": "Justice League",
      "slug": "justice-league",
      "description": "A great team.",
      "privacy": "closed",
      "permission": "admin",
      "members_url": "https://api.github.com/teams/1/members{/member}",
      "repositories_url": "https://api.github.com/teams/1/repos",
      "parent": null
    }
  ],
  "apps": [
    {
      "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",
        "hooks_url": "https://api.github.com/orgs/github/hooks",
        "issues_url": "https://api.github.com/orgs/github/issues",
        "members_url": "https://api.github.com/orgs/github/members{/member}",
        "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "description": "A great organization"
      },
      "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"
      ]
    }
  ]
}

Resource not found

Status: 404 Not Found

Notes

Delete access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Disables the ability to restrict who can push to this branch.

delete /repos/{owner}/{repo}/branches/{branch}/protection/restrictions

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

No content

Status: 204 No Content

Notes

Get apps with access to the protected branch

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Lists the GitHub Apps that have push access to this branch. Only installed GitHub Apps with write access to the contents permission can be added as authorized actors on a protected branch.

get /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/apps
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default 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"
    ]
  }
]

Resource not found

Status: 404 Not Found

Notes

Add app access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Grants the specified apps push access for this branch. Only installed GitHub Apps with write access to the contents permission can be added as authorized actors on a protected branch.

TypeDescription
arrayThe GitHub Apps that have push access to this branch. Use the app's slug. Note: The list of users, apps, and teams in total is limited to 100 items.
post /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/apps \
  -d '{"apps":["apps"]}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  apps: [
    'apps'
  ]
})

Default 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"
    ]
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Set app access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Replaces the list of apps that have push access to this branch. This removes all apps that previously had push access and grants push access to the new list of apps. Only installed GitHub Apps with write access to the contents permission can be added as authorized actors on a protected branch.

TypeDescription
arrayThe GitHub Apps that have push access to this branch. Use the app's slug. Note: The list of users, apps, and teams in total is limited to 100 items.
put /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/apps \
  -d '{"apps":["apps"]}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  apps: [
    'apps'
  ]
})

Default 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"
    ]
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Remove app access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Removes the ability of an app to push to this branch. Only installed GitHub Apps with write access to the contents permission can be added as authorized actors on a protected branch.

TypeDescription
arrayThe GitHub Apps that have push access to this branch. Use the app's slug. Note: The list of users, apps, and teams in total is limited to 100 items.
delete /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/apps \
  -d '{"apps":["apps"]}'
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  apps: [
    'apps'
  ]
})

Default 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"
    ]
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Get teams with access to the protected branch

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Lists the teams who have push access to this branch. The list includes child teams.

get /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/teams
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/teams/1",
    "html_url": "https://api.github.com/teams/justice-league",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "privacy": "closed",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos",
    "parent": null
  }
]

Resource not found

Status: 404 Not Found

Notes

Add team access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Grants the specified teams push access for this branch. You can also give push access to child teams.

TypeDescription
arrayThe teams that can have push access. Use the team's slug. Note: The list of users, apps, and teams in total is limited to 100 items.
post /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/teams \
  -d '{"teams":["teams"]}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  teams: [
    'teams'
  ]
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/teams/1",
    "html_url": "https://api.github.com/teams/justice-league",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "privacy": "closed",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos",
    "parent": null
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Set team access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Replaces the list of teams that have push access to this branch. This removes all teams that previously had push access and grants push access to the new list of teams. Team restrictions include child teams.

TypeDescription
arrayThe teams that can have push access. Use the team's slug. Note: The list of users, apps, and teams in total is limited to 100 items.
put /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/teams \
  -d '{"teams":["teams"]}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  teams: [
    'teams'
  ]
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/teams/1",
    "html_url": "https://api.github.com/teams/justice-league",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "privacy": "closed",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos",
    "parent": null
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Remove team access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Removes the ability of a team to push to this branch. You can also remove push access for child teams.

TypeDescription
arrayTeams that should no longer have push access. Use the team's slug. Note: The list of users, apps, and teams in total is limited to 100 items.
delete /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/teams \
  -d '{"teams":["teams"]}'
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  teams: [
    'teams'
  ]
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/teams/1",
    "html_url": "https://api.github.com/teams/justice-league",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "privacy": "closed",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos",
    "parent": null
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Get users with access to the protected branch

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Lists the people who have push access to this branch.

get /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/users
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch'
})

Default response

Status: 200 OK
[
  {
    "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
  }
]

Resource not found

Status: 404 Not Found

Notes

Add user access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Grants the specified people push access for this branch.

TypeDescription
arrayUsernames for people who can have push access. Note: The list of users, apps, and teams in total is limited to 100 items.
post /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/users \
  -d '{"users":["users"]}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  users: [
    'users'
  ]
})

Default response

Status: 200 OK
[
  {
    "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
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Set user access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Replaces the list of people that have push access to this branch. This removes all people that previously had push access and grants push access to the new list of people.

TypeDescription
arrayUsernames for people who can have push access. Note: The list of users, apps, and teams in total is limited to 100 items.
put /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/users \
  -d '{"users":["users"]}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  users: [
    'users'
  ]
})

Default response

Status: 200 OK
[
  {
    "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
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Remove user access restrictions

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Removes the ability of a user to push to this branch.

TypeDescription
arrayUsernames of the people who should no longer have push access. Note: The list of users, apps, and teams in total is limited to 100 items.
delete /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
branch string path

branch+ parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/users \
  -d '{"users":["users"]}'
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users', {
  owner: 'octocat',
  repo: 'hello-world',
  branch: 'branch',
  users: [
    'users'
  ]
})

Default response

Status: 200 OK
[
  {
    "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
  }
]

Validation failed

Status: 422 Unprocessable Entity

Notes

Collaborators

List repository collaborators

For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners.

Team members will include the members of child teams.

get /repos/{owner}/{repo}/collaborators

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
affiliation string query

Filter collaborators returned by their affiliation. Can be one of:
* outside: All outside collaborators of an organization-owned repository.
* direct: All collaborators with permissions to an organization-owned repository, regardless of organization membership status.
* all: All collaborators the authenticated user can see.
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/collaborators
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/collaborators', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
[
  {
    "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,
    "permissions": {
      "pull": true,
      "push": true,
      "admin": false
    }
  }
]

Resource not found

Status: 404 Not Found

Notes

Check if a user is a repository collaborator

For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners.

Team members will include the members of child teams.

get /repos/{owner}/{repo}/collaborators/{username}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
username string path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/collaborators/USERNAME
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/collaborators/{username}', {
  owner: 'octocat',
  repo: 'hello-world',
  username: 'username'
})

Response if user is a collaborator

Status: 204 No Content

Response if user is not a collaborator

Status: 404 Not Found

Notes

Add a repository collaborator

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" and "Dealing with abuse rate limits" for details.

For more information the permission levels, see "Repository permission levels for an organization".

Note that, if you choose not to pass any parameters, you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

The invitee will receive a notification that they have been invited to the repository, which they must accept or decline. They may do this via the notifications page, the email they receive, or by using the repository invitations API endpoints.

Rate limits

To prevent abuse, you are limited to sending 50 invitations to a repository per 24 hour period. Note there is no limit if you are inviting organization members to an organization repository.

put /repos/{owner}/{repo}/collaborators/{username}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
username string path
permission string body

The permission to grant the collaborator. Only valid on organization-owned repositories. Can be one of:
* pull - can pull, but not push to or administer this repository.
* push - can pull and push, but not administer this repository.
* admin - can pull, push and administer this repository.
* maintain - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.
* triage - Recommended for contributors who need to proactively manage issues and pull requests without write access.

Default: push
permissions string body

undefined

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/collaborators/USERNAME \
  -d '{"permission":"permission"}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/collaborators/{username}', {
  owner: 'octocat',
  repo: 'hello-world',
  username: 'username',
  permission: 'permission'
})

Response when a new invitation is created

Status: 201 Created
{
  "id": 1,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "repository": {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "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
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks"
  },
  "invitee": {
    "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
  },
  "inviter": {
    "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
  },
  "permissions": "write",
  "created_at": "2016-06-13T14:52:50-05:00",
  "url": "https://api.github.com/user/repository_invitations/1296269",
  "html_url": "https://github.com/octocat/Hello-World/invitations"
}

Response when person is already a collaborator

Status: 204 No Content

Forbidden

Status: 403 Forbidden

Validation failed

Status: 422 Unprocessable Entity

Notes

delete /repos/{owner}/{repo}/collaborators/{username}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
username string path

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/collaborators/USERNAME
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/collaborators/{username}', {
  owner: 'octocat',
  repo: 'hello-world',
  username: 'username'
})

Default Response

Status: 204 No Content

Notes

Get repository permissions for a user

Checks the repository permission of a collaborator. The possible repository permissions are admin, write, read, and none.

get /repos/{owner}/{repo}/collaborators/{username}/permission

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
username string path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/collaborators/USERNAME/permission
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/collaborators/{username}/permission', {
  owner: 'octocat',
  repo: 'hello-world',
  username: 'username'
})

Response if user has admin permissions

Status: 200 OK
{
  "permission": "admin",
  "user": {
    "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
  }
}

Resource not found

Status: 404 Not Found

Notes

Comments

Custom media types for commit comments

These are the supported media types for commit comments. You can read more about the use of media types in the API here.

application/vnd.github-commitcomment.raw+json
application/vnd.github-commitcomment.text+json
application/vnd.github-commitcomment.html+json
application/vnd.github-commitcomment.full+json

For more information, see "Custom media types."

List commit comments for a repository

Commit Comments use these custom media types. You can read more about the use of media types in the API here.

Comments are ordered by ascending ID.

get /repos/{owner}/{repo}/comments

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/comments
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/comments', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
[
  {
    "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
    "url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
    "id": 1,
    "node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
    "body": "Great stuff",
    "path": "file1.txt",
    "position": 4,
    "line": 14,
    "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "user": {
      "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
    },
    "created_at": "2011-04-14T16:00:49Z",
    "updated_at": "2011-04-14T16:00:49Z",
    "author_association": "collaborator"
  }
]

Notes

Preview notice

An additional reactions object in the issue comment payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. Please see the blog post for full details.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.squirrel-girl-preview

The reactions key will have the following payload where url can be used to construct the API location for listing and creating reactions.

get /repos/{owner}/{repo}/comments/{comment_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
comment_id integer path

comment_id parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/comments/42
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/comments/{comment_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  comment_id: 42
})

Default response

Status: 200 OK
{
  "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
  "url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
  "id": 1,
  "node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
  "body": "Great stuff",
  "path": "file1.txt",
  "position": 4,
  "line": 14,
  "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "author_association": "collaborator",
  "user": {
    "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
  },
  "created_at": "2011-04-14T16:00:49Z",
  "updated_at": "2011-04-14T16:00:49Z"
}

Resource not found

Status: 404 Not Found

Notes

Preview notice

An additional reactions object in the issue comment payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. Please see the blog post for full details.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.squirrel-girl-preview

The reactions key will have the following payload where url can be used to construct the API location for listing and creating reactions.

patch /repos/{owner}/{repo}/comments/{comment_id}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
comment_id integer path

comment_id parameter
body string body

Required. The contents of the comment

Code samples

Shell 
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/comments/42 \
  -d '{"body":"body"}'
JavaScript (@octokit/core.js) 
await octokit.request('PATCH /repos/{owner}/{repo}/comments/{comment_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  comment_id: 42,
  body: 'body'
})

Default response

Status: 200 OK
{
  "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
  "url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
  "id": 1,
  "node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
  "body": "Nice change",
  "path": "file1.txt",
  "position": 4,
  "line": 14,
  "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "author_association": "collaborator",
  "user": {
    "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
  },
  "created_at": "2011-04-14T16:00:49Z",
  "updated_at": "2011-04-14T16:00:49Z"
}

Resource not found

Status: 404 Not Found

Notes

delete /repos/{owner}/{repo}/comments/{comment_id}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
comment_id integer path

comment_id parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/comments/42
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/comments/{comment_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  comment_id: 42
})

Default Response

Status: 204 No Content

Resource not found

Status: 404 Not Found

Notes

List commit comments

Use the :commit_sha to specify the commit that will have its comments listed.

get /repos/{owner}/{repo}/commits/{commit_sha}/comments

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
commit_sha string path

commit_sha+ parameter
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/commits/COMMIT_SHA/comments
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/commits/{commit_sha}/comments', {
  owner: 'octocat',
  repo: 'hello-world',
  commit_sha: 'commit_sha'
})

Default response

Status: 200 OK
[
  {
    "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
    "url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
    "id": 1,
    "node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
    "body": "Great stuff",
    "path": "file1.txt",
    "position": 4,
    "line": 14,
    "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "user": {
      "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
    },
    "created_at": "2011-04-14T16:00:49Z",
    "updated_at": "2011-04-14T16:00:49Z",
    "author_association": "collaborator"
  }
]

Notes

Preview notice

An additional reactions object in the issue comment payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. Please see the blog post for full details.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.squirrel-girl-preview

The reactions key will have the following payload where url can be used to construct the API location for listing and creating reactions.

Create a commit comment

Create a comment for a commit using its :commit_sha.

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" and "Dealing with abuse rate limits" for details.

post /repos/{owner}/{repo}/commits/{commit_sha}/comments

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
commit_sha string path

commit_sha+ parameter
body string body

Required. The contents of the comment.
path string body

Relative path of the file to comment on.
position integer body

Line index in the diff to comment on.
line integer body

Deprecated. Use position parameter instead. Line number in the file to comment on.

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/commits/COMMIT_SHA/comments \
  -d '{"body":"body"}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/commits/{commit_sha}/comments', {
  owner: 'octocat',
  repo: 'hello-world',
  commit_sha: 'commit_sha',
  body: 'body'
})

Default response

Status: 201 Created
{
  "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
  "url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
  "id": 1,
  "node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
  "body": "Great stuff",
  "path": "file1.txt",
  "position": 4,
  "line": 14,
  "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "author_association": "collaborator",
  "user": {
    "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
  },
  "created_at": "2011-04-14T16:00:49Z",
  "updated_at": "2011-04-14T16:00:49Z"
}

Forbidden

Status: 403 Forbidden

Validation failed

Status: 422 Unprocessable Entity

Notes

Commits

The Repo Commits API supports listing, viewing, and comparing commits in a repository.

List commits

Signature verification object

The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object:

NameTypeDescription
verifiedbooleanIndicates whether GitHub considers the signature in this commit to be verified.
reasonstringThe reason for verified value. Possible values and their meanings are enumerated in table below.
signaturestringThe signature that was extracted from the commit.
payloadstringThe value that was signed.

These are the possible values for reason in the verification object:

ValueDescription
expired_keyThe key that made the signature is expired.
not_signing_keyThe "signing" flag is not among the usage flags in the GPG key that made the signature.
gpgverify_errorThere was an error communicating with the signature verification service.
gpgverify_unavailableThe signature verification service is currently unavailable.
unsignedThe object does not include a signature.
unknown_signature_typeA non-PGP signature was found in the commit.
no_userNo user was associated with the committer email address in the commit.
unverified_emailThe committer email address in the commit was associated with a user, but the email address is not verified on her/his account.
bad_emailThe committer email address in the commit is not included in the identities of the PGP key that made the signature.
unknown_keyThe key that made the signature has not been registered with any user's account.
malformed_signatureThere was an error parsing the signature.
invalidThe signature could not be cryptographically verified using the key whose key-id was found in the signature.
validNone of the above errors applied, so the signature is considered to be verified.
get /repos/{owner}/{repo}/commits

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
sha string query

SHA or branch to start listing commits from. Default: the repository’s default branch (usually master).
path string query

Only commits containing this file path will be returned.
author string query

GitHub login or email address by which to filter by commit author.
since string query

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

Only commits before this date will be returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/commits
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/commits', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
[
  {
    "id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "tree_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "message": "Fix all the bugs",
    "timestamp": "2016-10-10T00:00:00Z",
    "author": {
      "name": "Monalisa Octocat",
      "email": "mona@github.com"
    },
    "committer": {
      "name": "Monalisa Octocat",
      "email": "mona@github.com"
    }
  },
  {
    "id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "tree_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "message": "Fix all the bugs",
    "timestamp": "2016-10-10T00:00:00Z",
    "author": {
      "name": "Monalisa Octocat",
      "email": "mona@github.com"
    },
    "committer": {
      "name": "Monalisa Octocat",
      "email": "mona@github.com"
    }
  }
]

Bad request

Status: 400 Bad Request

Resource not found

Status: 404 Not Found

Conflict

Status: 409 Conflict

Internal error

Status: 500 Internal Server Error

Notes

List branches for HEAD commit

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Returns all branches where the given commit SHA is the HEAD, or latest commit for the branch.

get /repos/{owner}/{repo}/commits/{commit_sha}/branches-where-head

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
commit_sha string path

commit_sha+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.groot-preview+json" \
  https://api.github.com/repos/octocat/hello-world/commits/COMMIT_SHA/branches-where-head
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/commits/{commit_sha}/branches-where-head', {
  owner: 'octocat',
  repo: 'hello-world',
  commit_sha: 'commit_sha',
  mediaType: {
    previews: [
      'groot'
    ]
  }
})

Default response

Status: 200 OK
[
  {
    "name": "branch_5",
    "commit": {
      "sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc",
      "url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
    },
    "protected": false
  }
]

Preview header missing

Status: 415 Unsupported Media Type

Validation failed

Status: 422 Unprocessable Entity

Notes

Preview notice

Listing branches or pull requests for a commit in the Commits API is currently available for developers to preview. See the blog post for more details. To access the new endpoints during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.groot-preview+json
☝️ This header is required.

List pull requests associated with a commit

Lists all pull requests containing the provided commit SHA, which can be from any point in the commit history. The results will include open and closed pull requests. Additional preview headers may be required to see certain details for associated pull requests, such as whether a pull request is in a draft state. For more information about previews that might affect this endpoint, see the List pull requests endpoint.

get /repos/{owner}/{repo}/commits/{commit_sha}/pulls

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notice

owner string path
repo string path
commit_sha string path

commit_sha+ parameter
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.groot-preview+json" \
  https://api.github.com/repos/octocat/hello-world/commits/COMMIT_SHA/pulls
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/commits/{commit_sha}/pulls', {
  owner: 'octocat',
  repo: 'hello-world',
  commit_sha: 'commit_sha',
  mediaType: {
    previews: [
      'groot'
    ]
  }
})

Default response

Status: 200 OK
[
  {
    "url": "https://api.github.com/repos/octocat/Hello-World/pulls/1347",
    "id": 1,
    "node_id": "MDExOlB1bGxSZXF1ZXN0MQ==",
    "html_url": "https://github.com/octocat/Hello-World/pull/1347",
    "diff_url": "https://github.com/octocat/Hello-World/pull/1347.diff",
    "patch_url": "https://github.com/octocat/Hello-World/pull/1347.patch",
    "issue_url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/pulls/1347/commits",
    "review_comments_url": "https://api.github.com/repos/octocat/Hello-World/pulls/1347/comments",
    "review_comment_url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments{/number}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/comments",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "number": 1347,
    "state": "open",
    "locked": true,
    "title": "Amazing new feature",
    "user": {
      "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
    },
    "body": "Please pull these awesome changes in!",
    "labels": [
      {
        "id": 208045946,
        "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
        "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
        "name": "bug",
        "description": "Something isn't working",
        "color": "f29513",
        "default": true
      }
    ],
    "milestone": {
      "url": "https://api.github.com/repos/octocat/Hello-World/milestones/1",
      "html_url": "https://github.com/octocat/Hello-World/milestones/v1.0",
      "labels_url": "https://api.github.com/repos/octocat/Hello-World/milestones/1/labels",
      "id": 1002604,
      "node_id": "MDk6TWlsZXN0b25lMTAwMjYwNA==",
      "number": 1,
      "state": "open",
      "title": "v1.0",
      "description": "Tracking milestone for version 1.0",
      "creator": {
        "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
      },
      "open_issues": 4,
      "closed_issues": 8,
      "created_at": "2011-04-10T20:09:31Z",
      "updated_at": "2014-03-03T18:58:10Z",
      "closed_at": "2013-02-12T13:22:01Z",
      "due_on": "2012-10-09T23:39:01Z"
    },
    "active_lock_reason": "too heated",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:01:12Z",
    "closed_at": "2011-01-26T19:01:12Z",
    "merged_at": "2011-01-26T19:01:12Z",
    "merge_commit_sha": "e5bd3914e2e596debea16f433f57875b5b90bcd6",
    "assignee": {
      "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
    },
    "assignees": [
      {
        "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
      },
      {
        "login": "hubot",
        "id": 1,
        "node_id": "MDQ6VXNlcjE=",
        "avatar_url": "https://github.com/images/error/hubot_happy.gif",
        "gravatar_id": "",
        "url": "https://api.github.com/users/hubot",
        "html_url": "https://github.com/hubot",
        "followers_url": "https://api.github.com/users/hubot/followers",
        "following_url": "https://api.github.com/users/hubot/following{/other_user}",
        "gists_url": "https://api.github.com/users/hubot/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/hubot/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/hubot/subscriptions",
        "organizations_url": "https://api.github.com/users/hubot/orgs",
        "repos_url": "https://api.github.com/users/hubot/repos",
        "events_url": "https://api.github.com/users/hubot/events{/privacy}",
        "received_events_url": "https://api.github.com/users/hubot/received_events",
        "type": "User",
        "site_admin": true
      }
    ],
    "requested_reviewers": [
      {
        "login": "other_user",
        "id": 1,
        "node_id": "MDQ6VXNlcjE=",
        "avatar_url": "https://github.com/images/error/other_user_happy.gif",
        "gravatar_id": "",
        "url": "https://api.github.com/users/other_user",
        "html_url": "https://github.com/other_user",
        "followers_url": "https://api.github.com/users/other_user/followers",
        "following_url": "https://api.github.com/users/other_user/following{/other_user}",
        "gists_url": "https://api.github.com/users/other_user/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/other_user/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/other_user/subscriptions",
        "organizations_url": "https://api.github.com/users/other_user/orgs",
        "repos_url": "https://api.github.com/users/other_user/repos",
        "events_url": "https://api.github.com/users/other_user/events{/privacy}",
        "received_events_url": "https://api.github.com/users/other_user/received_events",
        "type": "User",
        "site_admin": false
      }
    ],
    "requested_teams": [
      {
        "id": 1,
        "node_id": "MDQ6VGVhbTE=",
        "url": "https://api.github.com/teams/1",
        "html_url": "https://api.github.com/teams/justice-league",
        "name": "Justice League",
        "slug": "justice-league",
        "description": "A great team.",
        "privacy": "closed",
        "permission": "admin",
        "members_url": "https://api.github.com/teams/1/members{/member}",
        "repositories_url": "https://api.github.com/teams/1/repos",
        "parent": null
      }
    ],
    "head": {
      "label": "octocat:new-topic",
      "ref": "new-topic",
      "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "user": {
        "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
      },
      "repo": {
        "id": 1296269,
        "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
        "name": "Hello-World",
        "full_name": "octocat/Hello-World",
        "owner": {
          "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
        },
        "private": false,
        "html_url": "https://github.com/octocat/Hello-World",
        "description": "This your first repo!",
        "fork": false,
        "url": "https://api.github.com/repos/octocat/Hello-World",
        "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
        "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
        "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
        "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
        "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
        "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
        "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
        "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
        "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
        "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
        "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
        "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
        "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
        "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
        "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
        "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
        "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
        "git_url": "git:github.com/octocat/Hello-World.git",
        "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
        "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
        "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
        "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
        "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
        "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
        "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
        "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
        "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
        "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
        "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
        "ssh_url": "git@github.com:octocat/Hello-World.git",
        "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
        "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
        "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
        "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
        "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
        "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
        "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
        "clone_url": "https://github.com/octocat/Hello-World.git",
        "mirror_url": "git:git.example.com/octocat/Hello-World",
        "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
        "svn_url": "https://svn.github.com/octocat/Hello-World",
        "homepage": "https://github.com",
        "language": null,
        "forks_count": 9,
        "stargazers_count": 80,
        "watchers_count": 80,
        "size": 108,
        "default_branch": "master",
        "open_issues_count": 0,
        "is_template": true,
        "topics": [
          "octocat",
          "atom",
          "electron",
          "api"
        ],
        "has_issues": true,
        "has_projects": true,
        "has_wiki": true,
        "has_pages": false,
        "has_downloads": true,
        "archived": false,
        "disabled": false,
        "pushed_at": "2011-01-26T19:06:43Z",
        "created_at": "2011-01-26T19:01:12Z",
        "updated_at": "2011-01-26T19:14:43Z",
        "permissions": {
          "admin": false,
          "push": false,
          "pull": true
        },
        "allow_rebase_merge": true,
        "template_repository": null,
        "allow_squash_merge": true,
        "allow_merge_commit": true,
        "subscribers_count": 42,
        "network_count": 0,
        "anonymous_access_enabled": false
      }
    },
    "base": {
      "label": "octocat:master",
      "ref": "master",
      "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "user": {
        "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
      },
      "repo": {
        "id": 1296269,
        "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
        "name": "Hello-World",
        "full_name": "octocat/Hello-World",
        "owner": {
          "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
        },
        "private": false,
        "html_url": "https://github.com/octocat/Hello-World",
        "description": "This your first repo!",
        "fork": false,
        "url": "https://api.github.com/repos/octocat/Hello-World",
        "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
        "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
        "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
        "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
        "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
        "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
        "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
        "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
        "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
        "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
        "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
        "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
        "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
        "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
        "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
        "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
        "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
        "git_url": "git:github.com/octocat/Hello-World.git",
        "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
        "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
        "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
        "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
        "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
        "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
        "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
        "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
        "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
        "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
        "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
        "ssh_url": "git@github.com:octocat/Hello-World.git",
        "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
        "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
        "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
        "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
        "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
        "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
        "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
        "clone_url": "https://github.com/octocat/Hello-World.git",
        "mirror_url": "git:git.example.com/octocat/Hello-World",
        "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
        "svn_url": "https://svn.github.com/octocat/Hello-World",
        "homepage": "https://github.com",
        "language": null,
        "forks_count": 9,
        "stargazers_count": 80,
        "watchers_count": 80,
        "size": 108,
        "default_branch": "master",
        "open_issues_count": 0,
        "is_template": true,
        "topics": [
          "octocat",
          "atom",
          "electron",
          "api"
        ],
        "has_issues": true,
        "has_projects": true,
        "has_wiki": true,
        "has_pages": false,
        "has_downloads": true,
        "archived": false,
        "disabled": false,
        "pushed_at": "2011-01-26T19:06:43Z",
        "created_at": "2011-01-26T19:01:12Z",
        "updated_at": "2011-01-26T19:14:43Z",
        "permissions": {
          "admin": false,
          "push": false,
          "pull": true
        },
        "allow_rebase_merge": true,
        "template_repository": null,
        "allow_squash_merge": true,
        "allow_merge_commit": true,
        "subscribers_count": 42,
        "network_count": 0,
        "anonymous_access_enabled": false
      }
    },
    "_links": {
      "self": {
        "href": "https://api.github.com/repos/octocat/Hello-World/pulls/1347"
      },
      "html": {
        "href": "https://github.com/octocat/Hello-World/pull/1347"
      },
      "issue": {
        "href": "https://api.github.com/repos/octocat/Hello-World/issues/1347"
      },
      "comments": {
        "href": "https://api.github.com/repos/octocat/Hello-World/issues/1347/comments"
      },
      "review_comments": {
        "href": "https://api.github.com/repos/octocat/Hello-World/pulls/1347/comments"
      },
      "review_comment": {
        "href": "https://api.github.com/repos/octocat/Hello-World/pulls/comments{/number}"
      },
      "commits": {
        "href": "https://api.github.com/repos/octocat/Hello-World/pulls/1347/commits"
      },
      "statuses": {
        "href": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e"
      }
    },
    "author_association": "OWNER",
    "draft": false
  }
]

Preview header missing

Status: 415 Unsupported Media Type

Notes

Preview notice

Listing branches or pull requests for a commit in the Commits API is currently available for developers to preview. See the blog post for more details. To access the new endpoints during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.groot-preview+json
☝️ This header is required.

Get a commit

Returns the contents of a single commit reference. You must have read access for the repository to use this endpoint.

Note: If there are more than 300 files in the commit diff, the response will include pagination link headers for the remaining files, up to a limit of 3000 files. Each page contains the static commit information, and the only changes are to the file listing.

You can pass the appropriate media type to fetch diff and patch formats. Diffs with binary data will have no patch property.

To return only the SHA-1 hash of the commit reference, you can provide the sha custom media type in the Accept header. You can use this endpoint to check if a remote reference's SHA-1 hash is the same as your local reference's SHA-1 hash by providing the local SHA-1 reference as the ETag.

Signature verification object

The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object:

NameTypeDescription
verifiedbooleanIndicates whether GitHub considers the signature in this commit to be verified.
reasonstringThe reason for verified value. Possible values and their meanings are enumerated in table below.
signaturestringThe signature that was extracted from the commit.
payloadstringThe value that was signed.

These are the possible values for reason in the verification object:

ValueDescription
expired_keyThe key that made the signature is expired.
not_signing_keyThe "signing" flag is not among the usage flags in the GPG key that made the signature.
gpgverify_errorThere was an error communicating with the signature verification service.
gpgverify_unavailableThe signature verification service is currently unavailable.
unsignedThe object does not include a signature.
unknown_signature_typeA non-PGP signature was found in the commit.
no_userNo user was associated with the committer email address in the commit.
unverified_emailThe committer email address in the commit was associated with a user, but the email address is not verified on her/his account.
bad_emailThe committer email address in the commit is not included in the identities of the PGP key that made the signature.
unknown_keyThe key that made the signature has not been registered with any user's account.
malformed_signatureThere was an error parsing the signature.
invalidThe signature could not be cryptographically verified using the key whose key-id was found in the signature.
validNone of the above errors applied, so the signature is considered to be verified.
get /repos/{owner}/{repo}/commits/{ref}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
ref string path

ref+ parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/commits/REF
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/commits/{ref}', {
  owner: 'octocat',
  repo: 'hello-world',
  ref: 'ref'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "node_id": "MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==",
  "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments",
  "commit": {
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "author": {
      "name": "Monalisa Octocat",
      "email": "mona@github.com",
      "date": "2011-04-14T16:00:49Z"
    },
    "committer": {
      "name": "Monalisa Octocat",
      "email": "mona@github.com",
      "date": "2011-04-14T16:00:49Z"
    },
    "message": "Fix all the bugs",
    "tree": {
      "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
    },
    "comment_count": 0,
    "verification": {
      "verified": false,
      "reason": "unsigned",
      "signature": null,
      "payload": null
    }
  },
  "author": {
    "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
  },
  "committer": {
    "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
  },
  "parents": [
    {
      "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
    }
  ],
  "stats": {
    "additions": 104,
    "deletions": 4,
    "total": 108
  },
  "files": [
    {
      "filename": "file1.txt",
      "additions": 10,
      "deletions": 2,
      "changes": 12,
      "status": "modified",
      "raw_url": "https://github.com/octocat/Hello-World/raw/7ca483543807a51b6079e54ac4cc392bc29ae284/file1.txt",
      "blob_url": "https://github.com/octocat/Hello-World/blob/7ca483543807a51b6079e54ac4cc392bc29ae284/file1.txt",
      "patch": "@@ -29,7 +29,7 @@\n....."
    }
  ]
}

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Internal error

Status: 500 Internal Server Error

Notes

Compare two commits

Both :base and :head must be branch names in :repo. To compare branches across other repositories in the same network as :repo, use the format <USERNAME>:branch.

The response from the API is equivalent to running the git log base..head command; however, commits are returned in chronological order. Pass the appropriate media type to fetch diff and patch formats.

The response also includes details on the files that were changed between the two commits. This includes the status of the change (for example, if a file was added, removed, modified, or renamed), and details of the change itself. For example, files with a renamed status have a previous_filename field showing the previous filename of the file, and files with a modified status have a patch field showing the changes made to the file.

Working with large comparisons

The response will include a comparison of up to 250 commits. If you are working with a larger commit range, you can use the List commits to enumerate all commits in the range.

For comparisons with extremely large diffs, you may receive an error response indicating that the diff took too long to generate. You can typically resolve this error by using a smaller commit range.

Signature verification object

The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object:

NameTypeDescription
verifiedbooleanIndicates whether GitHub considers the signature in this commit to be verified.
reasonstringThe reason for verified value. Possible values and their meanings are enumerated in table below.
signaturestringThe signature that was extracted from the commit.
payloadstringThe value that was signed.

These are the possible values for reason in the verification object:

ValueDescription
expired_keyThe key that made the signature is expired.
not_signing_keyThe "signing" flag is not among the usage flags in the GPG key that made the signature.
gpgverify_errorThere was an error communicating with the signature verification service.
gpgverify_unavailableThe signature verification service is currently unavailable.
unsignedThe object does not include a signature.
unknown_signature_typeA non-PGP signature was found in the commit.
no_userNo user was associated with the committer email address in the commit.
unverified_emailThe committer email address in the commit was associated with a user, but the email address is not verified on her/his account.
bad_emailThe committer email address in the commit is not included in the identities of the PGP key that made the signature.
unknown_keyThe key that made the signature has not been registered with any user's account.
malformed_signatureThere was an error parsing the signature.
invalidThe signature could not be cryptographically verified using the key whose key-id was found in the signature.
validNone of the above errors applied, so the signature is considered to be verified.
get /repos/{owner}/{repo}/compare/{base}...{head}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
base string path
head string path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/compare/BASE...HEAD
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/compare/{base}...{head}', {
  owner: 'octocat',
  repo: 'hello-world',
  base: 'base',
  head: 'head'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/Hello-World/compare/master...topic",
  "html_url": "https://github.com/octocat/Hello-World/compare/master...topic",
  "permalink_url": "https://github.com/octocat/Hello-World/compare/octocat:bbcd538c8e72b8c175046e27cc8f907076331401...octocat:0328041d1152db8ae77652d1618a02e57f745f17",
  "diff_url": "https://github.com/octocat/Hello-World/compare/master...topic.diff",
  "patch_url": "https://github.com/octocat/Hello-World/compare/master...topic.patch",
  "base_commit": {
    "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "node_id": "MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==",
    "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments",
    "commit": {
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "author": {
        "name": "Monalisa Octocat",
        "email": "mona@github.com",
        "date": "2011-04-14T16:00:49Z"
      },
      "committer": {
        "name": "Monalisa Octocat",
        "email": "mona@github.com",
        "date": "2011-04-14T16:00:49Z"
      },
      "message": "Fix all the bugs",
      "tree": {
        "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e",
        "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
      },
      "comment_count": 0,
      "verification": {
        "verified": false,
        "reason": "unsigned",
        "signature": null,
        "payload": null
      }
    },
    "author": {
      "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
    },
    "committer": {
      "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
    },
    "parents": [
      {
        "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
        "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
      }
    ]
  },
  "merge_base_commit": {
    "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "node_id": "MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==",
    "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments",
    "commit": {
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "author": {
        "name": "Monalisa Octocat",
        "email": "mona@github.com",
        "date": "2011-04-14T16:00:49Z"
      },
      "committer": {
        "name": "Monalisa Octocat",
        "email": "mona@github.com",
        "date": "2011-04-14T16:00:49Z"
      },
      "message": "Fix all the bugs",
      "tree": {
        "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e",
        "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
      },
      "comment_count": 0,
      "verification": {
        "verified": false,
        "reason": "unsigned",
        "signature": null,
        "payload": null
      }
    },
    "author": {
      "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
    },
    "committer": {
      "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
    },
    "parents": [
      {
        "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
        "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
      }
    ]
  },
  "status": "behind",
  "ahead_by": 1,
  "behind_by": 2,
  "total_commits": 1,
  "commits": [
    {
      "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "node_id": "MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==",
      "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments",
      "commit": {
        "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
        "author": {
          "name": "Monalisa Octocat",
          "email": "mona@github.com",
          "date": "2011-04-14T16:00:49Z"
        },
        "committer": {
          "name": "Monalisa Octocat",
          "email": "mona@github.com",
          "date": "2011-04-14T16:00:49Z"
        },
        "message": "Fix all the bugs",
        "tree": {
          "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e",
          "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
        },
        "comment_count": 0,
        "verification": {
          "verified": false,
          "reason": "unsigned",
          "signature": null,
          "payload": null
        }
      },
      "author": {
        "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
      },
      "committer": {
        "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
      },
      "parents": [
        {
          "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
          "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
        }
      ]
    }
  ],
  "files": [
    {
      "sha": "bbcd538c8e72b8c175046e27cc8f907076331401",
      "filename": "file1.txt",
      "status": "added",
      "additions": 103,
      "deletions": 21,
      "changes": 124,
      "blob_url": "https://github.com/octocat/Hello-World/blob/6dcb09b5b57875f334f61aebed695e2e4193db5e/file1.txt",
      "raw_url": "https://github.com/octocat/Hello-World/raw/6dcb09b5b57875f334f61aebed695e2e4193db5e/file1.txt",
      "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/file1.txt?ref=6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "patch": "@@ -132,7 +132,7 @@ module Test @@ -1000,7 +1000,7 @@ module Test"
    }
  ]
}

Resource not found

Status: 404 Not Found

Internal error

Status: 500 Internal Server Error

Notes

Contents

These API endpoints let you create, modify, and delete Base64 encoded content in a repository. To request the raw format or rendered HTML (when supported), use custom media types for repository contents.

Custom media types for repository contents

READMEs, files, and symlinks support the following custom media types:

application/vnd.github.VERSION.raw
application/vnd.github.VERSION.html

Use the .raw media type to retrieve the contents of the file.

For markup files such as Markdown or AsciiDoc, you can retrieve the rendered HTML using the .html media type. Markup languages are rendered to HTML using our open-source Markup library.

All objects support the following custom media type:

application/vnd.github.VERSION.object

Use the object media type parameter to retrieve the contents in a consistent object format regardless of the content type. For example, instead of an array of objects for a directory, the response will be an object with an entries attribute containing the array of objects.

You can read more about the use of media types in the API here.

Get repository content

Gets the contents of a file or directory in a repository. Specify the file path or directory in :path. If you omit :path, you will receive the contents of all files in the repository.

Files and symlinks support a custom media type for retrieving the raw content or rendered HTML (when supported). All content types support a custom media type to ensure the content is returned in a consistent object format.

Note:

  • To get a repository's contents recursively, you can recursively get the tree.
  • This API has an upper limit of 1,000 files for a directory. If you need to retrieve more files, use the Git Trees API.
  • This API supports files up to 1 megabyte in size.

If the content is a directory

The response will be an array of objects, one object for each item in the directory. When listing the contents of a directory, submodules have their "type" specified as "file". Logically, the value should be "submodule". This behavior exists in API v3 for backwards compatibility purposes. In the next major version of the API, the type will be returned as "submodule".

If the content is a symlink

If the requested :path points to a symlink, and the symlink's target is a normal file in the repository, then the API responds with the content of the file (in the format shown in the example. Otherwise, the API responds with an object describing the symlink itself.

If the content is a submodule

The submodule_git_url identifies the location of the submodule repository, and the sha identifies a specific commit within the submodule repository. Git uses the given URL when cloning the submodule repository, and checks out the submodule at that specific commit.

If the submodule repository is not hosted on github.com, the Git URLs (git_url and _links["git"]) and the github.com URLs (html_url and _links["html"]) will have null values.

get /repos/{owner}/{repo}/contents/{path}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
path string path

path+ parameter
ref string query

The name of the commit/branch/tag. Default: the repository’s default branch (usually master)

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/contents/PATH
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/contents/{path}', {
  owner: 'octocat',
  repo: 'hello-world',
  path: 'path'
})

Response if content is a file

Status: 200 OK
{
  "type": "file",
  "encoding": "base64",
  "size": 5362,
  "name": "README.md",
  "path": "README.md",
  "content": "encoded content ...",
  "sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
  "url": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
  "git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
  "html_url": "https://github.com/octokit/octokit.rb/blob/master/README.md",
  "download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/README.md",
  "_links": {
    "git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
    "html": "https://github.com/octokit/octokit.rb/blob/master/README.md"
  }
}

Response if content is a directory

Status: 200 OK
[
  {
    "type": "file",
    "size": 625,
    "name": "octokit.rb",
    "path": "lib/octokit.rb",
    "sha": "fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
    "url": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit.rb",
    "git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
    "html_url": "https://github.com/octokit/octokit.rb/blob/master/lib/octokit.rb",
    "download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/lib/octokit.rb",
    "_links": {
      "self": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit.rb",
      "git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
      "html": "https://github.com/octokit/octokit.rb/blob/master/lib/octokit.rb"
    }
  },
  {
    "type": "dir",
    "size": 0,
    "name": "octokit",
    "path": "lib/octokit",
    "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
    "url": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit",
    "git_url": "https://api.github.com/repos/octokit/octokit.rb/git/trees/a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
    "html_url": "https://github.com/octokit/octokit.rb/tree/master/lib/octokit",
    "download_url": null,
    "_links": {
      "self": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit",
      "git": "https://api.github.com/repos/octokit/octokit.rb/git/trees/a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
      "html": "https://github.com/octokit/octokit.rb/tree/master/lib/octokit"
    }
  }
]

Response if content is a symlink

Status: 200 OK
{
  "type": "symlink",
  "target": "/path/to/symlink/target",
  "size": 23,
  "name": "some-symlink",
  "path": "bin/some-symlink",
  "sha": "452a98979c88e093d682cab404a3ec82babebb48",
  "url": "https://api.github.com/repos/octokit/octokit.rb/contents/bin/some-symlink",
  "git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/452a98979c88e093d682cab404a3ec82babebb48",
  "html_url": "https://github.com/octokit/octokit.rb/blob/master/bin/some-symlink",
  "download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/bin/some-symlink",
  "_links": {
    "git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/452a98979c88e093d682cab404a3ec82babebb48",
    "self": "https://api.github.com/repos/octokit/octokit.rb/contents/bin/some-symlink",
    "html": "https://github.com/octokit/octokit.rb/blob/master/bin/some-symlink"
  }
}

Response if content is a submodule

Status: 200 OK
{
  "type": "submodule",
  "submodule_git_url": "git://github.com/jquery/qunit.git",
  "size": 0,
  "name": "qunit",
  "path": "test/qunit",
  "sha": "6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "url": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
  "git_url": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "html_url": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "download_url": null,
  "_links": {
    "git": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
    "self": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
    "html": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
  }
}

Found

Status: 302 Found

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Notes

Create or update file contents

Creates a new file or replaces an existing file in a repository.

put /repos/{owner}/{repo}/contents/{path}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
path string path

path+ parameter
message string body

Required. The commit message.
content string body

Required. The new file content, using Base64 encoding.
sha string body

Required if you are updating a file. The blob SHA of the file being replaced.
branch string body

The branch name. Default: the repository’s default branch (usually master)
committer object body

The person that committed the file. Default: the authenticated user.

Properties of the committer object
name (string)

Required. The name of the author or committer of the commit. You'll receive a 422 status code if name is omitted.
email (string)

Required. The email of the author or committer of the commit. You'll receive a 422 status code if email is omitted.
date (string)

undefined
author object body

The author of the file. Default: The committer or the authenticated user if you omit committer.

Properties of the author object
name (string)

Required. The name of the author or committer of the commit. You'll receive a 422 status code if name is omitted.
email (string)

Required. The email of the author or committer of the commit. You'll receive a 422 status code if email is omitted.
date (string)

undefined

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/contents/PATH \
  -d '{"message":"message","content":"content"}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /repos/{owner}/{repo}/contents/{path}', {
  owner: 'octocat',
  repo: 'hello-world',
  path: 'path',
  message: 'message',
  content: 'content'
})

Example for updating a file

Status: 200 OK
{
  "content": {
    "name": "hello.txt",
    "path": "notes/hello.txt",
    "sha": "a56507ed892d05a37c6d6128c260937ea4d287bd",
    "size": 9,
    "url": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt",
    "html_url": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt",
    "git_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/a56507ed892d05a37c6d6128c260937ea4d287bd",
    "download_url": "https://raw.githubusercontent.com/octocat/HelloWorld/master/notes/hello.txt",
    "type": "file",
    "_links": {
      "self": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt",
      "git": "https://api.github.com/repos/octocat/Hello-World/git/blobs/a56507ed892d05a37c6d6128c260937ea4d287bd",
      "html": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt"
    }
  },
  "commit": {
    "sha": "18a43cd8e1e3a79c786e3d808a73d23b6d212b16",
    "node_id": "MDY6Q29tbWl0MThhNDNjZDhlMWUzYTc5Yzc4NmUzZDgwOGE3M2QyM2I2ZDIxMmIxNg==",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/18a43cd8e1e3a79c786e3d808a73d23b6d212b16",
    "html_url": "https://github.com/octocat/Hello-World/git/commit/18a43cd8e1e3a79c786e3d808a73d23b6d212b16",
    "author": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Monalisa Octocat",
      "email": "octocat@github.com"
    },
    "committer": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Monalisa Octocat",
      "email": "octocat@github.com"
    },
    "message": "my commit message",
    "tree": {
      "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/9a21f8e2018f42ffcf369b24d2cd20bc25c9e66f",
      "sha": "9a21f8e2018f42ffcf369b24d2cd20bc25c9e66f"
    },
    "parents": [
      {
        "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/da5a433788da5c255edad7979b328b67d79f53f6",
        "html_url": "https://github.com/octocat/Hello-World/git/commit/da5a433788da5c255edad7979b328b67d79f53f6",
        "sha": "da5a433788da5c255edad7979b328b67d79f53f6"
      }
    ],
    "verification": {
      "verified": false,
      "reason": "unsigned",
      "signature": null,
      "payload": null
    }
  }
}

Example for creating a file

Status: 201 Created
{
  "content": {
    "name": "hello.txt",
    "path": "notes/hello.txt",
    "sha": "95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "size": 9,
    "url": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt",
    "html_url": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt",
    "git_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "download_url": "https://raw.githubusercontent.com/octocat/HelloWorld/master/notes/hello.txt",
    "type": "file",
    "_links": {
      "self": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt",
      "git": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
      "html": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt"
    }
  },
  "commit": {
    "sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
    "node_id": "MDY6Q29tbWl0NzYzODQxN2RiNmQ1OWYzYzQzMWQzZTFmMjYxY2M2MzcxNTU2ODRjZA==",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd",
    "html_url": "https://github.com/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd",
    "author": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Monalisa Octocat",
      "email": "octocat@github.com"
    },
    "committer": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Monalisa Octocat",
      "email": "octocat@github.com"
    },
    "message": "my commit message",
    "tree": {
      "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
      "sha": "691272480426f78a0138979dd3ce63b77f706feb"
    },
    "parents": [
      {
        "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "html_url": "https://github.com/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5"
      }
    ],
    "verification": {
      "verified": false,
      "reason": "unsigned",
      "signature": null,
      "payload": null
    }
  }
}

Resource not found

Status: 404 Not Found

Conflict

Status: 409 Conflict

Validation failed

Status: 422 Unprocessable Entity

Notes

Delete a file

Deletes a file in a repository.

You can provide an additional committer parameter, which is an object containing information about the committer. Or, you can provide an author parameter, which is an object containing information about the author.

The author section is optional and is filled in with the committer information if omitted. If the committer information is omitted, the authenticated user's information is used.

You must provide values for both name and email, whether you choose to use author or committer. Otherwise, you'll receive a 422 status code.

delete /repos/{owner}/{repo}/contents/{path}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
path string path

path+ parameter
message string body

Required. The commit message.
sha string body

Required. The blob SHA of the file being replaced.
branch string body

The branch name. Default: the repository’s default branch (usually master)
committer object body

object containing information about the committer.

Properties of the committer object
name (string)

The name of the author (or committer) of the commit
email (string)

The email of the author (or committer) of the commit
author object body

object containing information about the author.

Properties of the author object
name (string)

The name of the author (or committer) of the commit
email (string)

The email of the author (or committer) of the commit

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/contents/PATH \
  -d '{"message":"message","sha":"sha"}'
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/contents/{path}', {
  owner: 'octocat',
  repo: 'hello-world',
  path: 'path',
  message: 'message',
  sha: 'sha'
})

Default response

Status: 200 OK
{
  "content": null,
  "commit": {
    "sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
    "node_id": "MDY6Q29tbWl0NzYzODQxN2RiNmQ1OWYzYzQzMWQzZTFmMjYxY2M2MzcxNTU2ODRjZA==",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd",
    "html_url": "https://github.com/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd",
    "author": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Monalisa Octocat",
      "email": "octocat@github.com"
    },
    "committer": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Monalisa Octocat",
      "email": "octocat@github.com"
    },
    "message": "my commit message",
    "tree": {
      "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
      "sha": "691272480426f78a0138979dd3ce63b77f706feb"
    },
    "parents": [
      {
        "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "html_url": "https://github.com/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5"
      }
    ],
    "verification": {
      "verified": false,
      "reason": "unsigned",
      "signature": null,
      "payload": null
    }
  }
}

Resource not found

Status: 404 Not Found

Conflict

Status: 409 Conflict

Validation failed

Status: 422 Unprocessable Entity

Service unavailable

Status: 503 Service Unavailable

Notes

Get a repository README

Gets the preferred README for a repository.

READMEs support custom media types for retrieving the raw content or rendered HTML.

get /repos/{owner}/{repo}/readme

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
ref string query

The name of the commit/branch/tag. Default: the repository’s default branch (usually master)

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/readme
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/readme', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
{
  "type": "file",
  "encoding": "base64",
  "size": 5362,
  "name": "README.md",
  "path": "README.md",
  "content": "encoded content ...",
  "sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
  "url": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
  "git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
  "html_url": "https://github.com/octokit/octokit.rb/blob/master/README.md",
  "download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/README.md",
  "_links": {
    "git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
    "html": "https://github.com/octokit/octokit.rb/blob/master/README.md"
  }
}

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes

Download a repository archive (tar)

Gets a redirect URL to download a tar archive for a repository. If you omit :ref, the repository’s default branch (usually master) will be used. Please make sure your HTTP framework is configured to follow redirects or you will need to use the Location header to make a second GET request. Note: For private repositories, these links are temporary and expire after five minutes.

get /repos/{owner}/{repo}/tarball/{ref}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
ref string path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/tarball/REF
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/tarball/{ref}', {
  owner: 'octocat',
  repo: 'hello-world',
  ref: 'ref'
})

Response

Status: 302 Found

Notes

Download a repository archive (zip)

Gets a redirect URL to download a zip archive for a repository. If you omit :ref, the repository’s default branch (usually master) will be used. Please make sure your HTTP framework is configured to follow redirects or you will need to use the Location header to make a second GET request. Note: For private repositories, these links are temporary and expire after five minutes.

get /repos/{owner}/{repo}/zipball/{ref}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
ref string path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/zipball/REF
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/zipball/{ref}', {
  owner: 'octocat',
  repo: 'hello-world',
  ref: 'ref'
})

Response

Status: 302 Found

Notes

Deploy keys

You can launch projects from a GitHub Enterprise Server repository to your server by using a deploy key, which is an SSH key that grants access to a single repository. GitHub Enterprise Server attaches the public part of the key directly to your repository instead of a personal user account, and the private part of the key remains on your server. For more information, see "Delivering deployments."

Deploy keys can either be setup using the following API endpoints, or by using GitHub. To learn how to set deploy keys up in GitHub, see "Managing deploy keys."

get /repos/{owner}/{repo}/keys

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/keys
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/keys', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "key": "ssh-rsa AAA...",
    "url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
    "title": "octocat@octomac",
    "verified": true,
    "created_at": "2014-12-10T15:53:42Z",
    "read_only": true
  }
]

Notes

Create a deploy key

You can create a read-only deploy key.

post /repos/{owner}/{repo}/keys

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
title string body

A name for the key.
key string body

Required. The contents of the key.
read_only boolean body

If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.

Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see "Repository permission levels for an organization" and "Permission levels for a user account repository."

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/keys \
  -d '{"key":"key"}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/keys', {
  owner: 'octocat',
  repo: 'hello-world',
  key: 'key'
})

Default response

Status: 201 Created
{
  "id": 1,
  "key": "ssh-rsa AAA...",
  "url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
  "title": "octocat@octomac",
  "verified": true,
  "created_at": "2014-12-10T15:53:42Z",
  "read_only": true
}

Validation failed

Status: 422 Unprocessable Entity

Notes

get /repos/{owner}/{repo}/keys/{key_id}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
key_id integer path

key_id parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/keys/42
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  key_id: 42
})

Default response

Status: 200 OK
{
  "id": 1,
  "key": "ssh-rsa AAA...",
  "url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
  "title": "octocat@octomac",
  "verified": true,
  "created_at": "2014-12-10T15:53:42Z",
  "read_only": true
}

Resource not found

Status: 404 Not Found

Notes

Delete a deploy key

Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.

delete /repos/{owner}/{repo}/keys/{key_id}

Parameters

Name Type In Description
accept string header

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

owner string path
repo string path
key_id integer path

key_id parameter

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/keys/42
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  key_id: 42
})

Default Response

Status: 204 No Content

Notes

Deployments

Deployments are requests to deploy a specific ref (branch, SHA, tag). GitHub dispatches a deployment event that external services can listen for and act on when new deployments are created. Deployments enable developers and organizations to build loosely coupled tooling around deployments, without having to worry about the implementation details of delivering different types of applications (e.g., web, native).

Deployment statuses allow external services to mark deployments with an error, failure, pending, in_progress, queued, or success state that systems listening to deployment_status events can consume.

Deployment statuses can also include an optional description and log_url, which are highly recommended because they make deployment statuses more useful. The log_url is the full URL to the deployment output, and the description is a high-level summary of what happened with the deployment.

GitHub dispatches deployment and deployment_status events when new deployments and deployment statuses are created. These events allows third-party integrations to receive respond to deployment requests and update the status of a deployment as progress is made.

Below is a simple sequence diagram for how these interactions would work.

+---------+             +--------+            +-----------+        +-------------+
| Tooling |             | GitHub |            | 3rd Party |        | Your Server |
+---------+             +--------+            +-----------+        +-------------+
     |                      |                       |                     |
     |  Create Deployment   |                       |                     |
     |--------------------->|                       |                     |
     |                      |                       |                     |
     |  Deployment Created  |                       |                     |
     |<---------------------|                       |                     |
     |                      |                       |                     |
     |                      |   Deployment Event    |                     |
     |                      |---------------------->|                     |
     |                      |                       |     SSH+Deploys     |
     |                      |                       |-------------------->|
     |                      |                       |                     |
     |                      |   Deployment Status   |                     |
     |                      |<----------------------|                     |
     |                      |                       |                     |
     |                      |                       |   Deploy Completed  |
     |                      |                       |<--------------------|
     |                      |                       |                     |
     |                      |   Deployment Status   |                     |
     |                      |<----------------------|                     |
     |                      |                       |                     |

Keep in mind that GitHub is never actually accessing your servers. It's up to your third-party integration to interact with deployment events. Multiple systems can listen for deployment events, and it's up to each of those systems to decide whether they're responsible for pushing the code out to your servers, building native code, etc.

Note that the repo_deployment OAuth scope grants targeted access to deployments and deployment statuses without granting access to repository code, while the public_repo and repo scopes grant permission to code as well.

Inactive deployments

When you set the state of a deployment to success, then all prior non-transient, non-production environment deployments in the same repository will become inactive. To avoid this, you can set auto_inactive to false when creating the deployment status.

You can communicate that a transient environment no longer exists by setting its state to inactive. Setting the state to inactive shows the deployment as destroyed in GitHub and removes access to it.

List deployments

Simple filtering of deployments is available via query parameters:

get /repos/{owner}/{repo}/deployments

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
sha string query

The SHA recorded at creation time.
ref string query

The name of the ref. This can be a branch, tag, or SHA.
task string query

The name of the task for the deployment (e.g., deploy or deploy:migrations).
environment string query

The name of the environment that was deployed to (e.g., staging or production).
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/deployments
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/deployments', {
  owner: 'octocat',
  repo: 'hello-world'
})

Default response

Status: 200 OK
[
  {
    "url": "https://api.github.com/repos/octocat/example/deployments/1",
    "id": 1,
    "node_id": "MDEwOkRlcGxveW1lbnQx",
    "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
    "ref": "topic-branch",
    "task": "deploy",
    "payload": {},
    "original_environment": "staging",
    "environment": "production",
    "description": "Deploy request from hubot",
    "creator": {
      "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
    },
    "created_at": "2012-07-20T01:19:13Z",
    "updated_at": "2012-07-20T01:19:13Z",
    "statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses",
    "repository_url": "https://api.github.com/repos/octocat/example",
    "transient_environment": false,
    "production_environment": true
  }
]

Notes

Preview notice

The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.ant-man-preview+json

Create a deployment

Deployments offer a few configurable parameters with certain defaults.

The ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them before we merge a pull request.

The environment parameter allows deployments to be issued to different runtime environments. Teams often have multiple environments for verifying their applications, such as production, staging, and qa. This parameter makes it easier to track which environments have requested deployments. The default environment is production.

The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If the ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds, the API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will return a failure response.

By default, commit statuses for every submitted context must be in a success state. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to specify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do not require any contexts or create any commit statuses, the deployment will always succeed.

The payload parameter is available for any extra information that a deployment system might need. It is a JSON text field that will be passed on when a deployment event is dispatched.

The task parameter is used by the deployment system to allow different execution paths. In the web world this might be deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an application with debugging enabled.

Users with repo or repo_deployment scopes can create a deployment for a given ref.

Merged branch response

You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating a deployment. This auto-merge happens when:

  • Auto-merge option is enabled in the repository
  • Topic branch does not include the latest changes on the base branch, which is master in the response example
  • There are no merge conflicts

If there are no new commits in the base branch, a new request to create a deployment should give a successful response.

Merge conflict response

This error happens when the auto_merge option is enabled and when the default branch (in this case master), can't be merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.

Failed commit status checks

This error happens when the required_contexts parameter indicates that one or more contexts need to have a success status for the commit to be deployed, but one or more of the required contexts do not have a state of success.

post /repos/{owner}/{repo}/deployments

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

owner string path
repo string path
ref string body

Required. The ref to deploy. This can be a branch, tag, or SHA.
task string body

Specifies a task to execute (e.g., deploy or deploy:migrations).

Default: deploy
auto_merge boolean body

Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.

Default: true
required_contexts array of strings body

The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
payload string body

JSON payload with extra information about the deployment.
environment string body

Name for the target deployment environment (e.g., production, staging, qa).

Default: production
description string or null body

Short description of the deployment.
transient_environment boolean body

Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type. Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
production_environment boolean body

Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
created_at string body

undefined

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/deployments \
  -d '{"ref":"ref"}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /repos/{owner}/{repo}/deployments', {
  owner: 'octocat',
  repo: 'hello-world',
  ref: 'ref'
})

Simple example

Status: 201 Created
{
  "url": "https://api.github.com/repos/octocat/example/deployments/1",
  "id": 1,
  "node_id": "MDEwOkRlcGxveW1lbnQx",
  "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
  "ref": "topic-branch",
  "task": "deploy",
  "payload": {},
  "original_environment": "staging",
  "environment": "production",
  "description": "Deploy request from hubot",
  "creator": {
    "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
  },
  "created_at": "2012-07-20T01:19:13Z",
  "updated_at": "2012-07-20T01:19:13Z",
  "statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses",
  "repository_url": "https://api.github.com/repos/octocat/example",
  "transient_environment": false,
  "production_environment": true
}

Advanced example

Status: 201 Created
{
  "url": "https://api.github.com/repos/octocat/example/deployments/1",
  "id": 1,
  "node_id": "MDEwOkRlcGxveW1lbnQx",
  "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
  "ref": "topic-branch",
  "task": "deploy",
  "payload": {},
  "original_environment": "staging",
  "environment": "production",
  "description": "Deploy request from hubot",
  "creator": {
    "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
  },
  "created_at": "2012-07-20T01:19:13Z",
  "updated_at": "2012-07-20T01:19:13Z",
  "statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses",
  "repository_url": "https://api.github.com/repos/octocat/example",
  "transient_environment": false,
  "production_environment": true
}

Merged branch response

Status: 202 Accepted
{
  "message": "Auto-merged master into topic-branch on deployment."
}

Merge conflict response

Status: 409 Conflict
{
  "message": "Conflict merging master into topic-branch"
}

Failed commit status checks

Status: 409 Conflict
{
  "message": "Conflict: Commit status checks failed for topic-branch."
}

Validation failed

Status: 422 Unprocessable Entity

Notes

Preview notice

The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.ant-man-preview+json

get /repos/{owner}/{repo}/deployments/{deployment_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notices

owner string path
repo string path
deployment_id integer path

deployment_id parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/deployments/42
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  deployment_id: 42
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/example/deployments/1",
  "id": 1,
  "node_id": "MDEwOkRlcGxveW1lbnQx",
  "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
  "ref": "topic-branch",
  "task": "deploy",
  "payload": {},
  "original_environment": "staging",
  "environment": "production",
  "description": "Deploy request from hubot",
  "creator": {
    "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
  },
  "created_at": "2012-07-20T01:19:13Z",
  "updated_at": "2012-07-20T01:19:13Z",
  "statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses",
  "repository_url": "https://api.github.com/repos/octocat/example",
  "transient_environment": false,
  "production_environment": true
}

Resource not found

Status: 404 Not Found

Notes

Preview notices

If an issue event is created via a GitHub App, the response will include the performed_via_github_app object with information about the GitHub App. For more information, see the related blog post. To receive the performed_via_github_app object in the response, you must provide a custom media type in the Accept header:

application/vnd.github.machine-man-preview

The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.ant-man-preview+json

List deployment statuses

Users with pull access can view deployment statuses for a deployment:

get /repos/{owner}/{repo}/deployments/{deployment_id}/statuses

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notices

owner string path
repo string path
deployment_id integer path

deployment_id parameter
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/deployments/42/statuses
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}/statuses', {
  owner: 'octocat',
  repo: 'hello-world',
  deployment_id: 42
})

Default response

Status: 200 OK
[
  {
    "url": "https://api.github.com/repos/octocat/example/deployments/42/statuses/1",
    "id": 1,
    "node_id": "MDE2OkRlcGxveW1lbnRTdGF0dXMx",
    "state": "success",
    "creator": {
      "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
    },
    "description": "Deployment finished successfully.",
    "environment": "production",
    "target_url": "https://example.com/deployment/42/output",
    "created_at": "2012-07-20T01:19:13Z",
    "updated_at": "2012-07-20T01:19:13Z",
    "deployment_url": "https://api.github.com/repos/octocat/example/deployments/42",
    "repository_url": "https://api.github.com/repos/octocat/example",
    "environment_url": "https://test-branch.lab.acme.com",
    "log_url": "https://example.com/deployment/42/output"
  }
]

Resource not found

Status: 404 Not Found

Notes

Preview notices

New features in the Deployments API on GitHub are currently available during a public beta. Please see the blog post for full details.

To access the new environment parameter, the two new values for the state parameter (in_progress and queued), and use auto_inactive on production deployments during the public beta period, you must provide the following custom media type in the Accept header:

application/vnd.github.flash-preview+json

The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.ant-man-preview+json

Create a deployment status

Users with push access can create deployment statuses for a given deployment.

GitHub Apps require read & write access to "Deployments" and read-only access to "Repo contents" (for private repos). OAuth Apps require the repo_deployment scope.

post /repos/{owner}/{repo}/deployments/{deployment_id}/statuses

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notices

owner string path
repo string path
deployment_id integer path

deployment_id parameter
state string body

Required. The state of the status. Can be one of error, failure, inactive, in_progress, queued pending, or success. Note: To use the inactive state, you must provide the application/vnd.github.ant-man-preview+json custom media type. To use the in_progress and queued states, you must provide the application/vnd.github.flash-preview+json custom media type. When you set a transient deployment to inactive, the deployment will be shown as destroyed in GitHub.
target_url string body

The target URL to associate with this status. This URL should contain output to keep the user updated while the task is running or serve as historical information for what happened in the deployment. Note: It's recommended to use the log_url parameter, which replaces target_url.
log_url string body

The full URL of the deployment's output. This parameter replaces target_url. We will continue to accept target_url to support legacy uses, but we recommend replacing target_url with log_url. Setting log_url will automatically set target_url to the same value. Default: ""
Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type. Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
description string body

A short description of the status. The maximum description length is 140 characters.
environment string body

Name for the target deployment environment, which can be changed when setting a deploy status. For example, production, staging, or qa. Note: This parameter requires you to use the application/vnd.github.flash-preview+json custom media type.
environment_url string body

Sets the URL for accessing your environment. Default: ""
Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type. Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
auto_inactive boolean body

Adds a new inactive status to all prior non-transient, non-production environment deployments with the same repository and environment name as the created status's deployment. An inactive status is only added to deployments that had a success state. Default: true
Note: To add an inactive status to production environments, you must use the application/vnd.github.flash-preview+json custom media type.
Note: This parameter requires you to use the application/vnd.gith