> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trellis.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Chat

> Create an empty chat row and obtain a chat_id

Create an empty chat and return its `id`. Every other chat surface — [Send Message](/api-reference/chats/send-message), [WebSocket](/api-reference/chats/websocket), and [Upload Files](/api-reference/chats/upload-files) — now requires an existing `chat_id`. Call this endpoint first.

<Note>
  This replaces the previous behavior where omitting `chat_id` from `POST /v1/chats` or `POST /v1/chats/uploads` would lazily create one. Those surfaces now reject the request with a `400 MISSING_CHAT_ID` error.
</Note>

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the [authenticate](/api-reference/authentication/authenticate) endpoint.
</ParamField>

<ParamField body="title" type="string">
  Custom title for the chat. If omitted, a timestamp-based title is generated.
</ParamField>

<ParamField body="integration_id" type="string">
  ID of the database integration this chat will query. When supplied, it is validated against the caller's organization and stored on the chat's metadata so subsequent messages don't need to resend it.
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  The newly created chat's ID. Pass this as `chat_id` on subsequent calls.
</ResponseField>

<ResponseField name="organization_id" type="string" required>
  Organization the chat belongs to.
</ResponseField>

<ResponseField name="member_id" type="string" required>
  Member the chat belongs to.
</ResponseField>

<ResponseField name="title" type="string" required>
  The chat's title.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp when the chat was created.
</ResponseField>

## Rate limits and caps

| Limit                 | Value                          | Response on breach              |
| --------------------- | ------------------------------ | ------------------------------- |
| Creation rate         | 20 requests per minute per JWT | `429` with `Retry-After` header |
| Open chats per member | 500                            | `409 OPEN_CHAT_CAP`             |

The open-chat cap counts every chat that hasn't been deleted; reach it and you must delete a chat (see [Delete Chat](/api-reference/chats/delete-chat) or [Delete Chats](/api-reference/chats/delete-chats)) before creating another.

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.trellis.sh/v1/chats/create \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Q4 revenue review",
      "integration_id": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      "https://api.trellis.sh/v1/chats/create",
      headers={
          "Authorization": "Bearer YOUR_TOKEN",
          "Content-Type": "application/json",
      },
      json={
          "title": "Q4 revenue review",
          "integration_id": "550e8400-e29b-41d4-a716-446655440000",
      },
  )
  chat_id = response.json()["id"]
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.trellis.sh/v1/chats/create", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Q4 revenue review",
      integration_id: "550e8400-e29b-41d4-a716-446655440000",
    }),
  });
  const { id: chatId } = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "chat_abc123",
    "organization_id": "org_abc123",
    "member_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Q4 revenue review",
    "created_at": "2026-04-29T18:00:00+00:00"
  }
  ```

  ```json 400 Integration not accessible theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "integration_id is not accessible to caller"
  }
  ```

  ```json 409 Open-chat cap reached theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": {
      "code": "OPEN_CHAT_CAP",
      "current_count": 500,
      "cap": 500
    }
  }
  ```

  ```json 429 Rate limited theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Rate limit exceeded",
    "retry_after_seconds": 12
  }
  ```
</ResponseExample>