Docs

Preview Endpoint

A token-authenticated endpoint called by the floating approval panel when the publisher approves or requests regeneration of an ad template.

POST/api/preview/approve

Overview

The preview endpoint is called by the floating approval panel injected into the publisher's own site during live-site preview mode. It does not require session authentication — the previewToken (a CUID with ~128 bits of entropy) serves as the bearer credential for the specific placement it belongs to.

Approving a template

To mark a placement's template as approved and begin serving real ads:

Request body

{
  "previewToken": "clp_abc123def456..."
}

Response

{
  "ok": true,
  "placementId": "clp_xyz789..."
}

On success, Inlay sets templateApproved = true on the placement. Ad serving begins on the next matching page impression.

Idempotent

Calling this endpoint multiple times with the same token when already approved is a no-op — it will not error or change state.

Regenerating a template

To clear the current template and request a new AI generation pass:

Request body

{
  "previewToken": "clp_abc123def456...",
  "regenerate": true,
  "feedback": "Use a smaller font. Remove the border. Match the card style exactly."
}

Response

{
  "ok": true,
  "placementId": "clp_xyz789..."
}

On regeneration, Inlay:

Saves the current template HTML to previousAdComponentHtml
Saves the feedback text to regenerateFeedback
Clears adComponentHtml, adPlacement, templateApproved, and firstVisitPageUrl
The next real visitor to a matching page triggers a fresh generation pass, with the previous template and feedback passed to the AI

Request body fields

Field	Type	Description
previewToken	string	Required. The placement's unique preview token.
regenerate	boolean	Optional. If true, clears the template and schedules regeneration. Defaults to false.
feedback	string?	Optional. Human-readable feedback for the AI. Only used when regenerate: true.

Error responses

Status	Body	Cause
400	{ "ok": false, "error": "previewToken required" }	previewToken not provided or not a string
404	{ "ok": false, "error": "Not found" }	No placement with the given previewToken exists
422	{ "ok": false, "error": "No template to approve" }	Approve called but adComponentHtml is null
500	{ "ok": false, "error": "Internal error" }	Unexpected server error

Security

The endpoint has no session authentication. It is intentionally designed to be callable from the publisher's own site without requiring the publisher to be logged in. Security is provided by the previewToken itself — a CUID value with approximately 128 bits of entropy, making brute-force guessing computationally infeasible.

The endpoint has wide-open CORS (Access-Control-Allow-Origin: *) to allow cross-origin requests from the publisher's domain.

Keep previewTokens private

Although preview tokens are long and random, they grant the ability to approve or clear a placement's template. Do not share the preview URL with untrusted parties.

Serve Endpoint Plans & Limits