API ReferenceAICloud ClientpuckHandler

puckHandler

Handle all endpoints for the /api/puck/* path (used by the AI plugin) and fine-tune behavior.

// app/api/puck/[...all]/route.ts

import { puckHandler } from "@puckeditor/cloud-client";

const handleRequest = (request) => {
  return puckHandler(request, {
    ai: {
      context: "We are Google. You create Google landing pages.",
    },
  });
};

export const DELETE = handleRequest;
export const GET = handleRequest;
export const POST = handleRequest;

Args

Param	Example	Type	Status
`request`	`new Request()`	Request	Required
`cloudOptions`	`{ ai: {} }`	CloudOptions	-

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-4.1"`	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.

const handler = puckHandler(request, {
  ai: {
    context: "We are Google. You 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 handler
`instructions`	`"..."`	String	-	Custom instructions injected into the design mode prompt
`scripts`	`true`	Boolean	`false`	Set to `true` to allow generated components to include scripts

`allowed`

Allow design mode.

import { puckHandler } from "@puckeditor/cloud-client";
 
const handler = puckHandler(request, {
  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.

const handler = puckHandler(request, {
  ai: {
    designMode: {
      allowed: true,
      instructions: "Always use our brand font: Inter. Primary color: #4285F4.",
    },
  },
});

`scripts`

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

const handler = puckHandler(request, {
  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

const handler = puckHandler(request, {
  ai: {
    mode: "design",
    designMode: { allowed: true }, // required to allow the "design" mode
  },
});

`ai.model`

Select the model to use. By default, Puck will use a managed model.

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

const handler = puckHandler(request, {
  ai: {
    model: "openai/gpt-4.1",
    providerApiKey: process.env.MY_OPENAI_KEY,
  },
});

When providing your own model, you must provide a providerApiKey.

`ai.onFinish`

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

const handler = puckHandler(request, {
  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

`ai.providerApiKey`

Set the API key for the provider named in ai.model. Will use the OPENAI_API_KEY environment variable by default.

const handler = puckHandler(request, {
  ai: {
    model: "openai/gpt-4.1",
    providerApiKey: process.env.MY_OPENAI_KEY,
  },
});

`ai.providerOptions`

Pass configuration options through to the model call when using ai.model.

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

const handler = puckHandler(request, {
  ai: {
    model: "openai/gpt-4.1",
    providerApiKey: process.env.MY_OPENAI_KEY,
    providerOptions: {
      openai: {
        serviceTier: "priority", // Enable faster responses
      },
    },
  },
});

`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 { tool } from "@puckeditor/cloud-client";
 
const handler = puckHandler(request, {
  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.

const handler = puckHandler(request, {
  apiKey: process.env.MY_PUCK_KEY,
});

`host`

Set a custom Puck Cloud host.

const handler = puckHandler(request, {
  host: "https://www.example.com/api",
});

generate

tool