Contenidos del repositorio

La API de REST permite crear, modificar y eliminar contenido codificado en Base64 en un repositorio.

Acerca del contenido del repositorio

Para solicitar el formato sin procesar y interpretado en HTML (cuando sea posible), utiliza los tipos de medios personalizados para el contenido de un repositorio.

Tipos de medios personalizados para el contenido de un repositorio

Los archivos Léame, los archivos y los vínculos simbólicos admiten los siguientes tipos de medios personalizados:

application/vnd.github.raw
application/vnd.github.html

Use el tipo de medios .raw para recuperar el contenido del archivo.

Para archivos de marcado como Markdown o AsciiDoc, puede recuperar el código HTML representado si usa el tipo de medios .html. Los lenguajes de marcado se representan en HTML mediante nuestra biblioteca de marcado de código abierto.

Todos los objetos admiten el siguiente tipo de medio personalizado:

application/vnd.github.object

Use el parámetro de tipo de medios object para recuperar el contenido en un formato de objeto consistente con independencia del tipo de contenido. Por ejemplo, en vez de una matriz de objetos para un directorio, la respuesta será un objeto con un atributo entries que contenga la matriz de objetos.

Aquí puede obtener más información sobre el uso de los tipos de medios en la API.

Get repository content

Funciona con GitHub Apps

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.

Size limits

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.

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.

Parámetros para "Get repository content"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.
Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository. The name is not case sensitive.
`path` string Requerido path parameter
Parámetros de consulta
Nombre, Tipo, Descripción
`ref` string The name of the commit/branch/tag. Default: the repository’s default branch (usually `master`)

Códigos de estado de respuesta HTTP para "Get repository content"

status code	Descripción
`200`	OK
`302`	Found
`403`	Forbidden
`404`	Resource not found

Ejemplos de código para "Get repository content"

get/repos/{owner}/{repo}/contents/{path}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://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://HOSTNAME/repos/octokit/octokit.rb/contents/README.md",
  "git_url": "https://HOSTNAME/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://HOSTNAME/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://HOSTNAME/repos/octokit/octokit.rb/contents/README.md",
    "html": "https://github.com/octokit/octokit.rb/blob/master/README.md"
  }
}

Create or update file contents

Funciona con GitHub Apps

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.

Parámetros para "Create or update file contents"

Encabezados

Nombre, Tipo, Descripción

accept string

Setting to application/vnd.github+json is recommended.

Parámetros de la ruta de acceso

Nombre, Tipo, Descripción

owner string Requerido

The account owner of the repository. The name is not case sensitive.

repo string Requerido

The name of the repository. The name is not case sensitive.

path string Requerido

path parameter

Parámetros del cuerpo

Nombre, Tipo, Descripción

message string Requerido

The commit message.

content string Requerido

The new file content, using Base64 encoding.

sha string

Required if you are updating a file. The blob SHA of the file being replaced.

branch string

The branch name. Default: the repository’s default branch (usually master)

committer object

The person that committed the file. Default: the authenticated user.

Properties of committer

Nombre, Tipo, Descripción
`name` string Requerido The name of the author or committer of the commit. You'll receive a `422` status code if `name` is omitted.
`email` string Requerido The email of the author or committer of the commit. You'll receive a `422` status code if `email` is omitted.
`date` string

author object

The author of the file. Default: The committer or the authenticated user if you omit committer.

Properties of author

Nombre, Tipo, Descripción
`name` string Requerido The name of the author or committer of the commit. You'll receive a `422` status code if `name` is omitted.
`email` string Requerido The email of the author or committer of the commit. You'll receive a `422` status code if `email` is omitted.
`date` string

Códigos de estado de respuesta HTTP para "Create or update file contents"

status code	Descripción
`200`	OK
`201`	Created
`404`	Resource not found
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

Ejemplos de código para "Create or update file contents"

put/repos/{owner}/{repo}/contents/{path}

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://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://HOSTNAME/repos/octocat/Hello-World/contents/notes/hello.txt",
    "html_url": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt",
    "git_url": "https://HOSTNAME/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "download_url": "https://raw.githubusercontent.com/octocat/HelloWorld/master/notes/hello.txt",
    "type": "file",
    "_links": {
      "self": "https://HOSTNAME/repos/octocat/Hello-World/contents/notes/hello.txt",
      "git": "https://HOSTNAME/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://HOSTNAME/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://HOSTNAME/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
      "sha": "691272480426f78a0138979dd3ce63b77f706feb"
    },
    "parents": [
      {
        "url": "https://HOSTNAME/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

Funciona con GitHub Apps

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.

Parámetros para "Delete a file"

Encabezados

Nombre, Tipo, Descripción

accept string

Setting to application/vnd.github+json is recommended.

Parámetros de la ruta de acceso

Nombre, Tipo, Descripción

owner string Requerido

The account owner of the repository. The name is not case sensitive.

repo string Requerido

The name of the repository. The name is not case sensitive.

path string Requerido

path parameter

Parámetros del cuerpo

Nombre, Tipo, Descripción

message string Requerido

The commit message.

sha string Requerido

The blob SHA of the file being deleted.

branch string

The branch name. Default: the repository’s default branch (usually master)

committer object

object containing information about the committer.

Properties of committer

Nombre, Tipo, Descripción
`name` string The name of the author (or committer) of the commit
`email` string The email of the author (or committer) of the commit

author object

object containing information about the author.

Properties of author

Nombre, Tipo, Descripción
`name` string The name of the author (or committer) of the commit
`email` string The email of the author (or committer) of the commit

Códigos de estado de respuesta HTTP para "Delete a file"

status code	Descripción
`200`	OK
`404`	Resource not found
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.
`503`	Service unavailable

Ejemplos de código para "Delete a file"

delete/repos/{owner}/{repo}/contents/{path}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://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://HOSTNAME/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://HOSTNAME/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
      "sha": "691272480426f78a0138979dd3ce63b77f706feb"
    },
    "parents": [
      {
        "url": "https://HOSTNAME/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

Funciona con GitHub Apps

Gets the preferred README for a repository.

READMEs support custom media types for retrieving the raw content or rendered HTML.

Parámetros para "Get a repository README"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.
Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository. The name is not case sensitive.
Parámetros de consulta
Nombre, Tipo, Descripción
`ref` string The name of the commit/branch/tag. Default: the repository’s default branch (usually `master`)

Códigos de estado de respuesta HTTP para "Get a repository README"

status code	Descripción
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Ejemplos de código para "Get a repository README"

get/repos/{owner}/{repo}/readme

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://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://HOSTNAME/repos/octokit/octokit.rb/contents/README.md",
  "git_url": "https://HOSTNAME/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://HOSTNAME/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://HOSTNAME/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

Funciona con GitHub Apps

Gets the README from a repository directory.

READMEs support custom media types for retrieving the raw content or rendered HTML.

Parámetros para "Get a repository README for a directory"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.
Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository. The name is not case sensitive.
`dir` string Requerido The alternate path to look for a README file
Parámetros de consulta
Nombre, Tipo, Descripción
`ref` string The name of the commit/branch/tag. Default: the repository’s default branch (usually `master`)

Códigos de estado de respuesta HTTP para "Get a repository README for a directory"

status code	Descripción
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Ejemplos de código para "Get a repository README for a directory"

get/repos/{owner}/{repo}/readme/{dir}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://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://HOSTNAME/repos/octokit/octokit.rb/contents/README.md",
  "git_url": "https://HOSTNAME/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://HOSTNAME/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://HOSTNAME/repos/octokit/octokit.rb/contents/README.md",
    "html": "https://github.com/octokit/octokit.rb/blob/master/README.md"
  }
}

Download a repository archive (tar)

Funciona con GitHub Apps

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.

Parámetros para "Download a repository archive (tar)"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.
Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository. The name is not case sensitive.
`ref` string Requerido

Códigos de estado de respuesta HTTP para "Download a repository archive (tar)"

status code	Descripción
`302`	Found

Ejemplos de código para "Download a repository archive (tar)"

get/repos/{owner}/{repo}/tarball/{ref}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/tarball/REF

Response

Status: 302

Download a repository archive (zip)

Funciona con GitHub Apps

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.

Parámetros para "Download a repository archive (zip)"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.
Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository. The name is not case sensitive.
`ref` string Requerido

Códigos de estado de respuesta HTTP para "Download a repository archive (zip)"

status code	Descripción
`302`	Found

Ejemplos de código para "Download a repository archive (zip)"

get/repos/{owner}/{repo}/zipball/{ref}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/zipball/REF

Response

Status: 302