puckHandler
Handle all endpoints for the /api/puck/* path (used by Cloud Plugins) and fine-tune behavior.
// app/api/puck/[...all]/route.ts
import { puckHandler } from "@puckeditor/cloud-client";
const handleRequest = (request) => {
// TODO: authenticate this endpoint
return puckHandler(request);
};
export const DELETE = handleRequest;
export const GET = handleRequest;
export const POST = handleRequest;Args
| Param | Example | Type | Status |
|---|---|---|---|
request | new Request() | Request | Required |
cloudOptions | { ai: {} } | Object | - |
request
The incoming request for an /api/puck/* route.
cloudOptions
| Param | Example | Type | Status |
|---|---|---|---|
ai.context | "We are Google" | String | - |
ai.designMode | { allowed: true } | DesignModeOptions | - |
ai.maxIterations | 3 | Number | - |
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 | - |
auth | { tenantId: "team-1" } | Object | - |
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 the user can select design mode |
instructions | "..." | String | - | Custom instructions injected into the design mode prompt |
model | "openai/gpt-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 users to select design mode from the chat interface. This is not required when ai.mode is set to "design".
import { puckHandler } from "@puckeditor/cloud-client";
const handler = puckHandler(request, {
ai: {
designMode: { allowed: true },
},
});Once allowed, design mode will be enabled when 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-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.maxIterations
How many times the agent can iterate. Capped at 50.
const handler = puckHandler(request, {
ai: {
maxIterations: 2, // review the first write, then stop
},
});See generate’s maxIterations.
ai.mode
Force the mode used for every request. 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",
},
});ai.model
Select the model to use. By default, Puck uses openai/gpt-5.6-luna in both assembly and design modes. See model configuration for supported models.
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
| 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.
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.
| 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: {
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,
});auth
Provides authentication and identity configuration.
auth.tenantId
Isolate Puck Cloud resources to a single tenant, such as one of your customers. Defaults to a shared, global tenant.
const handler = puckHandler(request, {
auth: {
tenantId: user.teamId,
},
});The ID is case-sensitive and must be less than 255 characters.
auth.identity
Record an identity against Puck Cloud resources, allowing for access control in the future.
Accepts:
id(required): a unique ID for the user. Case-sensitive and must be less than 255 characters.name(optional): a name shown in Puck UI to identify the user- …: any other identity metadata you want to store
const handler = puckHandler(request, {
auth: {
identity: { id: user.id, name: user.name },
},
});auth.provider
Set to "puck" to use managed Puck Auth. Automatically configures the identity.
const handler = puckHandler(request, {
auth: {
provider: "puck",
},
});auth.access (coming soon)
Implement access control based on your user’s identity. Coming soon.
host
Set a custom Puck Cloud host.
const handler = puckHandler(request, {
host: "https://www.example.com/api",
});