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:
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
string
required
Your app ID (the
gp_ token from your install script).string
required
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.string
required
The current page path, used to record the boot and resolve mounting.
string
A previously issued visitor ID to continue an existing visitor session. Omit it to mint a new one.
boolean
Set when the browser signals Global Privacy Control. GPC opt-out is always honored.
string
A user-agent hint used for bot filtering when the request lacks a
User-Agent header.Response
string | null
The visitor JWT to send as a bearer token on every other endpoint.
number
Token expiry as a Unix timestamp in seconds.
string
The visitor ID for this session. Persist it and replay it on the next boot.
object
The resolved workspace configuration, including the active consent settings.
object
The directive computed for this visitor:
mode, policy_version, reason, region_code, and ai_disclosure.object
The resolved location:
country_code, region_code, and accept_language.object
Runtime feature flags for the session.
boolean
Whether the guide shows the Puntego mark for this workspace.
Chat
POST /chat
The conversation turn. Requires Authorization: Bearer <visitor-jwt>. 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
string
required
The visitor’s message. Must be non-empty.
string
required
A compact, sanitized digest of the current page the guide can act on. Must be non-empty.
string
required
The conversation this turn belongs to. The worker may return an effective ID on the stream if it rotates yours.
number
required
The zero-based index of this turn within the conversation.
string
required
The full URL of the page. Its origin must match the visitor session.
object
Viewport size as
{ width, height, dpr }. Defaults are used when omitted.object
Document size as
{ width, height }. Defaults are used when omitted.number
The current vertical scroll position.
object
Structured browser context (see below). Sanitized by the worker before prompt assembly.
object
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:
object
{ title, url } for the page.object
{ width, height, dpr }.object
{ width, height }.object
{ x, y } scroll offset.string
Text the visitor has selected, when any.
object
The currently focused candidate, in the same shape as a
targets entry.array
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 <visitor-jwt>.
Request
string
required
The visitor the decision applies to.
string
required
The page where the decision was made; its origin must match the visitor session.
string
required
The version of the consent copy the visitor saw.
number
required
When the decision was made, as a Unix timestamp in milliseconds.
string
required
One of
accepted, denied, rejected, dismissed, browser-denied, or gpc_auto_optout.string
The consent mode in effect at decision time.
boolean
Whether Global Privacy Control was active.
string
The policy version recorded with the decision.
object
An explicit region override as
{ country_code, region_code }.string
Where the decision came from:
runtime, gpc, or region_override.Response
boolean
Always
true for a well-formed request.boolean
true when a valid visitor session let the decision be persisted.Voice
Voice is optional per workspace. All three endpoints requireAuthorization: Bearer <visitor-jwt> 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).
string
Optional provider preference:
elevenlabs, openai, openai-batch, mock, or auto (the default).string
The provider token the browser uses to open the realtime session.
string
The provider that issued the token:
elevenlabs, openai, or mock.number
Token expiry as a Unix timestamp.
string
realtime, batch, or mock.string
How to connect:
webrtc, websocket, upload, or mock.number
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.
file
required
The recorded audio blob, sent as a multipart form field.
string
The transcribed visitor speech.
string
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.
string
required
The text to synthesize. Must be non-empty and within the length limit.
string
A specific voice to use. Falls back to the workspace voice when omitted.
string
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
Authentication
How the visitor JWT is minted, scoped, and refreshed.
Errors
The error envelope and what each status code means.
Rate limits
Per-visitor and per-workspace limits and the Retry-After header.
Verified Actions
The customer-approved tools the guide can run.