---
title: "Create a new branch for a project"
method: POST
path: "/v0/projects/{project}/branches"
---

# Create a new branch for a project

`POST /v0/projects/{project}/branches`

## Path parameters

- `project` string, required

## Request body

- object
  - `branch` string, required — Name of the new project branch.
  - `branch_from` string, required — Branch or commit SHA to branch from.
  - `force` boolean — Whether to throw an error if the branch already exists. Defaults to false.

## Response `200`

success

- ProjectBranch
  - `object` 'project_branch', required
  - `branch` string, required
  - `org` string, required
  - `project` string, required
  - `config_commit` object, required
    - `sha` string, required
    - `repo` object, required
      - `owner` string, required
      - `name` string, required
      - `branch` string, required
  - `latest_build` BuildObject, required
    - `object` 'build', required
    - `id` string, required
    - `project` string, required
    - `org` string, required
    - `config_commit` string, required
    - `documented_spec` union, required
      - object
        - `type` 'content', required
        - `content` string, required
      - object
        - `type` 'url', required
        - `url` string, required
        - `expires` string, date-time, required
    - `targets` object, required
      - `node` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `typescript` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `python` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `go` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `java` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `kotlin` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `ruby` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `terraform` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `cli` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `php` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
      - `csharp` BuildTarget
        - `object` 'build_target', required
        - `status` 'not_started' | 'codegen' | 'postgen' | 'completed', required
        - `commit` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `lint` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `test` union, required
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `build` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …
        - `upload` union
          - object
            - `status` 'not_started', required
          - object
            - `status` 'queued', required
          - object
            - `status` 'in_progress', required
          - object
            - `status` 'completed', required
            - `completed` object, required
              - …

## Changes

- **2025-07-07** `f8b160dfac6c` — 45 info
  - added the required property `latest_build/oneOf[#/components/schemas/BuildObject]/documented_spec/oneOf[subschema #2]/expires` to the response with the `200` status
  - added the required property `latest_build/oneOf[#/components/schemas/BuildObject]/targets/cli/build/oneOf[subschema #4]/completed/url` to the response with the `200` status
  - added the required property `latest_build/oneOf[#/components/schemas/BuildObject]/targets/cli/lint/oneOf[subschema #4]/completed/url` to the response with the `200` status
  - added the required property `latest_build/oneOf[#/components/schemas/BuildObject]/targets/cli/test/oneOf[subschema #4]/completed/url` to the response with the `200` status
  - …41 more

[Change history](https://skmtc.dev/stainless-api/apis/my-api/changes/v0/projects/:project/branches/post.md)

---

[API](https://skmtc.dev/stainless-api/apis/my-api.md) · [All operations](https://skmtc.dev/stainless-api/apis/my-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stainless-api/my-api/revisions/f8b160dfac6c/schema)