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

POST · /builder/ai/chat

Send a message to the AI assistant and receive a streaming response.

Request Body

{
  "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

GET · /marketing/ai/chat/history/{sessionId}

Retrieve the chat history for a session.

Path Parameters

Parameter	Type	Description
sessionId	string	The chat session ID

---

AI Usage

GET · /ai/usage/user/{userId}

Get AI token usage for a specific user.

Path Parameters

Parameter	Type	Description
userId	string	The user’s ID

Response

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