# Create Branch

## API Name

API Name: Branch – Create

***

## Overview

This API creates a new branch within a given project.

Branch name selection is delegated to the connector implementation because:

* Branch naming rules vary across end systems.
* Some systems enforce strict naming constraints.
* Some systems automatically append suffixes for uniqueness.
* Some systems reject duplicate branch names.

Connector responsibility:

* Generate a unique branch name compliant with end system constraints.
* Preferably use a timestamp-based strategy to ensure uniqueness.
* Call the end system API to create the branch in the specified project.
* Return created branch details.
* If branch creation fails, return appropriate error response.

***

### API URI

```bash
POST: /mbse/api/1.0/branches
    ?projectId={projectId}
```

***

### URI Parameters

| Name      | Mandatory | Type   | Description                                                |
| --------- | --------- | ------ | ---------------------------------------------------------- |
| projectId | True      | String | ID of the project in which the branch needs to be created. |

***

### Behavior Rules

1. Branch must be created within the context of the given `projectId`.
2. Connector must:
   * Generate a branch name compliant with end system rules.
   * Ensure branch name uniqueness.
3. Recommended approach:
   * Use timestamp-based naming strategy (e.g., `branch_YYYYMMddHHmmss`).
4. The API must return the created branch details.
5. If branch creation fails:
   * Return appropriate HTTP error code.
6. Connector must not return a null response.

***

### Response Payload

#### Sample Response

```json
{
  "branchId": "branch_20260214123045",
  "branchName": "branch_20260214123045"
}
```

***

### Response Parameters

| Name       | Required | Type   | Description                                    |
| ---------- | -------- | ------ | ---------------------------------------------- |
| branchId   | True     | String | Unique identifier of the newly created branch. |
| branchName | True     | String | Display name of the branch.                    |

***

### Error Handling

| HTTP Status | Description                                   |
| ----------- | --------------------------------------------- |
| 400         | Invalid project ID or invalid request.        |
| 404         | Project not found.                            |
| 409         | Branch creation conflict (if applicable).     |
| 500         | Internal server error during branch creation. |

***

### Example Use Case

#### Create New Branch

```bash
POST /mbse/api/1.0/branches?
projectId=123
```

***

### Implementation Guidelines

* Connector must sanitize branch name according to end system rules.
* Avoid hardcoding branch names.
* Prefer deterministic timestamp-based naming for traceability.
* Ensure created branch belongs strictly to provided project.
* Return branch details exactly as created in end system.

***

### Design Rationale

This API keeps branch naming logic flexible and system-aware.

By delegating naming to the connector:

* The MBSE layer remains system-agnostic.
* Integration remains portable across multiple modeling tools.
* Naming conflicts are handled locally by connector logic.

This design ensures consistent behavior across heterogeneous MBSE systems.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://opstech.gitbook.io/opstech-docs/mbse-connector-sdk-index/mbse-sdk-connector-apis/branch-apis/create-branch.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.