API ReferenceAICloud Clientchat

chat

Create a chat stream between the AI plugin and the Puck Cloud, and intercept chat requests made by the plugin.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      context: "We are Google",
    },
  });
}

Returns a Response object.

Args

Param	Example	Type	Status
`chatParams`	`{ config: {}, pageData: {} }`	ChatParams	Required
`cloudOptions`	`{ ai: {} }`	CloudOptions	-

Chat Params

Param	Example	Type	Status
`config`	`{ components: {} }`	Config	Required
`pageData`	`{ root: {}, content: [] }`	Data	Required
`messages`	`[]`	UIMessage[]	Required

`config`

The Puck config for the page. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    config: {
      components: {
        HeadingBlock: {
          fields: {
            title: { type: "text" },
          },
          render: ({ title }) => <h1>{title}</h1>,
        },
      },
    },
  });
}

`pageData`

The current page data. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    pageData: {
      root: { props: { title: "My page" } },
      content: [],
    },
  });
}

`messages`

The entire message history for the chat, as an array of AI SDK UIMessages. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    messages: [
      {
        id: "message-id",
        role: "user",
        parts: [{ text: "Create a landing page about dogs" }],
      },
    ],
  });
}

Cloud Options

Param	Example	Type	Status
`ai.context`	`"We are Google"`	String	-
`ai.designMode`	`{ allowed: true }`	DesignModeOptions	-
`ai.mode`	`"design"`	`"assembly" \| "design"`	-
`ai.model`	`"openai/gpt-5.5"`	String	-
`ai.onFinish`	`({ totalCost }) => {}`	Function	-
`ai.providerApiKey`	`"SECRET"`	String	-
`ai.providerOptions`	`{ openai: {} }`	Object	-
`ai.tools`	`{}`	Object	-
`apiKey`	`"SECRET"`	String	-
`host`	`"https://www.example.com/api/"`	String	-

`ai.context`

Provide system context and instructions to the agent.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      context: "We are Google. Your job is to create Google landing pages.",
    },
  });
}

`ai.designMode`

Configure design mode to let Puck AI generate new components.

DesignModeOptions

Param	Example	Type	Default	Description
`allowed`	`true`	Boolean	`false`	Whether design mode is available for this request
`instructions`	`"..."`	String	-	Custom instructions injected into the design mode prompt
`model`	`"openai/gpt-5.6-sol"`	String	`"openai/gpt-5.6-luna"`	Model override for design-mode requests
`providerOptions`	`{ openai: {} }`	Object	-	providerOptions override for design-mode requests
`scripts`	`true`	Boolean	`false`	Set to `true` to allow generated components to include scripts

`allowed`

Allow design mode.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      designMode: { allowed: true },
    },
  });
}

Once allowed, design mode will be enabled when ai.mode is design or the user has toggled it via the chat interface.

`instructions`

Provide additional instructions for the agent to follow when designing components, such as brand guidelines or layout constraints.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      designMode: {
        allowed: true,
        instructions:
          "Always use our brand font: Inter. Primary color: #4285F4.",
      },
    },
  });
}

`model`

Select the model for design-mode requests. Defaults to openai/gpt-5.6-luna, or ai.model when set. See model configuration for available models.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      designMode: {
        allowed: true,
        model: "openai/gpt-5.6-sol",
      },
    },
  });
}

`providerOptions`

Fine-tune the model call for design-mode requests. Supports the same options as ai.providerOptions, which it overrides in design mode.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      designMode: {
        allowed: true,
        providerOptions: {
          openai: { reasoningEffort: "high" },
        },
      },
    },
  });
}

`scripts`

Set to true to allow the agent to include client-side script fields in designed components.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      designMode: {
        allowed: true,
        scripts: true,
      },
    },
  });
}

`ai.mode`

Set the mode used for generating the page. Can be:

"assembly" (default) - generate pages based on the provided components
"design" - design new components, incorporating existing components where possible

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      mode: "design",
      designMode: { allowed: true }, // required to allow the "design" mode
    },
  });
}

`ai.model`

Select the model to use. By default, Puck selects a model based on the request mode: openai/gpt-5.4-mini for assembly and openai/gpt-5.6-luna for design.

We currently support Open AI models, which should be prefixed with openai/.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      model: "openai/gpt-5.5",
    },
  });
}

Without a providerApiKey, the request uses Puck AI credits and the model must be one of the supported models. Provide a key to run any OpenAI model on your own provider account.

Use designMode.model to override the model for design-mode requests.

`ai.onFinish`

A callback triggered when the request is complete. Provides usage information.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      onFinish: ({ totalCost, tokenUsage }) => {
        console.log(`Used ${totalCost} credit`);
      },
    },
  });
}

OnFinish Params

Param	Example	Type
`totalCost`	`0.2`	number
`tokenUsage`	`{}`	Object

`totalCost`

A number representing the total cost of the request.

`tokenUsage`

An object containing a breakdown of token consumption:

inputTokens
outputTokens
totalTokens
reasoningTokens
cachedInputTokens
cacheWriteTokens

`ai.providerApiKey`

Set the API key for the provider named in ai.model to run Puck AI on your own provider account. Will use the OPENAI_API_KEY environment variable by default.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      model: "openai/gpt-4.1",
      providerApiKey: process.env.MY_OPENAI_KEY,
    },
  });
}

`ai.providerOptions`

Pass configuration options through to the model call.

Param	Example	Type
`openai.reasoningEffort`	`"low"`	`"none" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh"`
`openai.serviceTier`	`"priority"`	`"auto" \| "default" \| "flex" \| "priority"`
`openai.textVerbosity`	`"low"`	`"low" \| "medium" \| "high"`

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      providerOptions: {
        openai: {
          serviceTier: "priority", // Enable faster responses
        },
      },
    },
  });
}

Use designMode.providerOptions to override these options for design-mode requests.

`ai.tools`

Define tools that enable the agent to execute functions on your server and retrieve data. The result of the tool will be factored into the request.

import { chat, tool } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      tools: {
        getProducts: tool({
          description: "Get a list of product codes",
          inputSchema: z.object(),
          execute: async () => {
            return [
              {
                name: "Google Maps",
                product_code: "maps",
              },
              {
                name: "Google Calendar",
                product_code: "calendar",
              },
            ];
          },
        }),
      },
    },
  });
}

`apiKey`

Set your API key. Will use the PUCK_API_KEY environment variable by default.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    apiKey: process.env.MY_PUCK_KEY,
  });
}

`host`

Set a custom Puck Cloud host.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    host: "https://www.example.com/api",
  });
}

Installation

generate