---
title: "Create or link a branch to a trail"
method: POST
path: "/api/v1/trails/{forge}/{owner}/{repo}/{number}/branch"
tags: ["Trails"]
---

# Create or link a branch to a trail

`POST /api/v1/trails/{forge}/{owner}/{repo}/{number}/branch`

## Path parameters

- `forge` string, required
- `owner` string, required
- `repo` string, required
- `number` string, required

## Request body

- union
  - object
    - `action` 'create', required
    - `branch_name` string
  - object
    - `action` 'link', required
    - `branch_name` string, required

## Response `200`

Branch linked

- object
  - `trail` object, required
    - `id` string, required — Stable trail id. Use as :trail_id for trail-scoped review APIs.
    - `number` integer, required — Per-repo sequential identifier. Prefer this for URLs.
    - `url` string, required — Canonical browser URL for the trail.
    - `branch` string, nullable, required
    - `base` string, required
    - `title` string, required
    - `body_document` object, nullable
      - `id` string, required
      - `document_key` string, required
      - `schema_version` number, required
      - `content_json` unknown, required
      - `text_snapshot` string, nullable, required
      - `updated_at` string, required
    - `status` 'draft' | 'open' | 'merged' | 'closed', required
    - `type` 'bug' | 'feature' | 'task', required
    - `phase` 'planning' | 'building' | 'reviewing', nullable, required — Phase of an `open` trail: `planning` initially, `building` after code changes, `reviewing` when marked reviewing or when a reviewer is assigned. `null` for draft/merged/closed.
    - `author` object, nullable, required
      - `id` string, required
      - `login` string, nullable, required
      - `identity` object, nullable
        - `kind` string, required
        - `accountId` string, nullable, required
        - `displayName` string, nullable, required
        - `avatarUrl` string, nullable, required
        - `handles` object[], required
          - `provider` string, required
          - `handle` string, required
          - `isPrimary` boolean
    - `assignees` string[], required
    - `assignee_identities` object[]
      - `login` string, nullable, required
      - `identity` object, nullable
        - `kind` string, required
        - `accountId` string, nullable, required
        - `displayName` string, nullable, required
        - `avatarUrl` string, nullable, required
        - `handles` object[], required
          - `provider` string, required
          - `handle` string, required
          - `isPrimary` boolean
    - `created_at` string, required
    - `updated_at` string, required
    - `merged_at` string, nullable, required
    - `merge_base_sha` string, nullable
    - `base_sha` string, nullable
    - `head_sha` string, nullable
    - `priority` 'urgent' | 'high' | 'medium' | 'low' | 'none', required
    - `reviewers` object[], required
      - `login` string, required
      - `status` 'approved' | 'changes_requested' | 'pending', required
      - `identity` object, nullable
        - `kind` string, required
        - `accountId` string, nullable, required
        - `displayName` string, nullable, required
        - `avatarUrl` string, nullable, required
        - `handles` object[], required
          - `provider` string, required
          - `handle` string, required
          - `isPrimary` boolean
    - `ready_for_review` boolean, required
    - `comment_count` number, required
    - `unresolved_count` number, required
    - `checkpoint_count` number
    - `has_code_changes` boolean
    - `runners` object[]
      - `state` 'not_run' | 'running' | 'evaluated' | 'stale' | 'disabled' | 'not_applicable' | 'configuration_error', required
      - `outcome` 'passed' | 'failed' | 'errored', nullable
      - `evaluated_at_sha` string, nullable
      - `stale_reason` 'head_moved' | 'config_changed', nullable
      - `runner_id` string, required
      - `run_id` string, nullable, required
      - `started_at` string, nullable, required
    - `mergeability` object, nullable
      - `gates` object[], required
        - `reviewers` object[]
          - `login` string, required
          - `state` 'pending' | 'approved' | 'stale' | 'changes_requested' | 'excluded', required
          - `reviewed_head_sha` string, nullable, required
          - `reason` string, nullable, required
        - `runner_ids` string[]
        - `state` 'not_run' | 'running' | 'evaluated' | 'stale' | 'disabled' | 'not_applicable' | 'configuration_error'
        - `outcome` 'passed' | 'failed' | 'errored', nullable
        - `evaluated_at_sha` string, nullable
        - `stale_reason` 'head_moved' | 'config_changed', nullable
        - `finding_count` number, nullable
        - `id` string, required
        - `gate_definition_id` string, required
        - `gate_key` string, required
        - `gate_type` 'approvals' | 'findings' | 'checks' | 'up_to_date' | 'base_checks' | 'eval', required
        - `blocking` boolean, required
        - `status` 'passed' | 'failed' | 'pending' | 'error' | 'skipped', required
        - `head_sha` string, nullable, required
        - `value` unknown, required
        - `rationale` string, nullable, required
        - `created_at` string, required
        - `completed_at` string, nullable, required
      - `head_sha` string, nullable, required
      - `checks` object, required
        - `availability` 'available' | 'unavailable' | 'not_applicable', required
        - `runs` object[], required
          - `id` number, required
          - `name` string, required
          - `status` string, required
          - `conclusion` string, nullable, required
          - `html_url` string, nullable, required
          - `started_at` string, nullable, required
          - `completed_at` string, nullable, required
          - `app_name` string, nullable, required
          - `required` boolean
      - `behind_by` number, required
      - `comparison_status` 'available' | 'unknown', required
      - `conflict_status` 'clean' | 'conflicting' | 'unknown', required
      - `mergeable` boolean, required
      - `bypass_policy` 'nobody' | 'admins' | 'admins_author', required
    - `config_source` 'live' | 'snapshot' | 'live_fallback' | 'unavailable'
    - `actions` object
      - `approve` object, required
        - `state` 'enabled' | 'blocked' | 'unavailable', required
        - `reason` string, nullable, required
      - `createCiPr` object, required
        - `state` 'enabled' | 'blocked' | 'unavailable', required
        - `reason` string, nullable, required
      - `merge` object, required
        - `state` 'enabled' | 'blocked' | 'unavailable', required
        - `reason` string, nullable, required
      - `mergeWithBypass` object, required
        - `state` 'enabled' | 'blocked' | 'unavailable', required
        - `reason` string, nullable, required
    - `monitors` object[]
      - `state` 'not_run' | 'running' | 'evaluated' | 'stale' | 'disabled' | 'not_applicable' | 'configuration_error'
      - `outcome` 'passed' | 'failed' | 'errored', nullable
      - `evaluated_at_sha` string, nullable
      - `stale_reason` 'head_moved' | 'config_changed', nullable
      - `last_failed_attempt` object, nullable
        - `run_id` string, required
        - `head_sha` string, nullable, required
        - `failed_at` string, required
      - `key` string, required
      - `label` string, required
      - `value_type` 'percent' | 'size' | 'boolean', required
      - `percent_value` number, nullable, required
      - `size_value` 'small' | 'medium' | 'large', nullable, required
      - `boolean_value` boolean, nullable, required
      - `rationale` string, nullable, required
      - `polarity` 'higher_is_better' | 'lower_is_better' | 'neutral', nullable, required
      - `trend_delta` number, nullable
      - `evaluating` boolean
      - `history` object[]
        - `percent_value` number, nullable, required
        - `size_value` 'small' | 'medium' | 'large', nullable, required
        - `boolean_value` boolean, nullable, required
        - `rationale` string, nullable, required
        - `evaluating` boolean
        - `run_id` string, required
        - `head_sha` string, nullable, required
        - `updated_at` string, required
      - `run_id` string, required
      - `head_sha` string, nullable, required
      - `updated_at` string, required
  - `branch_created` boolean, required

## Other responses

- `400` — Validation error
- `409` — Trail already has a linked branch

## Changes

- **2026-09-25** `14c8416feab7` — 1 breaking, 1 warning, 16 info
  - removed the required property `trail/mergeability/anyOf[subschema #1]/approval_gate_passed` from the response with the `200` status
  - removed the optional property `trail/gates` from the response with the `200` status
  - added the optional property `trail/mergeability/anyOf[subschema #1]/gates/items/evaluated_at_sha` to the response with the `200` status
  - added the optional property `trail/mergeability/anyOf[subschema #1]/gates/items/finding_count` to the response with the `200` status
  - …14 more
- **2026-09-24** `ba1409f8f36b` — 2 warning, 3 info
  - added the new `base_checks` enum value to the `trail/gates/items/gate_type` response property for the response status `200`
  - added the new `base_checks` enum value to the `trail/mergeability/anyOf[subschema #1]/gates/items/gate_type` response property for the response status `200`
  - added the optional property `trail/assignee_identities` to the response with the `200` status
  - added the optional property `trail/author/anyOf[subschema #1]/identity` to the response with the `200` status
  - …1 more
- …earlier changes not shown

[Full history](https://skmtc.dev/entire/apis/entire-api/changes/api/v1/trails/:forge/:owner/:repo/:number/branch/post.md)

---

[API](https://skmtc.dev/entire/apis/entire-api.md) · [All operations](https://skmtc.dev/entire/apis/entire-api/llms.txt) · [OpenAPI document](https://skmtc.dev/entire/apis/entire-api/revisions/d69a682d6e44?raw)