LFE Docs

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "type": "file",
  "encoding": "base64",
  "size": 5362,
  "name": "README.md",
  "path": "README.md",
  "content": "encoded content ...",
  "sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
  "url": "https://api.github.com/repos/pengwynn/octokit/contents/README.md",
  "git_url": "https://api.github.com/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
  "html_url": "https://github.com/pengwynn/octokit/blob/master/README.md",
  "download_url": "https://raw.githubusercontent.com/pengwynn/octokit/master/README.md",
  "_links": {
    "git": "https://api.github.com/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://api.github.com/repos/pengwynn/octokit/contents/README.md",
    "html": "https://github.com/pengwynn/octokit/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). Directories and submodules do not support custom media types.

Notes:

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "type": "file",
  "encoding": "base64",
  "size": 5362,
  "name": "README.md",
  "path": "README.md",
  "content": "encoded content ...",
  "sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
  "url": "https://api.github.com/repos/pengwynn/octokit/contents/README.md",
  "git_url": "https://api.github.com/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
  "html_url": "https://github.com/pengwynn/octokit/blob/master/README.md",
  "download_url": "https://raw.githubusercontent.com/pengwynn/octokit/master/README.md",
  "_links": {
    "git": "https://api.github.com/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://api.github.com/repos/pengwynn/octokit/contents/README.md",
    "html": "https://github.com/pengwynn/octokit/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.

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

Note: 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”.

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "type": "symlink",
  "target": "/path/to/symlink/target",
  "size": 23,
  "name": "some-symlink",
  "path": "bin/some-symlink",
  "sha": "452a98979c88e093d682cab404a3ec82babebb48",
  "url": "https://api.github.com/repos/pengwynn/octokit/contents/bin/some-symlink",
  "git_url": "https://api.github.com/repos/pengwynn/octokit/git/blobs/452a98979c88e093d682cab404a3ec82babebb48",
  "html_url": "https://github.com/pengwynn/octokit/blob/master/bin/some-symlink",
  "download_url": "https://raw.githubusercontent.com/pengwynn/octokit/master/bin/some-symlink",
  "_links": {
    "git": "https://api.github.com/repos/pengwynn/octokit/git/blobs/452a98979c88e093d682cab404a3ec82babebb48",
    "self": "https://api.github.com/repos/pengwynn/octokit/contents/bin/some-symlink",
    "html": "https://github.com/pengwynn/octokit/blob/master/bin/some-symlink"
  }
}

Response if content is a submodule

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "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"
  }
}

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.

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "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": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2010-04-10T14:10:01-07:00",
      "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"
      }
    ]
  }
}

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "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": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2010-04-10T14:10:01-07:00",
      "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"
      }
    ]
  }
}

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "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": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2010-04-10T14:10:01-07:00",
      "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"
      }
    ]
  }
}

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

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

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

curl -L https://api.github.com/repos/pengwynn/octokit/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.

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