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

# Create a trail discussion

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

## Path parameters

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

## Request body

- object
  - `title` string
  - `body` string, required

## Response `201`

Discussion created

- object
  - `discussion` union, required
    - object
      - `id` string, required
      - `trail_id` string, required
      - `title` string, required
      - `resolved` boolean, required
      - `resolved_by` string, nullable, required
      - `resolved_by_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
      - `resolved_at` string, nullable, required
      - `created_by` string, nullable, required
      - `created_by_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
      - `last_message_at` string, nullable, required
      - `last_message_author` string, nullable, required
      - `message_count` number, required
      - `participants` object[], required
        - `login` string, required
      - `kind` 'discussion', required
      - `review_comment_id` unknown, required
      - `review_comment` unknown, required
    - object
      - `id` string, required
      - `trail_id` string, required
      - `title` string, required
      - `resolved` boolean, required
      - `resolved_by` string, nullable, required
      - `resolved_by_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
      - `resolved_at` string, nullable, required
      - `created_by` string, nullable, required
      - `created_by_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
      - `last_message_at` string, nullable, required
      - `last_message_author` string, nullable, required
      - `message_count` number, required
      - `participants` object[], required
        - `login` string, required
      - `kind` 'code_review', required
      - `review_comment_id` string, required
      - `review_comment` object, required
        - `id` string, required
        - `trail_id` string, required
        - `repository_id` string, required
        - `review_id` string, required
        - `code_version_id` string, required
        - `actor_id` string, required
        - `actor_display_name` string, nullable
        - `actor_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
        - `body` string, nullable, required
        - `severity` 'high' | 'medium' | 'low', nullable, required
        - `confidence` number, nullable, required
        - `status` 'open' | 'resolved' | 'dismissed', required
        - `status_reason` string, nullable, required
        - `status_actor_id` string, nullable
        - `status_actor_display_name` string, nullable
        - `status_actor_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
        - `status_changed_at` string, nullable
        - `status_source` string, nullable
        - `status_actor_kind` string, nullable
        - `stale_outcome` 'current' | 'stale', required
        - `stale_checked_at` string, nullable, required
        - `stale_checked_code_version_id` string, nullable, required
        - `client_id` string, nullable, required
        - `client_id_hash` string, nullable, required
        - `created_at` string, required
        - `updated_at` string, required
        - `location` object, required
          - `id` string, required
          - `review_comment_id` string, required
          - `code_version_id` string, required
          - `granularity` 'line' | 'range' | 'file' | 'whole_change', required
          - `file_path` string, nullable, required
          - `start_line` number, nullable, required
          - `start_column` number, nullable, required
          - `end_line` number, nullable, required
          - `end_column` number, nullable, required
          - `selected_text` string, nullable, required
          - `nearby_text` string, nullable, required
          - `language` string, nullable, required
        - `discussion_id` string, required
        - `discussion_message_count` number, required
  - `message` object, nullable, required
    - `id` string, required
    - `author` string, 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
    - `body` string, required
    - `replies` object[], required
      - `id` string, required
      - `author` string, 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
      - `body` string, required

## Other responses

- `400` — Validation error
- `403` — Repository membership required
- `404` — Trail not found

## Changes

- **2026-09-24** `ba1409f8f36b` — 1 breaking, 3 info
  - added `subschema #1, subschema #2` to the `discussion` response property `oneOf` list for the response status `201`
  - added the optional property `message/anyOf[subschema #1]/identity` to the response with the `201` status
  - added the optional property `message/anyOf[subschema #1]/replies/items/identity` to the response with the `201` status
  - removed `subschema #1, subschema #2` from the `discussion` response property `oneOf` list for the response status `201`
- **2026-09-23** `a7ac2797c1a0` — 2 breaking, 2 info
  - removed the required property `discussion/oneOf[subschema #2]/review_comment/thread_id` from the response with the `201` status
  - removed the required property `discussion/oneOf[subschema #2]/review_comment/thread_message_count` from the response with the `201` status
  - added the required property `discussion/oneOf[subschema #2]/review_comment/discussion_id` to the response with the `201` status
  - added the required property `discussion/oneOf[subschema #2]/review_comment/discussion_message_count` to the response with the `201` status

[Change history](https://skmtc.dev/entire/apis/entire-api/changes/api/v1/trails/:forge/:owner/:repo/:number/discussions/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)