create_pull_request

Open a merge request (pull request) from head_branch into base_branch. Use this to start a team review workflow before merging a scenario branch. Opening the pull request does not add an approval or authorize a merge. Optionally pass reviewer_user_ids to explicitly assign active model editors or owners; those assignments are persisted as Bridge Town principals and trigger the existing deduplicated review notification.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model.')]	Yes	—
title	Annotated[str, Field(description='Title for the pull request.')]	Yes	—
head_branch	Annotated[str, Field(description='Branch containing the changes to merge.')]	Yes	—
base_branch	Annotated[str, Field(description="Target branch to merge into (typically 'main').")]	No	'main'
body	Annotated[str, Field(description='Optional description or context for the pull request.')]	No	''
reviewer_user_ids	Annotated[list[uuid.UUID], Field(description='Optional Bridge Town workspace user IDs to request for review. Only active model editors and owners are accepted; maximum 20.', max_length=20)]	No	—
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• id (integer)
• title (string)
• state (string)
• head_branch (string)
• base_branch (string)
• author (object)
• created_at (string)
• updated_at (string)
• merged (boolean)
• actor (object)
• workspace_id (string)
• requested_reviewers (array<object>)
• reviewer_assignment_version (integer)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "create_pull_request",
  "arguments": {
    "model_name": "forecasts",
    "title": "Aggressive growth scenario",
    "head_branch": "scenario/aggressive-growth",
    "base_branch": "main",
    "body": "Bumps growth_rate from 10% to 15%.",
    "reviewer_user_ids": [
      "22222222-2222-2222-2222-222222222222"
    ]
  }
}

Response

{
  "id": 42,
  "title": "Aggressive growth scenario",
  "state": "open",
  "head_branch": "scenario/aggressive-growth",
  "base_branch": "main",
  "author": {
    "kind": "human",
    "display_name": "Alice"
  },
  "created_at": "2026-04-28T10:00:00+00:00",
  "updated_at": "2026-04-28T10:00:00+00:00",
  "merged": false,
  "actor": {
    "kind": "human",
    "display_name": "Alice"
  },
  "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "requested_reviewers": [
    {
      "reviewer_user_id": "22222222-2222-2222-2222-222222222222",
      "display_name": "Bob",
      "state": "requested",
      "review_submitted_at": null
    }
  ],
  "reviewer_assignment_version": 1
}

Notes

• Module: Pull Requests
• Requires an authenticated Bridge Town session (OAuth) or an API token.
• Reviewer assignments use active Bridge Town workspace principals; the service does not infer assignments from email history.
• Opening a PR can notify eligible model owners under the existing review-notification policy. Reads do not send notifications.