# Creating Branches

### About this export

| Field | Value |
| --- | --- |
| **content_type** | lesson |
| **platform** | contentstack-academy |
| **source_url** | https://www.contentstack.com/academy/courses/branches-foundations/creating-branches |
| **course_slug** | branches-foundations |
| **lesson_slug** | creating-branches |
| **markdown_file_url** | /academy/md/courses/branches-foundations/creating-branches.md |
| **generated_at** | 2026-04-28T06:55:36.126Z |

> Part of **[Branches Foundations](https://www.contentstack.com/academy/courses/branches-foundations)** on Contentstack Academy. **Academy MD v3** — structured for retrieval; no quiz or assessment keys.

<!-- ai_metadata: {"lesson_id":"03","type":"text","duration_minutes":1,"topics":["Creating","Branches"]} -->

#### Lesson text

### **Creating Branches with API****Prerequisites:**

1.  **API Key and AuthToken:**
    
    Ensure you have the API key and [authtoken](https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens) for your Contentstack account.
    
2.  **Contentstack Stack API Endpoint:**
    
    Obtain the base API endpoint for your Contentstack stack.
    

## **Steps:**

### **1\. Authentication:**

Before making API calls, ensure you authenticate your requests by including the API key and authtoken in the headers.

Headers:  
Content-Type: application/json  
api\_key: YOUR\_API\_KEY  
authtoken : YOUR\_AUTH\_TOKEN  

### **2\. Get Existing Branches (Optional):**

You can retrieve information about existing branches in your Contentstack stack if needed.

GET /v3/stacks/branches

curl --location 'https://api.contentstack.io/v3/stacks/branches' \\  
  
\--header 'api\_key: \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*' \\  
  
\--header 'authtoken: \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*' \\  
  
\--header 'Content-Type: application/json' \\  
  
\--data ''

### **3\. Create a New Branch:**

To create a new branch, use the following API call:

POST /v3/stacks/branches

Request Body: {  
  
  "branch": {  
  
    "name": "NewBranchName",  
  
    "source": "SourceBranchID"  
  
  }  
  
}

*   Replace "NewBranchName" with the desired name for the new branch.
    

Replace "SourceBranchID" with the ID of the branch from which the new branch should inherit its data.  
  
  
curl --location 'https://api.contentstack.io/v3/stacks/branches' \\  
  
\--header 'Content-Type: application/json' \\  
  
\--header 'api\_key: \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*' \\  
  
\--header 'authtoken: \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*' \\  
  
\--header 'Content-Type: application/json' \\  
  
\--data '{  
  
    "branch": {  
  
        "uid": "dev",  
  
        "source": "main"  
  
    }  
  
}'

### **4\. Response:**

Upon successful creation, the response will include details about the new branch, including its unique ID.

{  
  
  "branch": {  
  
    "uid": "NEW\_BRANCH\_ID",  
  
    "name": "NewBranchName",  
  
    "source": "SourceBranchID",  
  
    // Other branch details...  
  
  }  
  
}  
  
  
{  
  
    "notice": "Your request to create branch is in progress. Please check organization bulk task queue for more details.",  
  
    "branch": {  
  
        "uid": "dev",  
  
        "source": "main",  
  
        "created\_by": "\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*",  
  
        "updated\_by": "\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*",  
  
        "created\_at": "2024-01-23T12:42:23.260Z",  
  
        "updated\_at": "2024-01-23T12:42:23.260Z",  
  
        "deleted\_at": "in-progress",  
  
        "alias": \[\]  
  
    }  
  
}

![branches-token.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltb75e380c0f638072/664d4eaa78533908439e4fac/branches-token.png)

### **5\. Error Handling:**

Handle errors by checking the status code and the response body. Common error responses include details about what went wrong.

### **6\. Conclusion:**

With these API calls, you can seamlessly integrate branch creation into your Contentstack workflows, facilitating efficient collaboration and content development.

## **Creating Branches Using CLI**

### **Prerequisites:**

1.  **Contentstack CLI:**
    
    *   Ensure you have the Contentstack CLI tool installed. You can install it from [https://www.contentstack.com/docs/developers/cli/install-the-cli](https://www.contentstack.com/docs/developers/cli/install-the-cli).
        
    
2.  **API Key:**
    
    *   Obtain the API key for your Contentstack stack.
        
    

### **Steps:**

### **1\. Configure CLI:**

Before initiating any commands, configure the Contentstack CLI tool with your API key, access token, and stack ID.

csdx auth:login

Follow the prompts to enter your API key, access token, and stack ID.

### **2\. Create a New Branch:**

Use the following command to create a new branch:

USAGE  
  $ csdx cm:branches:create  
  $ csdx cm:branches:create \[--source \] \[--uid \] \[-k \]  
  $ csdx cm:branches:create \[--source \] \[--uid \] \[--stack-api-key \]

FLAGS  
  -k, --stack-api-key=  Stack API key  
  --source=             Source branch from which new branch to be created  
  --uid=                Branch UID to be created

DESCRIPTION  
  Create a new branch

EXAMPLES  
  $ csdx cm:branches:create

  $ csdx cm:branches:create --source main -uid new\_branch -k bltxxxxxxxx

  $ csdx cm:branches:create --source main --uid new\_branch --stack-api-key bltxxxxxxxx

*   Replace new\_branch with the desired name for the new branch.
    
*   Replace source with the ID of the branch from which the new branch should inherit its data.
    
*   Provide API key value to -k or --stack-api-key
    

### 

![BranchesFoundations-L3-img-2.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt5ac58f90e15ecec3/67dc8839983a6519853b73d2/BranchesFoundations-L3-img-2.png)

### **3\. View Created Branch:**

Verify the successful creation of the branch by listing the existing branches:

List the branches

USAGE  
  $ csdx cm:branches

FLAGS  
  -k, --stack-api-key=  Stack API Key  
  --verbose                    Verbose

DESCRIPTION  
  List the branches

EXAMPLES  
  $ csdx cm:branches

  $ csdx cm:branches --verbose

  $ csdx cm:branches -k

This command will display a list of branches associated with your Contentstack stack, including the newly created branch.

![BranchesFoundations-L3-img-3.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltff9181c58c6a9665/67dc886545b229efcb910ded/BranchesFoundations-L3-img-3.png)

### **4\. Conclusion:**

Congratulations! You have successfully created a new branch in Contentstack using the CLI tool. This streamlined process allows for efficient management of content branches, fostering collaborative content development within your Contentstack environment.

# **Creating a Branch with the UI**

To delve into the intricacies of creating a new branch, users are required to navigate through the Contentstack interface and adhere to a structured set of steps:

1.  ## **Accessing Branch Settings:**
    
    *   Log in to your Contentstack account and proceed to the settings panel.
        
    *   Choose the "Branches" option to initiate the branch creation process.  
          
        
        ![BranchesFoundations-L3-img-4.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltc0d6b1880c4370b8/67dc888add73e3919fbf2be3/BranchesFoundations-L3-img-4.png)  
          
        
    
2.  ## **Initiating New Branch:**
    
    *   Within the Branches section, locate the "+ New Branch" option situated in the top-right corner.
        
    *   Click on this option to commence the creation of a fresh branch.  
          
        
        ![BranchesFoundations-L3-img-5.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt31eb048058c803d3/67dc88a398672543b08881e6/BranchesFoundations-L3-img-5.png)
        
    
3.  ## **Completing the Create New Branch Form:**
    
    *   Upon selecting to create a new branch, a prompt directs users to the "Create New Branch" form.
        
    *   Users are required to furnish the form with specific information to define the new branch.  
          
        
        ![BranchesFoundations-L3-img-6.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltf5c89f40d9347533/67dc88beb1a1f3c27c3ef06b/BranchesFoundations-L3-img-6.png)
        
    
4.  ## **Essential Information in the Create New Branch Form:**
    
    *   **Branch ID:** Users must assign a unique identifier to the branch, facilitating a clear distinction.
        
    *   **Source Selection:** From the provided dropdown menu, users must select the source branch from which the new branch will inherit its data.  
          
        ![BranchesFoundations-L3-img-7.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt99acc19d22f87666/67dc88d545b229e98e910df3/BranchesFoundations-L3-img-7.png)
        
    
5.  ## **Finalizing the Branch Creation:**
    
    *   To conclude the branch creation process, users are instructed to click the "Save" button in the form's bottom-right corner.
        
    

![BranchesFoundations-L3-img-8.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt765540af59682c04/67dc88f4037e2ba01b22d1b3/BranchesFoundations-L3-img-8.png)

![BranchesFoundations-L3-img-9.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blta7b764092858f5f6/67dc890df7eccc8c0490cfcd/BranchesFoundations-L3-img-9.png)

  

## **Further Reference**

*   [Creating a branch using API](https://www.contentstack.com/docs/developers/apis/content-management-api#create-a-branch)
    
*   [Creating a branch using CLI](https://www.contentstack.com/docs/developers/cli/compare-and-merge-branches-using-the-cli#create-a-branch)
    
*   [Listing Branches using CLI](https://www.contentstack.com/docs/developers/cli/compare-and-merge-branches-using-the-cli#list-branches)
    
*   [Creating a Branch using UI](https://www.contentstack.com/docs/developers/branches/create-a-branch)

#### Key takeaways

- Connect **Creating Branches** back to your stack configuration before moving to the next module.
- Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment.
- Re-read the delivery versus management boundary for anything you changed in the entry model.

## Supplement for indexing

### Content summary

Creating Branches. Creating Branches with API Prerequisites: 1. API Key and AuthToken: Ensure you have the API key and authtoken (https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens authentication-tokens-authtokens) for your Contentstack account. 2. Contentstack Stack API Endpoint: Obtain the base API endpoint for your Contentstack stack. Steps: 1\. Authentication: Before making API calls, ensure you authenticate your requests by including the API key and authtoken in the headers. Headers: Content-Type: application/json api\ key: YOUR\ API\ KEY authtoken : YOUR\ AUTH\ TOKEN 2\. Get Existing Branches (Optional): You can retrieve information about existing branches in your Contentstack sta

### Retrieval tags

- Creating
- Branches
- branches-foundations
- lesson 03
- Creating Branches
- branches-foundations lesson

### Indexing notes

Index this lesson as a primary chunk tagged with lesson_id "03" and topics: [Creating, Branches].
Parent course slug: branches-foundations. Use asset_references URLs as thumbnail hints in search results when present.
Never surface LMS quiz content or assessment answers from this file.

### Asset references

| Label | URL |
| --- | --- |
| branches-token.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltb75e380c0f638072/664d4eaa78533908439e4fac/branches-token.png` |
| BranchesFoundations-L3-img-2.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt5ac58f90e15ecec3/67dc8839983a6519853b73d2/BranchesFoundations-L3-img-2.png` |
| BranchesFoundations-L3-img-3.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltff9181c58c6a9665/67dc886545b229efcb910ded/BranchesFoundations-L3-img-3.png` |
| BranchesFoundations-L3-img-4.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltc0d6b1880c4370b8/67dc888add73e3919fbf2be3/BranchesFoundations-L3-img-4.png` |
| BranchesFoundations-L3-img-5.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt31eb048058c803d3/67dc88a398672543b08881e6/BranchesFoundations-L3-img-5.png` |
| BranchesFoundations-L3-img-6.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltf5c89f40d9347533/67dc88beb1a1f3c27c3ef06b/BranchesFoundations-L3-img-6.png` |
| BranchesFoundations-L3-img-7.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt99acc19d22f87666/67dc88d545b229e98e910df3/BranchesFoundations-L3-img-7.png` |
| BranchesFoundations-L3-img-8.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt765540af59682c04/67dc88f4037e2ba01b22d1b3/BranchesFoundations-L3-img-8.png` |
| BranchesFoundations-L3-img-9.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blta7b764092858f5f6/67dc890df7eccc8c0490cfcd/BranchesFoundations-L3-img-9.png` |

### External links

| Label | URL |
| --- | --- |
| Contentstack Academy home | `https://www.contentstack.com/academy/` |
| Training instance setup | `https://www.contentstack.com/academy/training-instance` |
| Academy playground (GitHub) | `https://github.com/contentstack/contentstack-academy-playground` |
| Contentstack documentation | `https://www.contentstack.com/docs/` |
| authtoken | `https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens` |
| branches-token.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltb75e380c0f638072/664d4eaa78533908439e4fac/branches-token.png` |
| https://www.contentstack.com/docs/developers/cli/install-the-cli | `https://www.contentstack.com/docs/developers/cli/install-the-cli` |
| BranchesFoundations-L3-img-2.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt5ac58f90e15ecec3/67dc8839983a6519853b73d2/BranchesFoundations-L3-img-2.png` |
| BranchesFoundations-L3-img-3.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltff9181c58c6a9665/67dc886545b229efcb910ded/BranchesFoundations-L3-img-3.png` |
| BranchesFoundations-L3-img-4.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltc0d6b1880c4370b8/67dc888add73e3919fbf2be3/BranchesFoundations-L3-img-4.png` |
| BranchesFoundations-L3-img-5.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt31eb048058c803d3/67dc88a398672543b08881e6/BranchesFoundations-L3-img-5.png` |
| BranchesFoundations-L3-img-6.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltf5c89f40d9347533/67dc88beb1a1f3c27c3ef06b/BranchesFoundations-L3-img-6.png` |
| BranchesFoundations-L3-img-7.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt99acc19d22f87666/67dc88d545b229e98e910df3/BranchesFoundations-L3-img-7.png` |
| BranchesFoundations-L3-img-8.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt765540af59682c04/67dc88f4037e2ba01b22d1b3/BranchesFoundations-L3-img-8.png` |
| BranchesFoundations-L3-img-9.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blta7b764092858f5f6/67dc890df7eccc8c0490cfcd/BranchesFoundations-L3-img-9.png` |
| Creating a branch using API | `https://www.contentstack.com/docs/developers/apis/content-management-api#create-a-branch` |
| Creating a branch using CLI | `https://www.contentstack.com/docs/developers/cli/compare-and-merge-branches-using-the-cli#create-a-branch` |
| Listing Branches using CLI | `https://www.contentstack.com/docs/developers/cli/compare-and-merge-branches-using-the-cli#list-branches` |
| Creating a Branch using UI | `https://www.contentstack.com/docs/developers/branches/create-a-branch` |