# Create thread

> Starts a discussion thread on a conversation item with a first comment. Each item can have only one thread.

`POST /v2/api/threads`

<Note>
**Required scope:** `THREADS_WRITE`
</Note>

## Behavior

Starts a discussion thread on a conversation item. `content` becomes the thread's first comment, and the response is the full thread including that comment.

Each item can have **only one thread**. If one already exists, the request returns `409` with code `THREAD_ALREADY_EXISTS` — find it with [`GET /v2/api/threads`](/docs/threads/find-thread) and add a comment instead.

## Mentions

Mention teammates inline in `content` with `@[Display Name](usr-xxxx)` — see the [mentions guide](/docs/notes/overview#mentions).

## Errors

| Status | Code | When |
|--------|------|------|
| `400` | `INVALID_THREAD_ENTITY_TYPE` | `entity_type` is not one of `CALL`, `TEXT_MESSAGE`, `CONVERSATION_NOTE` |
| `400` | `EMPTY_NOTE_CONTENT` | `content` is missing or blank |
| `400` | `NOTE_CONTENT_TOO_LONG` | `content` exceeds 4,000 characters |
| `404` | `CONVERSATION_ITEM_NOT_FOUND` | No conversation item with this `entity_id` |
| `409` | `THREAD_ALREADY_EXISTS` | The item already has a thread |
