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

# AI Chat

> Interact with the AI assistant programmatically

## Overview

The AI Chat API powers the conversational builder experience. It uses Server-Sent Events (SSE) for streaming responses.

***

## Send Message

<ParamField path="POST" type="/builder/ai/chat">
  Send a message to the AI assistant and receive a streaming response.
</ParamField>

**Request Body**

```json theme={null}
{
  "projectId": "project_abc123",
  "messages": [
    {
      "role": "user",
      "content": "Create a landing page with a hero section"
    }
  ],
  "model": "hiveku-max",
  "mode": "coder"
}
```

**Parameters**

| Parameter   | Type   | Required | Description                                                                                 |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `projectId` | string | Yes      | The project context                                                                         |
| `messages`  | array  | Yes      | Conversation history                                                                        |
| `model`     | string | No       | Model tier: `hiveku-mini`, `hiveku-max`, `hiveku-ultra` (defaults to user's selected model) |
| `mode`      | string | No       | AI mode: `code`, `ask`, `architect`, `debug`, `design`, `test`, `security`, `refactor`      |

**Response (SSE Stream)**

The response is a Server-Sent Events stream:

```
data: {"type": "text", "content": "I'll create a landing page..."}

data: {"type": "tool_call", "name": "createFile", "args": {"path": "src/app/page.tsx"}}

data: {"type": "tool_result", "content": "File created successfully"}

data: {"type": "text", "content": "I've created the landing page with a hero section."}

data: [DONE]
```

### Stream Event Types

| Type          | Description                                     |
| ------------- | ----------------------------------------------- |
| `text`        | AI text response chunk                          |
| `tool_call`   | AI is calling a tool (file edit, deploy, etc.)  |
| `tool_result` | Result of a tool execution                      |
| `reasoning`   | AI reasoning/thinking (when supported by model) |
| `error`       | Error message                                   |
| `[DONE]`      | Stream complete                                 |

***

## Get Chat History

<ParamField path="GET" type="/marketing/ai/chat/history/{sessionId}">
  Retrieve the chat history for a session.
</ParamField>

**Path Parameters**

| Parameter   | Type   | Description         |
| ----------- | ------ | ------------------- |
| `sessionId` | string | The chat session ID |

***

## AI Usage

<ParamField path="GET" type="/ai/usage/user/{userId}">
  Get AI token usage for a specific user.
</ParamField>

**Path Parameters**

| Parameter | Type   | Description   |
| --------- | ------ | ------------- |
| `userId`  | string | The user's ID |

**Response**

```json theme={null}
{
  "totalTokens": 1250000,
  "inputTokens": 450000,
  "outputTokens": 800000,
  "periodStart": "2025-04-01T00:00:00Z",
  "periodEnd": "2025-04-30T23:59:59Z"
}
```