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

# Create chat

> Create a new chat session and start building with AI

Creates a new chat session and starts the AI workflow.

## Request

```
POST /api/chat
```

### Headers

| Header          | Required | Description         |
| --------------- | -------- | ------------------- |
| `Authorization` | Yes      | `Bearer macaly_...` |
| `Content-Type`  | Yes      | `application/json`  |

### Body Parameters

| Field                      | Type                                                             | Required | Default     | Description                                          |
| -------------------------- | ---------------------------------------------------------------- | -------- | ----------- | ---------------------------------------------------- |
| `content`                  | string                                                           | Yes      | -           | The user's message/prompt                            |
| `stream`                   | boolean                                                          | No       | `true`      | If `false`, returns JSON instead of stream           |
| `backend`                  | string                                                           | No       | `"DEFAULT"` | Backend to use                                       |
| `executionMode`            | `"auto"` \| `"planning"` \| `"build"`                            | No       | -           | Controls how the AI approaches the task              |
| `model`                    | `"sonnet-4-5"` \| `"sonnet-4-6"` \| `"opus-4-5"` \| `"opus-4-6"` | No       | -           | AI model to use. Defaults to team's configured model |
| `reasoningEffort`          | `"medium"` \| `"high"`                                           | No       | -           | Controls how deeply the AI reasons about the task    |
| `experimental_attachments` | array                                                            | No       | `[]`        | File attachments (see format below)                  |

#### Attachment Format

Each item in the `experimental_attachments` array has the following structure:

| Field         | Type   | Required | Description                     |
| ------------- | ------ | -------- | ------------------------------- |
| `url`         | string | Yes      | URL of the file to attach       |
| `name`        | string | No       | Display name for the attachment |
| `contentType` | string | No       | MIME type of the file           |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.macaly.com/api/chat \
    -H "Authorization: Bearer macaly_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "content": "Create a landing page for a coffee shop",
      "stream": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://www.macaly.com/api/chat', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer macaly_abc123...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content: 'Create a landing page for a coffee shop',
      stream: false,
    }),
  });

  const data = await response.json();
  console.log(data.chatId);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://www.macaly.com/api/chat',
      headers={
          'Authorization': 'Bearer macaly_abc123...',
          'Content-Type': 'application/json',
      },
      json={
          'content': 'Create a landing page for a coffee shop',
          'stream': False,
      },
  )

  data = response.json()
  print(data['chatId'])
  ```
</CodeGroup>

## Response

### JSON Response (when `stream: false`)

```json theme={null}
{
  "chatId": "abc123def456",
  "url": "https://www.macaly.com/chat/abc123def456",
  "streamId": "stream_xyz789",
  "assistantMessageId": "msg_123"
}
```

| Field                | Type                | Description                                                                     |
| -------------------- | ------------------- | ------------------------------------------------------------------------------- |
| `chatId`             | string              | The unique chat identifier                                                      |
| `url`                | string              | Direct URL to view the chat                                                     |
| `streamId`           | string \| undefined | Stream identifier for subscribing. Only present for workflow backends           |
| `assistantMessageId` | string \| undefined | ID of the assistant message being generated. Only present for workflow backends |

### Streaming Response (when `stream: true`, default)

When streaming is enabled, the response is a text stream:

```
2:[{"chatId":"abc123def456"}]
0:"Starting to build..."
...
```

The first line contains the chat ID in the format `2:[{"chatId":"..."}]`.

#### Parsing the Chat ID from Stream

```javascript theme={null}
const text = await response.text();
const match = text.match(/2:\[{"chatId":"([^"]+)"/);
const chatId = match?.[1];
```

## Status Codes

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| 200    | Success - Chat created                           |
| 400    | Invalid request body                             |
| 401    | Invalid or missing API key                       |
| 402    | Insufficient credits                             |
| 403    | Forbidden - No permission for the specified team |
| 422    | Validation error                                 |
| 429    | Rate limited                                     |
| 500    | Server error                                     |

## Next Steps

After creating a chat:

1. **Poll for completion** using [`GET /api/chat/{chatId}/status`](/en/api/get-status)
2. **Subscribe to stream** using [`GET /api/chat/{chatId}/subscribe`](/en/api/subscribe-stream) for real-time updates
3. **Send follow-up messages** using [`POST /api/chat/{chatId}/publish`](/en/api/publish-message)