# General Translation Platform: Create a branch
URL: https://generaltranslation.com/en-GB/docs/platform/openapi/reference/project/create-branch.mdx
---

title: Create a branch
description: Create a branch, or rename and confirm the default branch, in a General Translation Project. API reference for Create a branch.

method: POST
---

Creates a branch in a Project, or confirms and renames the default branch. Returns the resulting branch's ID and name.

## Overview [#overview]

```http
POST https://api2.gtx.dev/v2/project/branches/create
```

**Permission** `project:files:write` · **Rate limit** Default (200/min)

Set up a branch before uploading files to it. To look up existing branches, use [Get branch information](/docs/platform/openapi/reference/project/branch-info).

## How it works [#how-it-works]

* When `defaultBranch` is `true` and a default branch already exists, the existing default branch is returned. If the provided `branchName` differs, the default branch is renamed to match it.
* Creating a non-default branch requires a paid plan. On the free plan, a non-default branch request returns `403`.
* Otherwise, the branch is created (or reused if it already exists) and returned with its `id` and `name`.

## Request [#request]

### Headers

| Header            | Description                                          | Required |
| ----------------- | ---------------------------------------------------- | -------- |
| `x-gt-api-key`    | Project or Organisation API key.                     | Yes      |
| `x-gt-project-id` | Project ID. Required when using an Organisation key. | No       |

### Body

**Content type** `application/json`

| Field           | Description                                     | Type      | Optional | Default |
| --------------- | ----------------------------------------------- | --------- | -------- | ------- |
| `branchName`    | Name of the branch; must not be empty.          | `string`  | No       | —       |
| `defaultBranch` | Treat this as the Project's default branch. | `boolean` | Yes      | `false` |

## Response [#response]

**Status** `200 OK`

```json title="Response"
{
  "branch": { "id": "br_...", "name": "feature-x" }
}
```

## Errors [#errors]

| Status | Cause                                                                                      |
| ------ | ------------------------------------------------------------------------------------------ |
| `400`  | Invalid request body, or empty `branchName`.                                               |
| `401`  | Missing or invalid API key.                                                                |
| `403`  | API key lacks `project:files:write`, or the free plan does not allow non-default branches. |
| `429`  | Rate limit exceeded.                                                                       |

## Example [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/branches/create \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "branchName": "feature-x"
  }'
```