---
title: "Start an AI chat stream"
method: POST
path: "/ai/chat"
tags: ["AI"]
---

# Start an AI chat stream

`POST /ai/chat`

## Request

- Base URL: `https://api.grapesjs.com/v1`
- URL: `https://api.grapesjs.com/v1/ai/chat`
- Auth: HTTP bearer

Starts a streaming AI chat session, used by [AI chat plugin](https://app.grapesjs.com/docs-sdk/plugins/ai/overview).

This endpoint is intended to be used with a short-lived access token created with `/access-tokens` for trusted client-side requests.

The response is a SSE stream in the AI SDK UI message format, consumed directly by the chat transport.

For more information about the AI chat plugin setup refer to this [guide](https://app.grapesjs.com/docs-sdk/plugins/ai/ai-chat#chat-platform-api).

## Request body

- AiChatRequest
  - `id` string, required: Chat session identifier.
  - `messages` AiChatMessage[], required: Recent chat messages sent to the AI model.
  - `projectContext` AiChatProjectContext, required: AI chat project context object forwarded by the client.
  - `settings` AiChatSettings: Optional settings for this chat request.
    - `agentChat` object: Main chat agent settings. Model selection and prompt customization are independent.
      - `modelId` string: ID of an active workspace text model. When omitted, the Studio chat model is used.
      - `prompt` AiChatPromptInstructions: Prompt instructions before and after the built-in prompt. For chat, a supplied preamble replaces the default introductory preamble; the core system prompt remains unchanged.
        - `preamble` string: Instructions placed before the prompt. An empty string removes the default introductory preamble for chat.
        - `postamble` string: Additional instructions placed after the prompt.
    - `agentDev` object: Code agent settings. Supplied system-prompt sections replace the corresponding defaults; omitted sections remain unchanged.
      - `modelId` string: ID of an active workspace text model. When omitted, the Studio code model is used.
      - `prompt` AiDevPromptInstructions: Optional code-agent system-prompt sections. Supplied strings replace individual sections, including Studio-specific defaults. An empty string removes a section. Only sections used by the current operation and project type apply.
        - `preamble` string: Initial task instructions.
        - `postamble` string: Additional instructions appended to the system prompt.
        - `currentCode` string: Current code context.
        - `mainPage` string: Main page context.
        - `design` string: Design instructions.
        - `imageRefs` string: Image reference instructions.
        - `media` string: Media usage instructions.
        - `icons` string: Icon usage instructions.
        - `pageLinking` string: Page linking instructions.
        - `css` string: CSS instructions.
        - `responsiveStyles` string: Responsive styling instructions.
        - `globalStyles` string: Global styling instructions.
        - `plugins` string: Installed plugin instructions.
        - `scripts` string: Script instructions.
        - `output` string: Generated code output instructions.
    - `agentImage` object: Image generation settings. Prompt instructions surround the image prompt without changing reference images.
      - `modelId` string: ID of an active workspace image model. When omitted, the Studio image model is used.
      - `prompt` AiChatPromptInstructions: Prompt instructions before and after the built-in prompt. For chat, a supplied preamble replaces the default introductory preamble; the core system prompt remains unchanged.
        - `preamble` string: Instructions placed before the prompt. An empty string removes the default introductory preamble for chat.
        - `postamble` string: Additional instructions placed after the prompt.

## Response `200`

Streaming response started successfully

## Other responses

- `400`: Invalid request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Server error

---

[API](https://skmtc.dev/grapesjs/apis/studio-platform-api.md) - [All operations](https://skmtc.dev/grapesjs/apis/studio-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/grapesjs/apis/studio-platform-api/revisions/acc4ffe35e2d?raw)