Rendering

The response never contains HTML. Presentation happens afterwards, in one of three channels that share one renderer:

1. Web component <webknox-answer> from @webknox/elements. It runs in your page and works in any framework.
2. Hosted embed: render.embed_url, an iframe for webviews and no-code tools.
3. Image: render.image_url, an image of the card for chat platforms, email and link previews.

A theme combines a style with layouts:

• The style is design tokens: preset daylight (default), midnight, editorial, playful or mono, plus overrides such as an accent colour.
• The layout is the structure: which fields appear and how they are arranged. Every type has full; most have glance; some have more (see the table above). A layout the card type does not have is ignored: the theme's layout for that type, then the theme's default, then full applies.

A theme bundles both, for example {"style": {"preset": "midnight"}, "layouts": {"weather.forecast": "glance", "*": "full"}}. The element's theme property takes such an object. Besides the preset, style takes three safe options: accent (#rrggbb for highlights, buttons and the first chart colour; the ink on accent-coloured buttons is chosen for contrast, and text in the accent colour is shaded, darker on light styles and lighter on dark ones, until it reads at 4.5:1 on the style's surfaces), corners (0, 4, 10, 18 or 26: the card's radius in CSS pixels) and font (sans, serif, mono or rounded, the bundled families), and raw tokens, which win over the options; the element's accent attribute wins over both. Everywhere a theme is named (the element and render.theme) the built-in themes work by name:

Theme	Style	Layouts
kiosk	midnight	glance for weather, nutrition, quick answers and sun & moon; full otherwise
dashboard	mono	weather as a table, nutrition as a label; full otherwise
magazine	editorial	weather as a headline; full otherwise
kids	playful	weather at a glance, nutrition as macros; full otherwise
status	daylight	weather and audio as a strip; glance otherwise

An explicit layout always beats the theme. Every layout shows its sources, at least behind an info button.

v1 offers WebKnox's layouts only; custom layouts are not part of v1. To go further, override styles through the element's CSS parts and custom properties, or render card.data yourself.

The element ships no fonts. The presets name DM Sans, DM Serif Display, DM Mono and Fredoka with system fallbacks; load them in your page if you want that exact look.

<webknox-answer theme="midnight" layout="glance"></webknox-answer>
<script type="module">
  import '@webknox/elements';
  document.querySelector('webknox-answer').answer = answer; // JSON from your server
</script>

The element emits webknox-follow-up (detail.text) when a follow-up chip is pressed or a quiz answer is confirmed (the text is the option key, e.g. B), and webknox-action (detail.action) when the user starts something such as a timer. Send a follow-up as the next user message.

Focus stays inside the card when a control disappears under it: Start cooking moves focus to the step, a video poster to the player, Show punchline to the punchline. After a follow-up, the card that asked is done; move focus to whatever your page shows next, such as the new answer or the question.

Hosted render

On Pro and Scale, a request can ask for hosted URLs of its answer: render: {theme?, layout?, formats}, where theme is a style preset, a built-in theme or the id of one of your saved themes, and formats lists embed, image or both.

• Only a matched answer with a card gets render; otherwise it is absent and nothing extra is charged. The embed is free; an image adds 1 token, so a matched answer with an image costs 2.
• Saved themes are made in the console's Themes section: a preset with the three safe options and a layout per card type (schemas/theme.schema.json in the contract). Their ids look like th_k2m7x4q6w3np. A render keeps the theme as it was when it was made, so editing or deleting a theme changes no existing embed or image. An id that is not one of your account's themes is a 400 invalid_request. To show a saved theme with the element, copy its definition from the console into the element's theme property.
• The answer (never your question) is stored until render.expires_at, 30 days after the request, and deleted within a day after it. Once it has expired, the URLs answer 410 Gone until it is deleted and 404 Not Found after that.
• On Free and Starter, a request with render is refused with 403 plan_required before it is answered. If the URLs cannot be made, the request fails with 503 unavailable and nothing is charged: you get the URLs or a retryable error, never an answer without them.
• Embed (embed_url): the interactive card, for an iframe on any site. It tells the page around it what happens through postMessage, as {source: "webknox", id, type, …}: type: "follow-up" with text (send it as the next user message), "action" with action, and "resize" with height in CSS pixels. Add ?follow_ups=0 to the URL to hide the follow-up chips when your page doesn't handle them.
• Image (image_url): the card rendered on a 600 px wide page at 2x, so 1200 px wide, with square, opaque corners (chat apps and mail clients frame images themselves). It is a PNG, or a JPEG (.jpg) when the card shows photos, which keeps it small enough for chat apps: typically under 200 KB. It is rendered ahead of time, usually within seconds of the answer; a fetch that comes earlier waits while it renders.

<iframe src="https://embed.webknox.com/v1/…" title="Answer" style="border:0;width:100%"></iframe>
<script>
  addEventListener('message', (event) => {
    if (event.origin !== 'https://embed.webknox.com' || event.data?.source !== 'webknox') return;
    if (event.data.type === 'resize') document.querySelector('iframe').style.height = `${event.data.height}px`;
  });
</script>

Answers never point at a third-party image host. Every image URL (image.url, gallery items[].url, video thumbnail_url, audio artwork_url, movie poster_url) is a WebKnox media URL:

https://webknox.com/media/v1/upload.wikimedia.org/wikipedia/commons/…/Aurora.jpg

Treat it as opaque. A media URL has no query string; the proxy ignores one if you add it. The original page stays in source_url and the credits, for attribution. WebKnox fetches the image from the host named in the path, caches it for a week and serves it with Access-Control-Allow-Origin: * and Cross-Origin-Resource-Policy: cross-origin, so img-src https://webknox.com is the only image rule your Content Security Policy needs.

Served hosts: wikimedia.org, ytimg.com, image.tmdb.org, img.spoonacular.com

A listed domain includes its subdomains. An image on any other host is left out of the answer: the field is null where the schema allows it, a gallery drops the item, and the full layout shows a placeholder. Only JPEG, PNG, WebP, GIF and AVIF up to 8 MB are served; SVG never is. Audio streams (stream_url) and video players stay with their provider and load only after the user presses play, so allow those origins in media-src and frame-src (https://www.youtube-nocookie.com) if you use those cards.