---
title: "Update trail metadata"
method: PATCH
path: "/api/v1/trails/{host}/{owner}/{repo}/{number}"
tags: ["Trails"]
---

# Update trail metadata

`PATCH /api/v1/trails/{host}/{owner}/{repo}/{number}`

## Path parameters

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

## Request body

- object — Send body by itself to update Trail body Markdown; metadata fields cannot be combined with body.
  - `branch` string — Git branch name
  - `base` string — Base branch
  - `title` string — Trail title
  - `body` string — Trail body Markdown
  - `status` 'draft' | 'open' | 'merged' | 'closed' — Trail status
  - `assignees` string[] — GitHub usernames to set as trail assignees
  - `type` 'bug' | 'feature' | 'task' — Trail type
  - `priority` 'urgent' | 'high' | 'medium' | 'low' | 'none' — Priority level
  - `requested_reviewers` string[] — GitHub usernames requested to review

## Response `200`

Updated trail

- 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
    - `assignees` string[], required
    - `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
    - `requested_reviewers` string[]
    - `comment_count` number, required
    - `unresolved_count` number, required
    - `checkpoint_count` number
    - `has_code_changes` boolean
    - `monitors` object[]
      - `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

## Other responses

- `400` — Validation error
- `404` — Trail not found

---

[API](https://skmtc.dev/entire/apis/entire-api.md) · [All operations](https://skmtc.dev/entire/apis/entire-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/entire/entire-api/revisions/1134b24b642f/schema)