Repo Contents API

Get the README
Get contents
Create a file
Update a file
Delete a file
Get archive link
Custom media types

These API methods let you retrieve the contents of files within a repository as Base64 encoded content. See media types for requesting raw format.

Get the README

This method returns the preferred README for a repository.

GET /repos/:owner/:repo/readme

READMEs support a custom media type for getting the raw content.

Parameters

ref: Optional string - The String name of the Commit/Branch/Tag. Defaults to 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",
  "_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 getting the raw content. Directories and submodules do not support custom media types.

Notes:

To get a repository’s contents recursively, you can recursively get the tree.
This API supports files up to 1 megabyte in size.

Parameters

path: Optional string - The content path.
ref: Optional string - The String name of the Commit/Branch/Tag. Defaults to 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",
  "_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

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",
    "_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",
    "_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"
    }
  }
]

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 a hash 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",
  "_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",
  "_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

path: Required string - The content path.
message: Required string - The commit message.
content: Required string - The new file content, Base64 encoded.
branch: Optional string - The branch name. If not provided, uses the repository’s default branch (usually master).

Optional Parameters

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 500 status code.

author.name: string - The name of the author of the commit
author.email: string - The email of the author of the commit
committer.name: string - The name of the committer of the commit
committer.email: string - The email of the 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": "hellothere",
    "path": "hellothere",
    "sha": "95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "size": 9,
    "url": "https://api.github.com/repos/octocat/Hello-World/contents/hellothere",
    "html_url": "https://github.com/octocat/Hello-World/blob/master/hellothere",
    "git_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "type": "file",
    "_links": {
      "self": "https://api.github.com/repos/octocat/Hello-World/contents/hellothere",
      "git": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
      "html": "https://github.com/octocat/Hello-World/blob/master/hellothere"
    }
  },
  "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

path: Required string - The content path.
message: Required string - The commit message.
content: Required string - The updated file content, Base64 encoded.
sha: Required string - The blob SHA of the file being replaced.
branch: Optional string - The branch name. If not provided, uses the repository’s default branch (usually master).

Optional Parameters

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 500 status code.

author.name: string - The name of the author of the commit
author.email: string - The email of the author of the commit
committer.name: string - The name of the committer of the commit
committer.email: string - The email of the 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": "hellothere",
    "path": "hellothere",
    "sha": "95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "size": 9,
    "url": "https://api.github.com/repos/octocat/Hello-World/contents/hellothere",
    "html_url": "https://github.com/octocat/Hello-World/blob/master/hellothere",
    "git_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "type": "file",
    "_links": {
      "self": "https://api.github.com/repos/octocat/Hello-World/contents/hellothere",
      "git": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
      "html": "https://github.com/octocat/Hello-World/blob/master/hellothere"
    }
  },
  "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

path: Required string - The content path.
message: Required string - The commit message.
sha: Required string - The blob SHA of the file being removed.
branch: Optional string - The branch name. If not provided, uses the repository’s default branch (usually master).

Optional Parameters

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 500 status code.

author.name: string - The name of the author of the commit
author.email: string - The email of the author of the commit
committer.name: string - The name of the committer of the commit
committer.email: string - The email of the 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"
      }
    ]
  }
}

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

GET /repos/:owner/:repo/:archive_format/:ref

Parameters

archive_format: Either tarball or zipball
ref: Optional string - valid Git reference, defaults to master

Response

Status: 302 Found
Location: http://github.com/me/myprivate/tarball/master?SSO=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 type.

application/vnd.github.VERSION.raw

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

Repo Contents API

Get the README

Parameters

Response

Get contents

Parameters

Response if content is a file

Response if content is a directory

Response if content is a symlink

Response if content is a submodule

Create a file

Parameters

Optional Parameters

Example Input

Response

Update a file

Parameters

Optional Parameters

Example Input

Response

Delete a file

Parameters

Optional Parameters

Example Input

Response

Get archive link

Parameters

Response

Custom media types

GitHub

Tools

Extras

Documentation