> ## Documentation Index > Fetch the complete documentation index at: https://docs.puntego.com/llms.txt > Use this file to discover all available pages before exploring further. # API reference > Request and response fields for the public worker endpoints: boot, chat, browser capture context, consent, and voice. The public worker surface is small on purpose. Your install script and the SDK call it for you, but the request and response shapes are documented here so you can debug traffic, build server-to-server tooling, or reason about what the guide sends. All public endpoints are served from `https://worker.puntego.com`. Paths below are relative to that base URL. ## Authentication `POST /boot` is the only unauthenticated endpoint. It mints a short-lived visitor JWT (roughly a 15-minute TTL) that every other public endpoint requires as a bearer token: ```http theme={null} Authorization: Bearer ``` For the full token flow, expiry, and refresh behavior, see [Authentication](/authentication). This page documents the public subset of the worker. There is a larger internal surface (ingestion, retrieval, events, billing, and dashboard APIs) that is not exhaustively listed here. ## Boot `POST /boot` Resolves the workspace configuration, the consent directive for the visitor's region, and a fresh visitor JWT. No `Authorization` header is required — this is where the token is issued. Returns `503` when the global killswitch is on, and never returns `401`. ### Request Your app ID (the `gp_` token from your install script). The page origin requesting boot. It must match the request `Origin` header and an allowed domain for the app, or boot is refused with a `403`. The current page path, used to record the boot and resolve mounting. A previously issued visitor ID to continue an existing visitor session. Omit it to mint a new one. Set when the browser signals Global Privacy Control. GPC opt-out is always honored. A user-agent hint used for bot filtering when the request lacks a `User-Agent` header. ### Response The visitor JWT to send as a bearer token on every other endpoint. Token expiry as a Unix timestamp in seconds. The visitor ID for this session. Persist it and replay it on the next boot. The resolved workspace configuration, including the active consent settings. The directive computed for this visitor: `mode`, `policy_version`, `reason`, `region_code`, and `ai_disclosure`. The resolved location: `country_code`, `region_code`, and `accept_language`. Runtime feature flags for the session. Whether the guide shows the Puntego mark for this workspace. ## Chat `POST /chat` The conversation turn. Requires `Authorization: Bearer `. It enforces visitor and workspace rate limits (returning `429` with a `Retry-After` header when exceeded), and when a production rollout list is configured, only enabled workspaces are served. The response is a Server-Sent Events stream (`Content-Type: text/event-stream`). It streams the assistant's answer in chunks, interleaved with structured metadata events (such as proposed guide actions, citations, and suggested next steps). ### Request The visitor's message. Must be non-empty. A compact, sanitized digest of the current page the guide can act on. Must be non-empty. The conversation this turn belongs to. The worker may return an effective ID on the stream if it rotates yours. The zero-based index of this turn within the conversation. The full URL of the page. Its origin must match the visitor session. Viewport size as `{ width, height, dpr }`. Defaults are used when omitted. Document size as `{ width, height }`. Defaults are used when omitted. The current vertical scroll position. Structured browser context (see below). Sanitized by the worker before prompt assembly. An optional JPEG capture of the viewport as `{ data, mime, width, height }`, where `data` is raw base64 and `mime` is `image/jpeg`. Oversized or malformed captures are dropped. ### Browser capture context When present, `capture_context` gives the guide structured web context without granting any arbitrary browser control — the worker sanitizes it before it reaches the model. It carries: `{ title, url }` for the page. `{ width, height, dpr }`. `{ width, height }`. `{ x, y }` scroll offset. Text the visitor has selected, when any. The currently focused candidate, in the same shape as a `targets` entry. Ranked DOM-backed candidates the guide can point at, each with a selector, a stable `gp_id`, viewport and document bounding boxes, a confidence score, and accessibility hints. ## Consent `POST /consent` Records the visitor's consent decision together with the region, policy version, and override source. Requires `Authorization: Bearer `. ### Request The visitor the decision applies to. The page where the decision was made; its origin must match the visitor session. The version of the consent copy the visitor saw. When the decision was made, as a Unix timestamp in milliseconds. One of `accepted`, `denied`, `rejected`, `dismissed`, `browser-denied`, or `gpc_auto_optout`. The consent mode in effect at decision time. Whether Global Privacy Control was active. The policy version recorded with the decision. An explicit region override as `{ country_code, region_code }`. Where the decision came from: `runtime`, `gpc`, or `region_override`. ### Response Always `true` for a well-formed request. `true` when a valid visitor session let the decision be persisted. ## Voice Voice is optional per workspace. All three endpoints require `Authorization: Bearer ` and respect the workspace voice cap. When voice provider credentials are absent, the worker falls back to an internal mock voice. ### Mint a speech token `GET /transcribe-token` Mints a visitor-scoped realtime speech token (or a mock token when voice is not configured). Optional provider preference: `elevenlabs`, `openai`, `openai-batch`, `mock`, or `auto` (the default). The provider token the browser uses to open the realtime session. The provider that issued the token: `elevenlabs`, `openai`, or `mock`. Token expiry as a Unix timestamp. `realtime`, `batch`, or `mock`. How to connect: `webrtc`, `websocket`, `upload`, or `mock`. Seconds reserved against the voice cap at mint time. Realtime sessions reconcile actual elapsed time against this baseline. ### Transcribe audio `POST /transcribe` Accepts browser-recorded audio as `multipart/form-data` and returns a transcript. Returns `503` when transcription is not configured and `413` when the audio exceeds the size limit. The recorded audio blob, sent as a multipart form field. The transcribed visitor speech. The transcription model that produced the text. ### Synthesize speech `POST /tts` Synthesizes speech from text and streams the audio back. The response body is the audio stream; the served provider is reported in the `x-puntego-tts-provider` response header. The text to synthesize. Must be non-empty and within the length limit. A specific voice to use. Falls back to the workspace voice when omitted. Provider preference: `elevenlabs`, `openai`, `cartesia`, `mock`, or `auto` (the default). ## Dashboard APIs The dashboard's workspace APIs (under `/api/tenants/:tenantId/`) are not part of this public bearer-token surface. They are protected by session cookies and are organization-scoped, so middleware blocks cross-workspace access. Use the dashboard UI for these; they are not intended for direct integration. ## Next steps How the visitor JWT is minted, scoped, and refreshed. The error envelope and what each status code means. Per-visitor and per-workspace limits and the Retry-After header. The customer-approved tools the guide can run.