---
title: "Create or link branch-backed work under a Trail"
method: POST
path: "/api/v1/{forge}/{project}/trails/{trailId}/changes"
tags: ["Project Trails"]
---

# Create or link branch-backed work under a Trail

`POST /api/v1/{forge}/{project}/trails/{trailId}/changes`

## Path parameters

- `forge` 'gh' | 'et', required
- `project` string, required
- `trailId` string, required

## Headers

- `If-Match` string, required
- `Idempotency-Key` string, required

## Request body

- object
  - `repositoryId` string, required
  - `title` string, required
  - `body` string
  - `branchName` string, required
  - `branchAction` 'create' | 'link'
  - `base` string
  - `status` 'draft' | 'open' | 'closed' | 'merged'
  - `readyForReview` boolean
  - `assignees` string[]
  - `type` 'bug' | 'feature' | 'task'
  - `priority` 'urgent' | 'high' | 'medium' | 'low' | 'none'

## Response `201`

Created or reused Change; ETag is the parent version

- object
  - `id` string, required
  - `trailId` string, required
  - `repositoryId` string, required

## Other responses

- `400` — Invalid request
- `401` — Not authenticated
- `403` — Feature disabled or access denied
- `404` — Project, Trail, or Change not found
- `409` — Resource conflict
- `412` — ETag precondition failed
- `422` — Validation failed
- `429` — Rate limit exceeded
- `502` — Project cell unavailable
- `503` — Project Trails unavailable

---

[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)