Contents

These API methods let you retrieve the contents of files within a repository as Base64 encoded content. See media types for requesting the raw format or rendered HTML (when supported).

Get the README

This method returns the preferred README for a repository.

GET /repos/:owner/:repo/readme

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

Parameters

Name Type Description
ref string The name of the commit/branch/tag. Default: the repository’s default branch (usually master)

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

Get contents

This method returns the contents of a file or directory in a repository.

GET /repos/:owner/:repo/contents/:path

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.

Parameters

Name Type Description
path string The content path.
ref string The name of the commit/branch/tag. Default: the repository’s default branch (usually master)

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

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".

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

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 above).

Otherwise, the API responds with an object describing the symlink itself:

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

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.

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

Create a file

This method creates a new file in a repository

PUT /repos/:owner/:repo/contents/:path

Parameters

Name Type Description
path string Required. The content path.
message string Required. The commit message.
content string Required. The new file content, Base64 encoded.
branch string The branch name. Default: the repository’s default branch (usually master)

Optional Parameters

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.

Both the author and committer parameters have the same keys:

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

Example Input

{
  "message": "my commit message",
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com"
  },
  "content": "bXkgbmV3IGZpbGUgY29udGVudHM="
}

Response

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",
    "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": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Scott Chacon",
      "email": "schacon@gmail.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
    }
  }
}

Update a file

This method updates a file in a repository

PUT /repos/:owner/:repo/contents/:path

Parameters

Name Type Description
path string Required. The content path.
message string Required. The commit message.
content string Required. The updated file content, Base64 encoded.
sha string Required. The blob SHA of the file being replaced.
branch string The branch name. Default: the repository’s default branch (usually master)

Optional Parameters

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.

Both the author and committer parameters have the same keys:

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

Example Input

{
  "message": "my commit message",
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com"
  },
  "content": "bXkgdXBkYXRlZCBmaWxlIGNvbnRlbnRz",
  "sha": "329688480d39049927147c162b9d2deaf885005f"
}

Response

Status: 200 OK
{
  "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",
    "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": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Scott Chacon",
      "email": "schacon@gmail.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
    }
  }
}

Delete a file

This method deletes a file in a repository

DELETE /repos/:owner/:repo/contents/:path

Parameters

Name Type Description
path string Required. The content path.
message string Required. The commit message.
sha string Required. The blob SHA of the file being replaced.
branch string The branch name. Default: the repository’s default branch (usually master)

Optional Parameters

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.

Both the author and committer parameters have the same keys:

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

Example Input

{
  "message": "my commit message",
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com"
  },
  "sha": "329688480d39049927147c162b9d2deaf885005f"
}

Response

Status: 200 OK
{
  "content": null,
  "commit": {
    "sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
    "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": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2014-11-07T22:01:45Z",
      "name": "Scott Chacon",
      "email": "schacon@gmail.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
    }
  }
}

Get archive link

This method will return a 302 to a URL to download a tarball or zipball archive for a repository. 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/:archive_format/:ref

Parameters

Name Type Description
archive_format string Can be either tarball or zipball. Default: tarball
ref string A valid Git reference. Default: the repository’s default branch (usually master)

Response

Status: 302 Found
Location: https://codeload.github.com/me/myprivate/legacy.zip/master?login=me&token=thistokenexpires

To follow redirects with curl, use the -L switch:

$curl -L https://api.github.com/repos/octokit/octokit.rb/tarball > octokit.tar.gz

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
100  206k  100  206k    0     0   146k      0  0:00:01  0:00:01 --:--:--  790k

Custom media types

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.