# List matching references

From **GitHub v3 REST API**.

`GET /repos/{owner}/{repo}/git/matching-refs/{ref}`

Returns an array of references from your Git database that match the supplied name. The `:ref` in the URL must be formatted as `heads/<branch name>` for branches and `tags/<tag name>` for tags. If the `:ref` doesn't exist in the repository, but existing refs start with `:ref`, they will be returned as an array.

When you use this endpoint without providing a `:ref`, it will return an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just `heads` and `tags`.

**Note:** You need to explicitly [request a pull request](https://docs.github.com/enterprise-server@3.0/rest/reference/pulls#get-a-pull-request) to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "[Checking mergeability of pull requests](https://docs.github.com/enterprise-server@3.0/rest/guides/getting-started-with-the-git-database-api#checking-mergeability-of-pull-requests)".

If you request matching references for a branch named `feature` but the branch `feature` doesn't exist, the response can still include other matching head refs that start with the word `feature`, such as `featureA` and `featureB`.

## Parameters

### `owner`

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

### `repo`

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

### `ref`

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

ref parameter

### `per_page`

- Location: query
- Required: false
- Type: `integer`
- Default: `30`

Results per page (max 100)

### `page`

- Location: query
- Required: false
- Type: `integer`
- Default: `1`

Page number of the results to fetch.

## Responses

### `200`

Response

#### Headers

##### `Link`

- Type: `string`

- Example: `<https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"`

### `application/json`

- Type: `array`

```json
[
  {
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWE=",
    "object": {
      "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
      "type": "commit",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
    },
    "ref": "refs/heads/feature-a",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-a"
  },
  {
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWI=",
    "object": {
      "sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac",
      "type": "commit",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac"
    },
    "ref": "refs/heads/feature-b",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-b"
  }
]
```

```json
{"items":{"$ref":"#/components/schemas/git-ref"},"type":"array"}
```

## Request examples

### cURL

```shell
curl --request GET \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/matching-refs/{ref}
```