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

# Create Chat

> Start a new conversation for a chatbot and receive a chat ID.

Create a new chat for one of your chatbots. The returned `chatId` is required for sending messages and reading the conversation.

## Authentication

This request requires your API key in the `x-api-key` header.

## Request

**chatbotId** `string` *required*

ID of the chatbot the chat belongs to.

**userId** `string`

Optional ID identifying the end user. Use it to associate a chat with a known user in your system.

## Response

**id** `string` *required*

ID of the created chat. Use it as the `chatId` in later requests.

**chatbotId** `string` *required*

ID of the chatbot the chat belongs to.

**userId** `string` *required*

ID of the associated end user.

**organizationId** `string` *required*

ID of the organization that owns the chat.

**createdAt** `string` *required*

ISO 8601 timestamp of when the chat was created.

## Examples

```bash cURL theme={null}
curl -X POST https://api.yourhomie.ai/v1/chats \
  -H "x-api-key: homie_sk_live_8f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotId": "5e9c1a2b-3d4e-4f60-b2f2-9f4b1c2d3e4f"
  }'
```

```javascript JavaScript (fetch) theme={null}
const res = await fetch("https://api.yourhomie.ai/v1/chats", {
  method: "POST",
  headers: {
    "x-api-key": "homie_sk_live_8f3a...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chatbotId: "5e9c1a2b-3d4e-4f60-b2f2-9f4b1c2d3e4f",
  }),
});

const chat = await res.json();
```

### Success response

```json theme={null}
{
  "id": "ab12cd34-ef56-7890-ab12-cd34ef567890",
  "chatbotId": "5e9c1a2b-3d4e-4f60-b2f2-9f4b1c2d3e4f",
  "userId": "7c2f9d10-4a6b-4c8e-9f1a-2b3c4d5e6f70",
  "organizationId": "11111111-2222-3333-4444-555555555555",
  "createdAt": "2025-10-16T11:44:41.140Z"
}
```

### Error response

```json theme={null}
{
  "message": "Invalid API key"
}
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/chats
openapi: 3.0.0
info:
  title: homie AI API
  description: The homie AI API description
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.yourhomie.ai
    description: Production server
security: []
tags:
  - name: Chat
    description: ''
  - name: Knowledge
    description: Public, CORS-enabled endpoints for PDP question sets
paths:
  /v1/chats:
    post:
      tags:
        - Chat
      summary: Create Chat
      operationId: ChatController_createChat
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatDto'
      security:
        - bearer: []
components:
  schemas:
    CreateChatDto:
      type: object
      properties:
        chatbotId:
          type: string
        userId:
          type: string
      required:
        - chatbotId
    ChatDto:
      type: object
      properties:
        id:
          type: string
        chatbotId:
          type: string
        userId:
          type: string
        organizationId:
          type: string
        createdAt:
          type: string
      required:
        - id
        - chatbotId
        - userId
        - organizationId
        - createdAt
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.