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

Cloud Options

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

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.",
    },
  },
});

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.

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

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

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 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/.

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

const handler = puckHandler(request, {
  ai: {
    onFinish: ({ totalCost, tokenUsage }) => {
      console.log(`Used ${totalCost} credit`);
    },
  },
});

OnFinish Params

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.

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.

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