We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the new Branches, Collaborators, Commits, Deploy Keys, Deployments, GitHub Pages, Releases, Metrics, Webhooks REST API pages.
Contenu d’un dépôt
Utilisez l’API REST pour créer, modifier et supprimer du contenu codé en Base64 dans un dépôt.
À propos du contenu des dépôts
Pour demander le format brut ou le rendu HTML (lorsqu’il est pris en charge), utilisez des types multimédias personnalisés pour le contenu du référentiel.
Types de média personnalisés pour le contenu du référentiel
README, fichiers et symlinks prennent en charge les types de médias personnalisés suivants :
application/vnd.github.raw
application/vnd.github.html
Utilisez le type de média .raw
pour récupérer le contenu du fichier.
Pour les fichiers de balisage, comme Markdown ou AsciiDoc, vous pouvez récupérer le code HTML rendu à l’aide du type de média .html
. Les langages de balisage sont rendus au format HTML à l’aide de notre bibliothèque de balisage open source.
Tous les objets prennent en charge le type de média personnalisé suivant :
application/vnd.github.object
Utilisez le paramètre de type de média object
pour récupérer le contenu dans un format d’objet cohérent, quel que soit le type de contenu. Par exemple, au lieu d’un tableau d’objets pour un répertoire, la réponse est un objet avec un attribut entries
contenant le tableau d’objets.
Vous pouvez en apprendre davantage sur l’utilisation de types de médias dans l’API ici.
Get repository content
Gets 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.
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.
- 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.
Paramètres
En-têtes |
---|
Nom, Type, Description |
accept stringSetting to |
Paramètres de chemin d’accès |
Nom, Type, Description |
owner stringObligatoireThe account owner of the repository. The name is not case sensitive. |
repo stringObligatoireThe name of the repository. The name is not case sensitive. |
path stringObligatoirepath parameter |
Paramètres de requête |
Nom, Type, Description |
ref stringThe name of the commit/branch/tag. Default: the repository’s default branch (usually |
Codes de statut de réponse HTTP
Code d’état | Description |
---|---|
200 | OK |
302 | Found |
403 | Forbidden |
404 | Resource not found |
Exemples de code
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/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. You must authenticate using an access token with the workflow
scope to use this endpoint.
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.
Paramètres
En-têtes | |||||||
---|---|---|---|---|---|---|---|
Nom, Type, Description | |||||||
accept stringSetting to | |||||||
Paramètres de chemin d’accès | |||||||
Nom, Type, Description | |||||||
owner stringObligatoireThe account owner of the repository. The name is not case sensitive. | |||||||
repo stringObligatoireThe name of the repository. The name is not case sensitive. | |||||||
path stringObligatoirepath parameter | |||||||
Paramètres du corps | |||||||
Nom, Type, Description | |||||||
message stringObligatoireThe commit message. | |||||||
content stringObligatoireThe new file content, using Base64 encoding. | |||||||
sha stringRequired if you are updating a file. The blob SHA of the file being replaced. | |||||||
branch stringThe branch name. Default: the repository’s default branch (usually | |||||||
committer objectThe person that committed the file. Default: the authenticated user. | |||||||
Properties of |
Nom, Type, Description |
---|
name stringObligatoireThe name of the author or committer of the commit. You'll receive a |
email stringObligatoireThe email of the author or committer of the commit. You'll receive a |
date string |
author
objectThe author of the file. Default: The committer
or the authenticated user if you omit committer
.
Nom, Type, Description |
---|
name stringObligatoireThe name of the author or committer of the commit. You'll receive a |
email stringObligatoireThe email of the author or committer of the commit. You'll receive a |
date string |
Codes de statut de réponse HTTP
Code d’état | Description |
---|---|
200 | OK |
201 | Created |
404 | Resource not found |
409 | Conflict |
422 | Validation failed, or the endpoint has been spammed. |
Exemples de code
curl \
-X PUT \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/repos/OWNER/REPO/contents/PATH \
-d '{"message":"my commit message","committer":{"name":"Monalisa Octocat","email":"octocat@github.com"},"content":"bXkgbmV3IGZpbGUgY29udGVudHM="}'
Response
Status: 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": "octocat@github.com"
},
"committer": {
"date": "2014-11-07T22:01:45Z",
"name": "Monalisa Octocat",
"email": "octocat@github.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"
}
],
"verification": {
"verified": false,
"reason": "unsigned",
"signature": null,
"payload": null
}
}
}
Delete a file
Deletes 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.
Note: If you use this endpoint and the "Create or update file contents" endpoint in parallel, the concurrent requests will conflict and you will receive errors. You must use these endpoints serially instead.
Paramètres
En-têtes | ||||||
---|---|---|---|---|---|---|
Nom, Type, Description | ||||||
accept stringSetting to | ||||||
Paramètres de chemin d’accès | ||||||
Nom, Type, Description | ||||||
owner stringObligatoireThe account owner of the repository. The name is not case sensitive. | ||||||
repo stringObligatoireThe name of the repository. The name is not case sensitive. | ||||||
path stringObligatoirepath parameter | ||||||
Paramètres du corps | ||||||
Nom, Type, Description | ||||||
message stringObligatoireThe commit message. | ||||||
sha stringObligatoireThe blob SHA of the file being deleted. | ||||||
branch stringThe branch name. Default: the repository’s default branch (usually | ||||||
committer objectobject containing information about the committer. | ||||||
Properties of |
Nom, Type, Description |
---|
name stringThe name of the author (or committer) of the commit |
email stringThe email of the author (or committer) of the commit |
author
objectobject containing information about the author.
Nom, Type, Description |
---|
name stringThe name of the author (or committer) of the commit |
email stringThe email of the author (or committer) of the commit |
Codes de statut de réponse HTTP
Code d’état | Description |
---|---|
200 | OK |
404 | Resource not found |
409 | Conflict |
422 | Validation failed, or the endpoint has been spammed. |
503 | Service unavailable |
Exemples de code
curl \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/repos/OWNER/REPO/contents/PATH \
-d '{"message":"my commit message","committer":{"name":"Monalisa Octocat","email":"octocat@github.com"},"sha":"329688480d39049927147c162b9d2deaf885005f"}'
Response
Status: 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": "octocat@github.com"
},
"committer": {
"date": "2014-11-07T22:01:45Z",
"name": "Monalisa Octocat",
"email": "octocat@github.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"
}
],
"verification": {
"verified": false,
"reason": "unsigned",
"signature": null,
"payload": null
}
}
}
Get a repository README
Gets the preferred README for a repository.
READMEs support custom media types for retrieving the raw content or rendered HTML.
Paramètres
En-têtes |
---|
Nom, Type, Description |
accept stringSetting to |
Paramètres de chemin d’accès |
Nom, Type, Description |
owner stringObligatoireThe account owner of the repository. The name is not case sensitive. |
repo stringObligatoireThe name of the repository. The name is not case sensitive. |
Paramètres de requête |
Nom, Type, Description |
ref stringThe name of the commit/branch/tag. Default: the repository’s default branch (usually |
Codes de statut de réponse HTTP
Code d’état | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Exemples de code
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/repos/OWNER/REPO/readme
Response
Status: 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"
}
}
Get a repository README for a directory
Gets the README from a repository directory.
READMEs support custom media types for retrieving the raw content or rendered HTML.
Paramètres
En-têtes |
---|
Nom, Type, Description |
accept stringSetting to |
Paramètres de chemin d’accès |
Nom, Type, Description |
owner stringObligatoireThe account owner of the repository. The name is not case sensitive. |
repo stringObligatoireThe name of the repository. The name is not case sensitive. |
dir stringObligatoireThe alternate path to look for a README file |
Paramètres de requête |
Nom, Type, Description |
ref stringThe name of the commit/branch/tag. Default: the repository’s default branch (usually |
Codes de statut de réponse HTTP
Code d’état | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Exemples de code
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/repos/OWNER/REPO/readme/DIR
Response
Status: 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"
}
}
Download a repository archive (tar)
Gets a redirect URL to download a tar archive for a repository. If you omit :ref
, the repository’s default branch (usually
main
) 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.
Paramètres
En-têtes |
---|
Nom, Type, Description |
accept stringSetting to |
Paramètres de chemin d’accès |
Nom, Type, Description |
owner stringObligatoireThe account owner of the repository. The name is not case sensitive. |
repo stringObligatoireThe name of the repository. The name is not case sensitive. |
ref stringObligatoire |
Codes de statut de réponse HTTP
Code d’état | Description |
---|---|
302 | Found |
Exemples de code
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/repos/OWNER/REPO/tarball/REF
Response
Status: 302
Download a repository archive (zip)
Gets a redirect URL to download a zip archive for a repository. If you omit :ref
, the repository’s default branch (usually
main
) 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. If the repository is empty, you will receive a 404 when you follow the redirect.
Paramètres
En-têtes |
---|
Nom, Type, Description |
accept stringSetting to |
Paramètres de chemin d’accès |
Nom, Type, Description |
owner stringObligatoireThe account owner of the repository. The name is not case sensitive. |
repo stringObligatoireThe name of the repository. The name is not case sensitive. |
ref stringObligatoire |
Codes de statut de réponse HTTP
Code d’état | Description |
---|---|
302 | Found |
Exemples de code
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/repos/OWNER/REPO/zipball/REF
Response
Status: 302