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 对目录的文件数有 1000 个的上限。如果需要检索更多文件，请使用Git 树 API。
- 下载 URL 会过期，并且仅供一次性使用。要确保下载 URL 不会过期，请使用内容 API 获取每次下载的最新下载 URL。
- 如果请求的文件大小为
- 1 MB 或更小：支持此端点的所有功能。
- 1-100 MB 之间：仅支持
raw或object自定义媒体类型。两者都将正常工作，但当使用object媒体类型时，content字段将为空字符串，而encoding字段将为"none"。要获取这些较大的文件的内容，请使用raw媒体类型。 - 大于 100 MB：不支持此端点。
“获取代码库内容”的细粒度访问令牌
此端点适用于以下细粒度令牌类型:
细粒度令牌必须具有以下权限集
- “内容”代码库权限（读取）
如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。
“获取代码库内容”的参数
| 名称、类型、描述 |
|---|
accept 字符串建议设置为 |
| 名称、类型、描述 |
|---|
owner 字符串 必填代码库的帐户所有者。名称不区分大小写。 |
repo 字符串 必填代码库的名称，不带 |
path 字符串 必填path 参数 |
| 名称、类型、描述 |
|---|
ref 字符串提交/分支/标签的名称。默认值：代码库的默认分支。 |
“获取代码库内容”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | 确定 |
302 | 已找到 |
304 | 未修改 |
403 | 禁止 |
404 | 资源未找到 |
“获取代码库内容”的代码示例
请求示例
获取/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\\nZSBiYWNrIG9uY2UgaXQgaXMgY29tcGxldGUuCgpBIHdlYiBhcHAgdGhhdCBs\\nZWFkcyB5b3UgdGhyb3VnaCBhIHlvZ2Egc2Vzc2lvbi4KCltXb3Jrb3V0IG5v\\ndyFdKGh0dHBzOi8vc2tlZHdhcmRzODguZ2l0aHViLmlvL3lvZ2EvKQoKPGlt\\nZyBzcmM9InNyYy9pbWFnZXMvbWFza2FibGVfaWNvbl81MTIucG5nIiBhbHQ9\\nImJvdCBsaWZ0aW5nIHdlaWdodHMiIHdpZHRoPSIxMDAiLz4KCkRvIHlvdSBo\\nYXZlIGZlZWRiYWNrIG9yIGlkZWFzIGZvciBpbXByb3ZlbWVudD8gW09wZW4g\\nYW4gaXNzdWVdKGh0dHBzOi8vZ2l0aHViLmNvbS9za2Vkd2FyZHM4OC95b2dh\\nL2lzc3Vlcy9uZXcpLgoKV2FudCBtb3JlIGdhbWVzPyBWaXNpdCBbQ25TIEdh\\nbWVzXShodHRwczovL3NrZWR3YXJkczg4LmdpdGh1Yi5pby9wb3J0Zm9saW8v\\nKS4KCiMjIERldmVsb3BtZW50CgpUbyBhZGQgYSBuZXcgcG9zZSwgYWRkIGFu\\nIGVudHJ5IHRvIHRoZSByZWxldmFudCBmaWxlIGluIGBzcmMvYXNhbmFzYC4K\\nClRvIGJ1aWxkLCBydW4gYG5wbSBydW4gYnVpbGRgLgoKVG8gcnVuIGxvY2Fs\\nbHkgd2l0aCBsaXZlIHJlbG9hZGluZyBhbmQgbm8gc2VydmljZSB3b3JrZXIs\\nIHJ1biBgbnBtIHJ1biBkZXZ2LiAoSWYgYSBzZXJ2aWNlIHdvcmtlciB3YXMg\\ncHJldmlvdXNseSByZWdpc3RlcmVkLCB5b3UgY2FuIHVucmVnaXN0ZXIgaXQg\\naW4gY2hyb21lIGRldmVsb3BlciB0b29sczogYEFwcGxpY2F0aW9uYCA+IGBT\\nZXJ2aWNlIHdvcmtlcnMgID4gYFVucmVnaXN0ZXJgLikKClRvIHJ1biBsb2Nh\\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 字符串建议设置为 |
| 名称、类型、描述 |
|---|
owner 字符串 必填代码库的帐户所有者。名称不区分大小写。 |
repo 字符串 必填代码库的名称，不带 |
path 字符串 必填path 参数 |
| 名称、类型、描述 | ||||
|---|---|---|---|---|
message 字符串 必需提交消息。 | ||||
content 字符串 必需使用 Base64 编码的新文件内容。 | ||||
sha 字符串如果您正在更新文件，则为必需。要替换的文件的 Blob SHA。 | ||||
branch 字符串分支名称。默认值：仓库的默认分支。 | ||||
committer 对象提交文件的人员。默认值：已认证的用户。 | ||||
|
| 名称、类型、描述 |
|---|
name 字符串 必需提交的作者或提交者的姓名。如果省略了 |
email 字符串 必需提交的作者或提交者的电子邮件。如果省略了 |
date 字符串 |
author 对象文件的作者。默认值：如果您省略了committer，则为committer或已认证的用户。
| 名称、类型、描述 |
|---|
name 字符串 必需提交的作者或提交者的姓名。如果省略了 |
email 字符串 必需提交的作者或提交者的电子邮件。如果省略了 |
date 字符串 |
“创建或更新文件内容”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | 确定 |
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 字符串建议设置为 |
| 名称、类型、描述 |
|---|
owner 字符串 必填代码库的帐户所有者。名称不区分大小写。 |
repo 字符串 必填代码库的名称，不带 |
path 字符串 必填path 参数 |
| 名称、类型、描述 | |||
|---|---|---|---|
message 字符串 必需提交消息。 | |||
sha 字符串 必需要删除的文件的 Blob SHA。 | |||
branch 字符串分支名称。默认值：仓库的默认分支 | |||
committer 对象包含有关提交者信息的 object。 | |||
|
| 名称、类型、描述 |
|---|
name 字符串提交的作者（或提交者）的姓名 |
email 字符串提交的作者（或提交者）的电子邮件 |
author 对象包含有关作者信息的 object。
| 名称、类型、描述 |
|---|
name 字符串提交的作者（或提交者）的姓名 |
email 字符串提交的作者（或提交者）的电子邮件 |
“删除文件”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | 确定 |
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 的开源 标记库 将标记语言呈现为 HTML。
“获取仓库自述文件”的参数
| 名称、类型、描述 |
|---|
accept 字符串建议设置为 |
| 名称、类型、描述 |
|---|
owner 字符串 必填代码库的帐户所有者。名称不区分大小写。 |
repo 字符串 必填代码库的名称，不带 |
| 名称、类型、描述 |
|---|
ref 字符串提交/分支/标签的名称。默认值：代码库的默认分支。 |
“获取仓库自述文件”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | 确定 |
304 | 未修改 |
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": "编码内容 ...", "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 的开源 标记库 将标记语言呈现为 HTML。
“获取目录的仓库自述文件”的参数
| 名称、类型、描述 |
|---|
accept 字符串建议设置为 |
| 名称、类型、描述 |
|---|
owner 字符串 必填代码库的帐户所有者。名称不区分大小写。 |
repo 字符串 必填代码库的名称，不带 |
dir 字符串 必需查找自述文件的备用路径 |
| 名称、类型、描述 |
|---|
ref 字符串提交/分支/标签的名称。默认值：代码库的默认分支。 |
“获取目录的仓库自述文件”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | 确定 |
404 | 资源未找到 |
422 | 验证失败或端点已被滥用。 |
“获取目录的仓库自述文件”的代码示例
请求示例
获取/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": "编码内容 ...", "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 字符串建议设置为 |
| 名称、类型、描述 |
|---|
owner 字符串 必填代码库的帐户所有者。名称不区分大小写。 |
repo 字符串 必填代码库的名称，不带 |
ref 字符串 必填 |
“下载仓库归档文件 (tar)” 的 HTTP 响应状态码
| 状态代码 | 描述 |
|---|---|
302 | 已找到 |
“下载仓库归档文件 (tar)” 的代码示例
请求示例
获取/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 字符串建议设置为 |
| 名称、类型、描述 |
|---|
owner 字符串 必填代码库的帐户所有者。名称不区分大小写。 |
repo 字符串 必填代码库的名称，不带 |
ref 字符串 必填 |
“下载仓库归档文件 (zip)” 的 HTTP 响应状态码
| 状态代码 | 描述 |
|---|---|
302 | 已找到 |
“下载仓库归档文件 (zip)” 的代码示例
请求示例
获取/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