# Get repository content

From **GitHub v3 REST API**.

`GET /repos/{owner}/{repo}/contents/{path}`

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](https://docs.github.com/enterprise-server@3.0/rest/reference/repos#custom-media-types) for
retrieving the raw content or rendered HTML (when supported). All content types support [a custom media
type](https://docs.github.com/enterprise-server@3.0/rest/reference/repos#custom-media-types) to ensure the content is returned in a consistent
object format.

**Note**:
*   To get a repository's contents recursively, you can [recursively get the tree](https://docs.github.com/enterprise-server@3.0/rest/reference/git#trees).
*   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](https://docs.github.com/enterprise-server@3.0/rest/reference/git#get-a-tree).
*   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](https://git.io/v1YCW).
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.

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

### `path`

- Location: path
- Required: true
- Type: `string`

path parameter

### `ref`

- Location: query
- Required: false
- Type: `string`

The name of the commit/branch/tag. Default: the repository’s default branch (usually `master`)

## Responses

### `200`

Response

### `application/json`

```json
[
  {
    "_links": {
      "git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
      "html": "https://github.com/octokit/octokit.rb/blob/master/lib/octokit.rb",
      "self": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit.rb"
    },
    "download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/lib/octokit.rb",
    "git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
    "html_url": "https://github.com/octokit/octokit.rb/blob/master/lib/octokit.rb",
    "name": "octokit.rb",
    "path": "lib/octokit.rb",
    "sha": "fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
    "size": 625,
    "type": "file",
    "url": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit.rb"
  },
  {
    "_links": {
      "git": "https://api.github.com/repos/octokit/octokit.rb/git/trees/a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
      "html": "https://github.com/octokit/octokit.rb/tree/master/lib/octokit",
      "self": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit"
    },
    "download_url": null,
    "git_url": "https://api.github.com/repos/octokit/octokit.rb/git/trees/a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
    "html_url": "https://github.com/octokit/octokit.rb/tree/master/lib/octokit",
    "name": "octokit",
    "path": "lib/octokit",
    "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
    "size": 0,
    "type": "dir",
    "url": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit"
  }
]
```

```json
{"oneOf":[{"$ref":"#/components/schemas/content-directory"},{"$ref":"#/components/schemas/content-file"},{"$ref":"#/components/schemas/content-symlink"},{"$ref":"#/components/schemas/content-submodule"}]}
```

### `application/vnd.github.v3.object`

- Type: `object`

Content Tree

```json
{"description":"Content Tree","properties":{"_links":{"properties":{"git":{"format":"uri","nullable":true,"type":"string"},"html":{"format":"uri","nullable":true,"type":"string"},"self":{"format":"uri","type":"string"}},"required":["git","html","self"],"type":"object"},"download_url":{"format":"uri","nullable":true,"type":"string"},"entries":{"items":{"properties":{"_links":{"properties":{"git":{"format":"uri","nullable":true,"type":"string"},"html":{"format":"uri","nullable":true,"type":"string"},"self":{"format":"uri","type":"string"}},"required":["git","html","self"],"type":"object"},"content":{"type":"string"},"download_url":{"format":"uri","nullable":true,"type":"string"},"git_url":{"format":"uri","nullable":true,"type":"string"},"html_url":{"format":"uri","nullable":true,"type":"string"},"name":{"type":"string"},"path":{"type":"string"},"sha":{"type":"string"},"size":{"type":"integer"},"type":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["_links","git_url","html_url","download_url","name","path","sha","size","type","url"],"type":"object"},"type":"array"},"git_url":{"format":"uri","nullable":true,"type":"string"},"html_url":{"format":"uri","nullable":true,"type":"string"},"name":{"type":"string"},"path":{"type":"string"},"sha":{"type":"string"},"size":{"type":"integer"},"type":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["_links","git_url","html_url","download_url","name","path","sha","size","type","url","content","encoding"],"title":"Content Tree","type":"object"}
```

### `302`

Found

### `403`

Forbidden

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `404`

Resource not found

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

## Request examples

### cURL

```shell
curl --request GET \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/contents/{path}
```