Skip to main content

contents

Overview

Namecontents
TypeResource
Idgithub.repos.contents

Fields

NameDatatype
namestring
urlstring
download_urlstring
typestring
git_urlstring
targetstring
html_urlstring
encodingstring
sizeinteger
_linksobject
shastring
pathstring
submodule_git_urlstring
contentstring

Methods

NameAccessible byRequired ParamsDescription
get_readmeSELECTowner, repoGets the preferred README for a repository.

READMEs support custom media types for retrieving the raw content or rendered HTML.
get_readme_in_directorySELECTdir, owner, repoGets the README from a repository directory.

READMEs support custom media types for retrieving the raw content or rendered HTML.
create_or_update_file_contentsINSERTowner, path, repo, data__content, data__messageCreates a new file or replaces an existing file in a repository.
delete_fileDELETEowner, path, repo, data__message, data__shaDeletes 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.
download_tarball_archiveEXECowner, ref, repoGets 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.
download_zipball_archiveEXECowner, ref, repoGets 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_contentEXECowner, path, repoGets 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 the repository's root directory. See the description below regarding what the API response includes for directories.

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.