REST API 现在已版本化。 有关更多信息，请参阅 "关于 API 版本控制”。
仓库内容的 REST API 端点
使用 REST API 在仓库中创建、修改和删除 Base64 编码的内容。
获取仓库内容
获取仓库中文件或目录的内容。使用 path 参数指定文件路径或目录。如果省略 path 参数，您将收到仓库根目录的内容。
此端点支持以下自定义媒体类型。有关更多信息，请参阅 "媒体类型”。
application/vnd.github.raw+json: 返回文件和符号链接的原始文件内容。application/vnd.github.html+json: 返回以 HTML 格式的文件内容。使用 GitHub 的开源 Markup 库 将标记语言渲染为 HTML。application/vnd.github.object+json: 无论内容类型如何，都以一致的对象格式返回内容。例如，目录的响应将不是对象数组，而是一个包含entries属性的对象，该属性包含对象数组。
如果内容是目录，则响应将是一个对象数组，每个目录项对应一个对象。列出目录内容时，子模块的“类型”指定为“文件”。从逻辑上讲，该值应该为“子模块”。这种行为存在 为了向后兼容的目的。在 API 的下一个主要版本中，类型将返回为“子模块”。
如果内容是符号链接，并且符号链接的目标是存储库中的普通文件，则 API 将响应文件的原始内容。否则，API 将响应一个描述符号链接本身的对象。
如果内容是子模块，则 submodule_git_url 字段标识子模块存储库的位置，sha 标识子模块存储库中的特定提交。Git 在克隆子模块存储库时使用给定的 URL，并在该特定提交处检出子模块。如果子模块存储库未托管在 github.com 上，则 Git URL（git_url 和 _links["git"]）和 github.com URL（html_url 和 _links["html"]）将具有空值。
注意:
- 要递归地获取存储库的内容，您可以 递归地获取树。
- 此 API 对目录中的文件数量上限为 1,000 个。如果您需要检索更多文件，请使用 Git 树 API。
- 下载 URL 会过期，并且仅供一次性使用。为了确保下载 URL 不过期，请使用内容 API 获取每个下载的最新下载 URL。
- 如果请求的文件大小为
- 1 MB 或更小：此端点的所有功能都受支持。
- 介于 1-100 MB 之间：仅支持
raw或object自定义媒体类型。两者都将正常工作，除了使用object媒体类型时，content字段将为空字符串，encoding字段将为"none"。要获取这些较大的文件的内容，请使用raw媒体类型。 - 大于 100 MB：此端点不受支持。
用于“获取仓库内容”的细粒度访问令牌
此端点与以下细粒度令牌类型一起使用
细粒度令牌必须具有以下权限集
- “内容”仓库权限（读取）
如果仅请求公共资源，则可以在没有身份验证或上述权限的情况下使用此端点。
“获取仓库内容”的参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需仓库的帐户所有者。名称不区分大小写。 |
repo string 必需仓库的名称，不包括 |
path string 必需路径参数 |
| 名称、类型、描述 |
|---|
ref string 提交/分支/标签的名称。默认：仓库的默认分支。 |
“获取仓库内容”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
302 | 已找到 |
304 | 未修改 |
403 | 禁止 |
404 | 资源未找到 |
“获取仓库内容”的代码示例
请求示例
get/repos/{owner}/{repo}/contents/{path}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/contents/PATH如果内容是文件，则返回响应
状态：200{ "type": "file", "encoding": "base64", "size": 5362, "name": "README.md", "path": "README.md", "content": "IyBZb2dhIEJvmsgaW4gcHJvZ3Jlc3MhIEZlZWwgdAoKOndhcm5pbmc6IFdvc\\nZnJlZSBmUgdG8gY0byBjaGVjayBvdXQgdGhlIGFwcCwgYnV0IGJlIHN1c29t\\nZSBiYWNrIG9uY2UgaXQgaXMgY29tcGxldGUuCgpAIHdlYiBhcHAgdGhhdCBs\\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" } }创建或更新文件内容
在仓库中创建一个新文件或替换现有文件。
注意：如果您并行使用此端点和“删除文件”端点，并发请求将发生冲突，您将收到错误。您必须依次使用这些端点。
OAuth 应用程序令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点。为了修改 .github/workflows 目录中的文件，还需要 workflow 范围。
用于“创建或更新文件内容”的细粒度访问令牌
此端点与以下细粒度令牌类型一起使用
细粒度令牌必须具有以下权限集
- “内容”仓库权限（写入）
“创建或更新文件内容”参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需仓库的帐户所有者。名称不区分大小写。 |
repo string 必需仓库的名称，不包括 |
path string 必需路径参数 |
| 名称、类型、描述 | ||||
|---|---|---|---|---|
message 字符串 必需提交消息。 | ||||
content 字符串 必需新文件内容，使用 Base64 编码。 | ||||
sha 字符串 **如果您正在更新文件，则为必需项。** 要替换的文件的 Blob SHA。 | ||||
branch 字符串 分支名称。默认值：存储库的默认分支。 | ||||
committer 对象 提交文件的人员。默认值：经过身份验证的用户。 | ||||
|
| 名称、类型、描述 |
|---|
name 字符串 必需提交的作者或提交者的姓名。如果您省略 |
email 字符串 必需提交的作者或提交者的电子邮件。如果您省略 |
date 字符串 |
author 对象 文件的作者。默认值：committer 或如果您省略 committer 则为经过身份验证的用户。
| 名称、类型、描述 |
|---|
name 字符串 必需提交的作者或提交者的姓名。如果您省略 |
email 字符串 必需提交的作者或提交者的电子邮件。如果您省略 |
date 字符串 |
“创建或更新文件内容”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
201 | 已创建 |
404 | 资源未找到 |
409 | 冲突 |
422 | 验证失败，或端点已被垃圾邮件。 |
“创建或更新文件内容”的代码示例
请求示例
put/repos/{owner}/{repo}/contents/{path}
curl -L \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/contents/PATH \ -d '{"message":"my commit message","committer":{"name":"Monalisa Octocat","email":"[email protected]"},"content":"bXkgbmV3IGZpbGUgY29udGVudHM="}'响应
状态: 201{ "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", "node_id": "MDY6Q29tbWl0NzYzODQxN2RiNmQ1OWYzYzQzMWQzZTFmMjYxY2M2MzcxNTU2ODRjZA==", "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": "Monalisa Octocat", "email": "[email protected]" }, "committer": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "[email protected]" }, "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 } } }删除文件
删除仓库中的文件。
您可以提供额外的 committer 参数，它是一个包含提交者信息的 对象。或者，您可以提供一个 author 参数，它是一个包含作者信息的 对象。
author 部分是可选的，如果省略，则使用 committer 信息填充。如果省略 committer 信息，则使用经过身份验证的用户的 信息。
无论您选择使用 author 还是 committer，您都必须提供 name 和 email 的值。否则，您将收到 422 状态码。
注意：如果您并行使用此端点和 "创建或更新文件内容" 端点，并发请求将发生冲突，您将收到错误。您必须改为串行使用这些端点。
用于“删除文件”的细粒度访问令牌
此端点与以下细粒度令牌类型一起使用
细粒度令牌必须具有以下权限集
- “内容”仓库权限（写入）
“删除文件”的参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需仓库的帐户所有者。名称不区分大小写。 |
repo string 必需仓库的名称，不包括 |
path string 必需路径参数 |
| 名称、类型、描述 | |||
|---|---|---|---|
message 字符串 必需提交消息。 | |||
sha string 必需要删除的文件的 Blob SHA。 | |||
branch 字符串 分支名称。默认值：存储库的默认分支 | |||
committer 对象 包含提交者信息的 object。 | |||
|
| 名称、类型、描述 |
|---|
name string 提交作者（或提交者）的姓名 |
email string 提交作者（或提交者）的电子邮件 |
author 对象 包含作者信息的 object。
| 名称、类型、描述 |
|---|
name string 提交作者（或提交者）的姓名 |
email string 提交作者（或提交者）的电子邮件 |
“删除文件”的 HTTP 响应状态码
| 状态代码 | 描述 |
|---|---|
200 | OK |
404 | 资源未找到 |
409 | 冲突 |
422 | 验证失败，或端点已被垃圾邮件。 |
503 | 服务不可用 |
“删除文件”的代码示例
请求示例
delete/repos/{owner}/{repo}/contents/{path}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/contents/PATH \ -d '{"message":"my commit message","committer":{"name":"Monalisa Octocat","email":"[email protected]"},"sha":"329688480d39049927147c162b9d2deaf885005f"}'响应
状态：200{ "content": null, "commit": { "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", "node_id": "MDY6Q29tbWl0NzYzODQxN2RiNmQ1OWYzYzQzMWQzZTFmMjYxY2M2MzcxNTU2ODRjZA==", "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": "Monalisa Octocat", "email": "[email protected]" }, "committer": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "[email protected]" }, "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 } } }获取存储库自述文件
获取存储库的首选自述文件。
此端点支持以下自定义媒体类型。有关更多信息，请参阅 "媒体类型”。
application/vnd.github.raw+json：返回原始文件内容。如果您未指定媒体类型，则为默认值。application/vnd.github.html+json：以 HTML 格式返回自述文件。使用 GitHub 的开源 Markup 库 将标记语言渲染为 HTML。
获取仓库自述文件参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需仓库的帐户所有者。名称不区分大小写。 |
repo string 必需仓库的名称，不包括 |
| 名称、类型、描述 |
|---|
ref string 提交/分支/标签的名称。默认：仓库的默认分支。 |
获取仓库自述文件的 HTTP 响应状态码
| 状态代码 | 描述 |
|---|---|
200 | OK |
404 | 资源未找到 |
422 | 验证失败，或端点已被垃圾邮件。 |
获取仓库自述文件的代码示例
请求示例
get/repos/{owner}/{repo}/readme
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/readme响应
状态：200{ "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" } }获取仓库目录的自述文件
从仓库目录获取自述文件。
此端点支持以下自定义媒体类型。有关更多信息，请参阅 "媒体类型”。
application/vnd.github.raw+json：返回原始文件内容。如果您未指定媒体类型，则为默认值。application/vnd.github.html+json：以 HTML 格式返回自述文件。使用 GitHub 的开源 Markup 库 将标记语言渲染为 HTML。
获取仓库目录的自述文件参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需仓库的帐户所有者。名称不区分大小写。 |
repo string 必需仓库的名称，不包括 |
dir string 必填查找自述文件的备用路径 |
| 名称、类型、描述 |
|---|
ref string 提交/分支/标签的名称。默认：仓库的默认分支。 |
获取仓库目录的自述文件的 HTTP 响应状态码
| 状态代码 | 描述 |
|---|---|
200 | OK |
404 | 资源未找到 |
422 | 验证失败，或端点已被垃圾邮件。 |
获取仓库目录的自述文件的代码示例
请求示例
get/repos/{owner}/{repo}/readme/{dir}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/readme/DIR响应
状态：200{ "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" } }下载仓库归档文件 (tar)
获取下载仓库 tar 归档文件的重定向 URL。如果您省略 :ref，将使用仓库的默认分支（通常为 main）。请确保您的 HTTP 框架配置为遵循重定向，否则您需要使用 Location 标头发出第二个 GET 请求。注意：对于私有仓库，这些链接是临时的，在五分钟后过期。
下载仓库归档文件 (tar) 的细粒度访问令牌
此端点与以下细粒度令牌类型一起使用
细粒度令牌必须具有以下权限集
- “内容”仓库权限（读取）
如果仅请求公共资源，则可以在没有身份验证或上述权限的情况下使用此端点。
下载仓库归档文件 (tar) 参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需仓库的帐户所有者。名称不区分大小写。 |
repo string 必需仓库的名称，不包括 |
ref string 必填 |
下载仓库归档文件 (tar) 的 HTTP 响应状态码
| 状态代码 | 描述 |
|---|---|
302 | 已找到 |
下载仓库归档文件 (tar) 的代码示例
请求示例
get/repos/{owner}/{repo}/tarball/{ref}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/tarball/REF响应
状态：302下载仓库存档（zip）
获取下载仓库 zip 存档的重定向 URL。如果您省略 `:ref`，将使用仓库的默认分支（通常为 `main`）。请确保您的 HTTP 框架已配置为遵循重定向，否则您需要使用 `Location` 标头发出第二个 `GET` 请求。
注意：对于私有仓库，这些链接是临时的，将在五分钟后过期。如果仓库为空，您在遵循重定向时将收到 404 错误。
用于“下载仓库存档（zip）”的细粒度访问令牌
此端点与以下细粒度令牌类型一起使用
细粒度令牌必须具有以下权限集
- “内容”仓库权限（读取）
如果仅请求公共资源，则可以在没有身份验证或上述权限的情况下使用此端点。
用于“下载仓库存档（zip）”的参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需仓库的帐户所有者。名称不区分大小写。 |
repo string 必需仓库的名称，不包括 |
ref string 必填 |
用于“下载仓库存档（zip）”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
302 | 已找到 |
用于“下载仓库存档（zip）”的代码示例
请求示例
get/repos/{owner}/{repo}/zipball/{ref}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/zipball/REF响应
状态：302