---
title: "Start a project Trail discussion"
method: POST
path: "/api/v1/{forge}/{project}/trails/{trailId}/discussions"
tags: ["Project Trails"]
---

# Start a project Trail discussion

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

## Path parameters

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

## Request body

- object
  - `title` string
  - `body` string

## Response `201`

Discussion response

- object
  - `discussion` object, required
    - `id` string, required
    - `trailId` string, required
    - `title` string, required
    - `kind` 'discussion', required
    - `etag` string
    - `resolved` boolean, required
    - `resolvedBy` string, nullable, required
    - `resolvedByIdentity` 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
    - `resolvedAt` string, nullable, required
    - `createdBy` string, nullable, required
    - `createdByIdentity` 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
    - `createdAt` string, required
    - `updatedAt` string, required
    - `lastMessageAt` string, nullable, required
    - `lastMessageAuthor` string, nullable, required
    - `messageCount` integer, required
    - `participants` object[], required
      - `login` string, required
    - `reviewCommentId` unknown, required
    - `reviewComment` unknown, 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
    - `createdAt` string, required
    - `body` string, required
    - `etag` string
    - `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
      - `createdAt` string, required
      - `body` string, required

## Other responses

- `400` — Request refused or upstream unavailable
- `401` — Request refused or upstream unavailable
- `403` — Request refused or upstream unavailable
- `404` — Request refused or upstream unavailable
- `409` — Request refused or upstream unavailable
- `412` — Request refused or upstream unavailable
- `422` — Request refused or upstream unavailable
- `429` — Request refused or upstream unavailable
- `502` — Request refused or upstream unavailable
- `503` — Request refused or upstream unavailable

## Changes

- **2026-09-24** `ba1409f8f36b` — 4 info
  - added the optional property `discussion/createdByIdentity` to the response with the `201` status
  - added the optional property `discussion/resolvedByIdentity` to the response with the `201` status
  - 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

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