create_branch

Create a new git branch in a model. Use this to start a scenario branch for testing alternative assumptions. Scenario workflow: (1) create_branch to start the scenario, (2) patch_file for small edits or update_file for larger changeson the scenario branch, (3) compare_branches to run both branches and diff the outputs, (4) merge_branch (Owner only) to adopt the winning scenario into main, or create_pull_request for team review before merging.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model.')]	Yes	—
branch_name	Annotated[str, Field(description='Name for the new branch. Must be a valid git ref name (no spaces, no special chars except hyphens and underscores).')]	Yes	—
base_branch	Annotated[str, Field(description="Branch to create from. Defaults to 'main'.")]	No	'main'
expected_base_sha	Annotated[str, Field(description="Optional expected SHA of base_branch's tip for optimistic concurrency. Fails if base_branch has moved (e.g. another collaborator's commit) since you last read it, so the new branch is never silently created off unexpected content.")]	No	''
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• model (string)
• branch (string)
• base_branch (string)
• sha (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "create_branch",
  "arguments": {
    "model_name": "forecasts",
    "branch_name": "scenario/aggressive-growth",
    "base_branch": "main"
  }
}

Response

{
  "model": "forecasts",
  "branch": "scenario/aggressive-growth",
  "base_branch": "main",
  "sha": "abc1234def5678901234567890abcdef12345678"
}

Notes

• Module: Branches
• Requires authentication via API token or Auth0 JWT.