# Create a reference

From **GitHub v3 REST API**.

`POST /repos/{owner}/{repo}/git/refs`

Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.

## Parameters

### `owner`

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

### `repo`

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

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{
  "ref": "refs/heads/featureA",
  "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd"
}
```

```json
{"properties":{"key":{"example":"\"refs/heads/newbranch\"","type":"string"},"ref":{"description":"The name of the fully qualified reference (ie: `refs/heads/master`). If it doesn't start with 'refs' and have at least two slashes, it will be rejected.","type":"string"},"sha":{"description":"The SHA1 value for this reference.","type":"string"}},"required":["ref","sha"],"type":"object"}
```

## Responses

### `201`

Response

#### Headers

##### `Location`

- Type: `string`

- Example: `https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA`

### `application/json`

- Type: `object`

Git references within a repository

```json
{
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "object": {
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "type": "commit",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  },
  "ref": "refs/heads/featureA",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA"
}
```

```json
{"description":"Git references within a repository","properties":{"node_id":{"type":"string"},"object":{"properties":{"sha":{"description":"SHA for the reference","example":"7638417db6d59f3c431d3e1f261cc637155684cd","maxLength":40,"minLength":40,"type":"string"},"type":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["type","sha","url"],"type":"object"},"ref":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["ref","node_id","url","object"],"title":"Git Reference","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 POST \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/refs \
  --header 'content-type: application/json' \
  --data '{
  "ref": "refs/heads/featureA",
  "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd"
}'
```