---
title: "List a repository's branches"
url: https://docs.corefinity.com/api/reference/deployments/list-site-deployment-branches
type: endpoint
last_updated: 2026-11-13
feature: deployments
related:
  - https://docs.corefinity.com/guides/sites/code-and-deployments/connect-a-repository.md
  - https://docs.corefinity.com/mcp/tools/corestack_deployments_branches_list.md
---
# List a repository's branches

Asks the git provider for the branches of one repository the connection can see, the default branch first,
then by name, at most 200. You must be someone who may deploy the site.

```http
GET /api/corestack/sites/{site}/deployments/branches
```

- Scope: `read`
- Two-factor: required on your account (all)
- Rate limit: 30 a minute
- Try it in the console: on

## Path parameters

- `site` (integer, required): The id of a site row. A website's production site and each of its environments has its own id. Digits only.

## Query parameters

- `connection` (integer, required): The id of a repository connection you may use on this site, as the settings list them in `connections`.
- `repo` (string, required): The repository as `owner/name`, or `group/subgroup/name` on GitLab.

## Request

### curl

```bash
curl 'https://manage.corefinity.com/api/corestack/sites/1042/deployments/branches?connection=4217&repo=northwind-digital%2Fharbourandfinch' \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json"
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->get('https://manage.corefinity.com/api/corestack/sites/1042/deployments/branches?connection=4217&repo=northwind-digital%2Fharbourandfinch');

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/deployments/branches?connection=4217&repo=northwind-digital%2Fharbourandfinch', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
  },
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.get(
    "https://manage.corefinity.com/api/corestack/sites/1042/deployments/branches?connection=4217&repo=northwind-digital%2Fharbourandfinch",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
)

data = res.json() if res.content else None
```

## Responses

### 200 The branches.

```json
{
  "branches": [
    {
      "default": true,
      "name": "main",
      "sha": "9730595c6ec7aa59b77674ada74e30d961b1817c"
    },
    {
      "default": false,
      "name": "develop",
      "sha": "4b1f0c9d2e7a8b6c5d4e3f2a1b0c9d8e7f6a5b4c"
    }
  ]
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope (`scope_required`, with the `scope` to use), or your company requires two-factor authentication and you have not set it up. For routes outside Managed Clusters.

```json
{
  "code": "company_unavailable",
  "message": "Your company is unavailable.",
  "reason": "company_unavailable"
}
```

### 404 The site does not exist or is one you cannot deploy, `connection` is not a connection you may use on this site, or deployments are not on for your company (`feature_off`).

```json
{
  "message": "Not found."
}
```

### 409 The git provider no longer accepts the connection (`needs_reauth`). Reconnect the account in the Control Panel.

```json
{
  "code": "needs_reauth",
  "message": "The GitLab connection needs re-authorising",
  "reason": "needs_reauth"
}
```

### 422 `connection` or `repo` is missing, `repo` is not `owner/name`, or the repository was not found with this connection (`invalid`). A git provider whose address cannot be reached answers a message only.

```json
{
  "code": "invalid",
  "errors": {
    "repo": [
      "Enter the repository as owner/name",
      "or group/subgroup/name on GitLab"
    ]
  },
  "field": "repo",
  "message": "Enter the repository as owner/name, or group/subgroup/name on GitLab",
  "reason": "invalid"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

### 502 A provider the request depends on did not answer. Nothing was changed; try again.

```json
{
  "message": "GitLab did not answer. Try again."
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 |  | Check the id. You see only what your account can reach. |
| 409 | `needs_reauth` | The repository's connection is gone or needs authorising again. Reconnect the repository. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 |  | Read the message; it says what happened. |

## The same task elsewhere

- Guide: [Connect a repository](https://docs.corefinity.com/guides/sites/code-and-deployments/connect-a-repository.md)
- MCP tool: [`corestack_deployments_branches_list`](https://docs.corefinity.com/mcp/tools/corestack_deployments_branches_list.md)
