# Get a repository README

From **GitHub v3 REST API**.

`GET /repos/{owner}/{repo}/readme`

Gets the preferred README for a repository.

READMEs support [custom media types](https://docs.github.com/enterprise-server@3.0/rest/reference/repos#custom-media-types) for retrieving the raw content or rendered HTML.

## Parameters

### `owner`

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

### `repo`

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

### `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`

- Type: `object`

Content File

```json
{
  "_links": {
    "git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "html": "https://github.com/octokit/octokit.rb/blob/master/README.md",
    "self": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md"
  },
  "content": "encoded content ...",
  "download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/README.md",
  "encoding": "base64",
  "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",
  "name": "README.md",
  "path": "README.md",
  "sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
  "size": 5362,
  "type": "file",
  "url": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md"
}
```

```json
{"description":"Content File","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"},"encoding":{"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"},"submodule_git_url":{"example":"\"git://example.com/defunkt/dotjs.git\"","type":"string"},"target":{"example":"\"actual/actual.md\"","type":"string"},"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 File","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"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

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