Text of docs.github.com › en › rest › repos › contents as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

REST API endpoints for repository contents - GitHub Docs

Skip to main content Skip to content Collapse sidebar Expand sidebar The REST API is now versioned. For more information, see " About API versioning ." REST API endpoints for repository contents Use the REST API to create, modify, and delete Base64 encoded content in a repository. Get repository content Gets the contents of a file or directory in a repository. Specify the file path or directory with the path parameter.

If you omit the path parameter, you will receive the contents of the repository's root directory. This endpoint supports the following custom media types. For more information, see " Media types ." application/vnd.github.raw+json : Returns the raw file contents for files and symlinks. application/vnd.github.html+json : Returns the file contents in HTML. Markup languages are rendered to HTML using GitHub's open-source Markup library . application/vnd.github.object+json : Returns 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. If the content is a directory: The response will be an array of objects, one object for each item in the directory. If the content is a symlink and the symlink's target is a normal file in the repository, then the API responds with the content of the file. Otherwise, the API responds with an object describing the symlink itself.

If the content is a submodule, the submodule_git_url field 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.

Notes : 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 . Download URLs expire and are meant to be used just once. To ensure the download URL does not expire, please use the contents API to obtain a fresh download URL for each download. If the requested file's size is: 1 MB or smaller: All features of this endpoint are supported.

Between 1-100 MB: Only the raw or object custom media types are supported. Both will work as normal, except that when using the object media type, the content field will be an empty string and the encoding field will be "none" . To get the contents of these larger files, use the raw media type. Greater than 100 MB: This endpoint is not supported. Fine-grained access tokens for "Get repository content" This endpoint works with the following fine-grained token types : GitHub App user access tokens GitHub App installation access tokens Fine-grained personal access tokens The fine-grained token must have the following permission set: "Contents" repository permissions (read) This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "Get repository content" Headers Name, Type, Description accept string Setting to application/vnd.github+json is recommended. Path parameters Name, Type, Description owner string Required The account owner of the repository. The name is not case sensitive. repo string Required The name of the repository without the .git extension. The name is not case sensitive. path string Required path parameter Query parameters Name, Type, Description ref string The name of the commit/branch/tag.

Default: the repository’s default branch. HTTP response status codes for "Get repository content" Status code Description 200 OK 302 Found 304 Not modified 403 Forbidden 404 Resource not found Code samples for "Get repository content" Request examples Select the example type get /repos /{owner} /{repo} /contents /{path} Copy to clipboard curl request example curl -L \ -H "Accept: application/vnd.github.object" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2026-03-10" \ https://api.github.com/repos/OWNER/REPO/contents/PATH Response if content is a file Status: 200 { "type": "file", "encoding": "base64", "size": 5362, "name": "README.md", "path": "README.md", "content": "IyBZb2dhIEJvmsgaW4gcHJvZ3Jlc3MhIEZlZWwgdAoKOndhcm5pbmc6IFdvc\\nZnJlZSBmUgdG8gY0byBjaGVjayBvdXQgdGhlIGFwcCwgYnV0IGJlIHN1c29t\\nZSBiYWNrIG9uY2UgaXQgaXMgY29tcGxldGUuCgpBIHdlYiBhcHAgdGhhdCBs\\nZWFkcyB5b3UgdGhyb3VnaCBhIHlvZ2Egc2Vzc2lvbi4KCltXb3Jrb3V0IG5v\\ndyFdKGh0dHBzOi8vc2tlZHdhcmRzODguZ2l0aHViLmlvL3lvZ2EvKQoKPGlt\\nZyBzcmM9InNyYy9pbWFnZXMvbWFza2FibGVfaWNvbl81MTIucG5nIiBhbHQ9\\nImJvdCBsaWZ0aW5nIHdlaWdodHMiIHdpZHRoPSIxMDAiLz4KCkRvIHlvdSBo\\nYXZlIGZlZWRiYWNrIG9yIGlkZWFzIGZvciBpbXByb3ZlbWVudD8gW09wZW4g\\nYW4gaXNzdWVdKGh0dHBzOi8vZ2l0aHViLmNvbS9za2Vkd2FyZHM4OC95b2dh\\nL2lzc3Vlcy9uZXcpLgoKV2FudCBtb3JlIGdhbWVzPyBWaXNpdCBbQ25TIEdh\\nbWVzXShodHRwczovL3NrZWR3YXJkczg4LmdpdGh1Yi5pby9wb3J0Zm9saW8v\\nKS4KCiMjIERldmVsb3BtZW50CgpUbyBhZGQgYSBuZXcgcG9zZSwgYWRkIGFu\\nIGVudHJ5IHRvIHRoZSByZWxldmFudCBmaWxlIGluIGBzcmMvYXNhbmFzYC4K\\nClRvIGJ1aWxkLCBydW4gYG5wbSBydW4gYnVpbGRgLgoKVG8gcnVuIGxvY2Fs\\nbHkgd2l0aCBsaXZlIHJlbG9hZGluZyBhbmQgbm8gc2VydmljZSB3b3JrZXIs\\nIHJ1biBgbnBtIHJ1biBkZXZgLiAoSWYgYSBzZXJ2aWNlIHdvcmtlciB3YXMg\\ncHJldmlvdXNseSByZWdpc3RlcmVkLCB5b3UgY2FuIHVucmVnaXN0ZXIgaXQg\\naW4gY2hyb21lIGRldmVsb3BlciB0b29sczogYEFwcGxpY2F0aW9uYCA+IGBT\\nZXJ2aWNlIHdvcmtlcnNgID4gYFVucmVnaXN0ZXJgLikKClRvIHJ1biBsb2Nh\\nbGx5IGFuZCByZWdpc3RlciB0aGUgc2VydmljZSB3b3JrZXIsIHJ1biBgbnBt\\nIHN0YXJ0YC4KClRvIGRlcGxveSwgcHVzaCB0byBgbWFpbmAgb3IgbWFudWFs\\nbHkgdHJpZ2dlciB0aGUgYC5naXRodWIvd29ya2Zsb3dzL2RlcGxveS55bWxg\\nIHdvcmtmbG93Lgo=\\n", "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" } } Create or update file contents Creates a new file or replaces an existing file in a repository.

Note If you use this endpoint and the " Delete a file " endpoint in parallel, the concurrent requests will conflict and you will receive errors. You must use these endpoints serially instead. OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint. The workflow scope is also required in order to modify files in the .github/workflows directory. Fine-grained access tokens for "Create or update file contents" This endpoint works with the following fine-grained token types : GitHub App user access tokens GitHub App installation access tokens Fine-grained personal access tokens The fine-grained token must have at least one of the following permission sets: "Contents" repository permissions (write) "Contents" repository permissions (write) and "Workflows" repository permissions (write) Parameters for "Create or update file contents" Headers Name, Type, Description accept string Setting to application/vnd.github+json is recommended.

Path parameters Name, Type, Description owner string Required The account owner of the repository. The name is not case sensitive. repo string Required The name of the repository without the .git extension. The name is not case sensitive. path string Required path parameter Body parameters Name, Type, Description message string Required The commit message. content string Required The new file content,

The rest of this page is on the live site.