All public endpoints are served from
https://worker.puntego.com. Paths below are relative to that base URL.Authentication
The worker uses a different credential for each boundary:POST /bootuses the public app ID plus a verifiedOriginand mints a short-lived visitor JWT.- Chat, consent, and voice use that JWT as a bearer token.
- Data exports and customer-identity minting use a server-held, scoped programmatic API key.
x-api-key: pk_live_... or the same key as a bearer token. For the full credential, scope, expiry, and refresh behavior, see Authentication.
This page documents the supported public and server-to-server subset of the worker. There is a larger internal surface (ingestion, retrieval, 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. Ordinary app-ID/origin boot does not use 401; an unknown app, disallowed or mismatched origin, bot, or invalid visitor ID is rejected with 403.
A valid app and origin can also receive a capability-restricted 200 privacy-controls-only response when the workspace is not eligible for normal assistant traffic or the global killswitch is active. That response sets features.privacy_controls_only to true: it preserves inspect/Forget access but cannot authorize chat or the normal runtime. This restriction is resolved before optional customer identity proof is consumed.
On a workspace eligible for a full assistant session, an explicitly supplied invalid, expired, or replayed customer_identity_token returns 401. Identity-bound boot fails closed instead of silently creating an anonymous assistant session.
Request
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.A previously issued visitor ID to continue an existing visitor session. Omit it to mint a new one.
A short-lived, one-time token minted by
POST /api/identity/token for an authenticated customer. Pass it only to the initial boot and keep it in memory. On full assistant boot, invalid or replayed proof returns boot/invalid_customer_identity (401); expired proof returns boot/expired_customer_identity (401). Identity failure never falls back to an anonymous assistant session.Response
The directive computed for this visitor:
mode, policy_version, reason, region_code, and ai_disclosure.Runtime feature flags for the session. When
privacy_controls_only is true, the JWT can access only visitor memory/privacy controls; chat and normal runtime routes remain blocked.Whether the answer card shows the “Powered by Puntego” line:
true on Free and Starter, false from Growth up, on the workspace’s current plan.Customer identity token
POST /api/identity/token
Mints a short-lived, one-time identity handoff for the browser SDK’s initial
/boot. This is a server-to-server endpoint: authenticate with an API key
scoped to identity:write, authenticate the customer in your own application
first, and never expose the API key or identity token in HTML, URLs, logs,
cookies, or browser storage. A successful response is 201 with
Cache-Control: private, no-store.
Request
Your stable identifier for the authenticated customer. It is upserted into the workspace’s customer directory and is never inferred from browser input.
Optional customer traits. Values may be strings, finite numbers, booleans,
null, or arrays of those scalar values; nested objects are rejected.Optional account binding as
{ external_id, display_name?, traits? }. Supplying it upserts the account and links the customer to it.Response
The one-time token to hand directly to
loadPuntego or PuntegoProvider in memory. It is consumed only by the initial boot and is never replayed during visitor-JWT refresh.identity/unauthorized (401), a key without
identity:write returns identity/insufficient_scope (403), and an app ID
outside the key’s workspace returns identity/app_not_found (404). Do not
retry the same identity token after an ambiguous boot response: its one-time
nonce may already have been consumed.
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
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.
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.The generated UI block kinds this client can present, for example
["table", "key_value", "callout"] (at most 24 distinct names). The answer’s visual only ever contains these kinds; [] means the client presents no visual and receives none. Names this Worker does not know are ignored. When omitted, the Worker assumes every block kind except "chart". Only a client that lists "chart" receives a chart and a metric tile’s limit, delta and series. When present, each puntego_ui event also carries a receipt for its visual, which ui_history sends back. Add "bound_values" when the client understands values written from the visitor’s data: each such value then also carries a bound object (display, raw, type, source, and unit or currency when it has one), and a visual may use the larger limits for those values. Without it, the same visual arrives with the rendered values only. Add "form_values" when the client can open a form with values already in its fields: a form field may then carry a value, which is what the visitor already wrote for it in the conversation (for a choice, one of its options). Without it, the same form arrives with empty fields.The page annotations this client can draw, from
"region" (an area of one element), "zone" (a dashed outline), "emphasis" (a value or row of data), "caption" (a note beside an element), "sequence" (two to five numbered marks) and "arrow" (from one element to another), at most 16 distinct names. The guide only chooses annotations the client lists and your workspace’s settings allow; names this Worker does not know are ignored. When omitted or [], the guide only points at and rings elements. Every annotation arrives as a visual guide_action (region with its shape, a targeted caption, or a multi_marker with numbered: true or connector: "arrow") and never clicks, types or navigates.Up to two earlier visuals of this conversation, each
{ document, receipt, turn_idx } exactly as the puntego_ui event delivered them, reduced to what they show (no buttons or record links), so a follow-up such as “sort it by seats” can refer to them. The Worker uses only visuals whose receipt it issued to this visitor for this conversation and an earlier turn; anything else is ignored. An earlier visual grounds the answer and never authorizes an action.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:
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.Experience Form submission
POST /api/visitor/experiences/engage
The embed and headless Experience API submit one visible Form branch as a form_response. The request must include the visitor-bound match receipt, immutable deployment and revision IDs, current path, and an idempotency key. value.surveyAnswers contains between 1 and 20 unique, question-attributed answers.
The Worker resolves the deployed Form definition, recalculates conditional steps, scrubs text, and rejects missing visible fields or answers for hidden and unauthored fields. An accepted submission returns submissionReceiptId; an identical idempotent replay returns the same receipt with duplicate: true.
See Conditional and multistep Forms for the authoring schema, limits, branch rules, and example payload.
Visitor action receipts
GET /api/visitor/actions
The visitor’s own durable record of Verified Actions carried out on their behalf. Requires Authorization: Bearer <visitor-jwt>; the session’s tenant, browser visitor, and (customer, account) subject all have to match the execution, so a token can only ever read its own history. Responses are private, no-store.
Newest first, keyset-paginated: pass limit (1–25, default 10) and the opaque cursor from the previous page. Rate limited to 60 requests per minute per visitor.
Response
One receipt per execution:
id, at (ISO-8601), owner-authored label, status (completed, failed, in_progress, needs_review), provider reference when one exists, target_system (the third-party system the confirmation named), and rollback_or_handoff — the owner-authored undo/handoff copy. That copy is text the visitor is shown; this endpoint never reverses anything.needs_review means the provider outcome was ambiguous and the site could not confirm it; the operator-facing reconciliation detail is never returned to the browser.
Consent
POST /consent
Records the visitor’s consent decision together with the region, policy version, and override source. Requires Authorization: Bearer <visitor-jwt>.
Request
Response
Data exports
The export endpoints are server-to-server, available from Growth, and require a programmatic API key with the endpoint’s exact scope. They return newline- delimited JSON (application/x-ndjson) by default. Add ?format=csv for CSV.
All three accept the same query parameters:
Opaque keyset cursor from the prior response’s
x-puntego-next-cursor header. Do not parse or construct it yourself.x-puntego-next-cursor. Follow it until that header is absent. A missing or
invalid key returns export/unauthorized (401), a key without the exact scope
returns export/insufficient_scope (403), and a malformed cursor returns
export/invalid_cursor (400).
Event rows
GET /api/export/events requires events:read and returns:
Aggregate conversation rows
GET /api/export/conversations requires analytics:read. This scope grants
only the aggregate rows below; it does not grant transcript text.
New fields are added after the existing ones (CSV) or as new keys (NDJSON), so
readers by column name or position keep working.
Sampled transcript rows
GET /api/export/transcripts requires the independent
transcripts:read scope. It deterministically includes all turns from 20% of
conversations: the same conversation stays in or out of the sample across runs.
This is an audit sample, not a complete transcript archive.
Every exported text value is capped at 4,000 characters and passed through
the structured pattern scrubber before export. Pattern scrubbing reduces common
email, phone, payment, and identifier exposure but cannot infer every name,
address, or free-form secret; treat this endpoint as sensitive data.
Sampling happens after each raw page is scanned, so a transcript page may
contain fewer rows than
limit — including zero rows — while still returning
x-puntego-next-cursor. Always continue until the cursor header is absent.
Assist API and workspace MCP server
Two more server-side surfaces use the same programmatic keys, from Growth:Authoring API (/api/v1)
Growth and higher workspaces can keep Experiences, audiences, experiments, and
Experience collections in git and promote them from CI. No dashboard session, no
sales call: mint the key yourself in Settings → API keys.
Two scopes, deliberately separate rungs, neither implying the other:
GET reads accept either scope, because a publish-only job still has to fetch a
revision id and a snapshot digest before it can promote anything.
Every mutation is attributed to the credential, not a person: the audit trail
records apikey:<key id>, which no membership lookup can ever resolve. That is
why a key can never satisfy the owner/admin gate on a release-guardian override.
Endpoints
POST /api/v1/experiences, PATCH /api/v1/experiences/:id, and
POST /api/v1/experiences/:id/deployments require an Idempotency-Key header:
a replayed CI job returns the original result with 200 instead of creating a
second Experience, revision, or deployment.
Concurrency and the promotion gate
Authoring writes are optimistically concurrent. Send the value you last read —baseRevisionId on an Experience, expectedVersion on a collection,
expectedRevision on an experiment — and a stale value is refused with 409
rather than clobbering a concurrent edit.
Promotion to production additionally requires the reviewed snapshot digest.
Call the preflight, record its snapshotDigest, and echo it back as
expectedSnapshotDigest on the deploy. The digest is recomputed inside the
deploying transaction, so a promotion that races a change made after review is
refused with experiences/release_snapshot_digest_mismatch (409). Deploys to
development evaluate no snapshot and reject the field.
Live collections need publish
Anactive Experience collection is the one authoring surface a visitor reads
with no revision in between: the resolve path reads its surface and its ordered
items directly. A write-only key is therefore refused item replacement and
surface changes on an active collection with
experience-collections/publish_scope_required (403), and deleting an active
collection is refused with experience-collections/delete_requires_inactive
(409). Pause or draft it with experiences:publish, edit, then re-activate.
Renaming and re-describing a live collection stays on the write rung.
CI workflow
A complete GitHub Actions job: revise the definition held in git, preflight the new revision, record the digest, then promote it.Every request and response shape on this surface — including the audience rule
tree and experiment variant allocation — is in the
OpenAPI document, so a generated client
is a first-class way to adopt this.
Voice
Voice is optional per workspace. Every voice endpoint requiresAuthorization: Bearer <visitor-jwt> and respects the workspace voice cap. Production requires a configured hosted provider; without one, voice fails closed and the widget remains usable as text. The internal mock is limited to development and tests.
Mint a speech token
GET /transcribe-token
Mints the marker for recorded-audio transcription (POST /transcribe). Development and test environments may return a mock token when voice is not configured; production never does. No realtime credential is ever issued to a browser: realtime transcription goes through /stt-stream (Soniox, through the worker) or POST /voice-call (OpenAI). provider=soniox answers 410 with speech-token/soniox_relayed, and provider=openai with speech-token/openai_realtime_moved.
Optional provider preference:
openai-batch, mock, or auto (the default). soniox and openai are no longer minted (410).Seconds reserved against the voice cap at mint time. Realtime sessions reconcile actual elapsed time against this baseline, measured on Puntego’s clock. When the widget’s capture ends it says so once, and the session is settled to its real length, rounded up to the second: a turn shorter than the reserve gives the rest back.
Start a realtime voice call
POST /voice-call
Starts an OpenAI realtime transcription call for the visitor. The body is the browser’s WebRTC SDP offer (content-type: application/sdp, at most 32 KiB). An optional speech_language query parameter (en, es, pt, fr, de or it, the conversation’s language) leads the transcription hint; it never forces a language. Puntego checks the workspace voice switch, the visitor’s AI and voice consent and the voice allowance, creates the call with its own server-held credential, and returns the SDP answer. The provider’s call id and credentials never leave Puntego. Returns 201.
Identifies the call on
/voice-call/renew and /voice-call/end. It only works with the same visitor session token.401, 403 (voice switched off or consent missing), 402 voice/monthly_cap, 413 voice-call/offer_too_large, 415 voice-call/unsupported_media_type, 400 voice-call/invalid_offer, 503 voice-call/not_configured. When the provider refuses the account, the answer is 502 with voice-call/provider_refused; the widget then tries its next provider.
POST /voice-call/renew with { "voice_session_id": "…" } re-checks the same conditions and pays the next lease (200). A refusal ends the call on Puntego’s side before it answers (402, 403, or 409 voice-call/no_active_call). POST /voice-call/end with the same body ends the call and bills its measured length; ending an unknown call is a no-op. Withdrawing voice consent, or the workspace turning voice off, ends live calls without any action from the browser. A call whose browser stops renewing is ended by Puntego within about a minute and a half and metered until Puntego ended it.
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.
Optional form field: the conversation’s language (
en, es, pt, fr, de or it). It leads the transcription hint and never forces a language.Synthesize speech
POST /tts
Synthesizes speech with ElevenLabs eleven_v4_turbo and streams the audio back as MP3 (audio/mpeg). ElevenLabs is the only text-to-speech provider; failures return an error instead of switching models or vendors. Successful responses include x-puntego-tts-provider: elevenlabs. The embed speaks replies through the streaming socket below and uses this endpoint as its fallback.
An ElevenLabs voice id (20 letters and digits). A voice UUID saved before the move to ElevenLabs is accepted and uses the workspace voice; any other invalid explicit value returns
400. The workspace voice is used when this field is omitted.The conversation’s language (en, es, pt, fr, de or it). Phone numbers, emails, web addresses, prices, percentages and dates in
text are said in words in this language, and the workspace’s pronunciations for it apply. Only what is spoken changes.429 with error tts/workspace_busy or tts/provider_busy and a short Retry-After; nothing is charged.
Stream a spoken reply
GET /tts-stream (WebSocket)
The embed’s streaming speech socket: one connection per spoken reply. The client sends the reply’s text as it is written and receives raw audio (16-bit little-endian mono PCM at 24 kHz, as binary frames) plus per-character timing, so speech starts with the first sentence and sentences join without gaps. A browser WebSocket cannot send headers, so the visitor token is offered as a second subprotocol: Sec-WebSocket-Protocol: puntego-tts.v1, puntego-auth.<visitor JWT>; the server answers puntego-tts.v1. A missing or invalid token is refused with 401 before any socket opens.
Client messages (JSON text frames):
{"type":"start","language":"es","voice_id":"…"}— first message.language(en, es, pt, fr, de, it) andvoice_idare optional;page_language(the page’s language) only chooses how values are said in words until the conversation has a language.{"type":"text","seq":0,"text":"…"}— a sentence of the reply, in order (seqincreases); at most 2,000 characters each and 8,000 per reply.{"type":"end"}— the reply’s text is complete.
ready (with sample_rate and encoding), binary PCM frames, alignment (seq, chars, start_ms, duration_ms; times from the start of the reply’s audio, always in the sentence’s own words: values said in words, pronunciations and expression cues never appear in it), segment_end (seq), done, and error (error carries the same codes as the HTTP routes, such as voice/disabled, voice/voice_consent_required or voice/monthly_cap) followed by a close (4003 refused, 4011 provider failure, 4400 protocol error, 4408 expired, 4429 busy: tts/workspace_busy or tts/provider_busy, worth retrying after a moment). Closing the socket stops the synthesis; voice seconds are charged for the audio actually delivered.
Stream speech recognition
GET /stt-stream (WebSocket)
The embed’s speech-recognition socket: the visitor’s microphone streams to the worker, which transcribes it with Soniox stt-rt-v5 using its own credentials (the browser never holds a provider key) and streams the transcript back. One connection per capture, or per hands-free conversation (kept between turns). As for /tts-stream, the visitor token is offered as a second subprotocol: Sec-WebSocket-Protocol: puntego-stt.v1, puntego-auth.<visitor JWT>; the server answers puntego-stt.v1. A missing or invalid token is refused with 401 before any socket opens.
Client messages: {"type":"start","sample_rate":16000,"language_hints":["es","en"],"endpointing":true} first (sample_rate is 16000, 24000, 44100 or 48000; up to six two-letter hints, most likely first, never restrictive; endpointing closes utterances on the provider’s own end-of-turn detection); then binary frames of 16-bit little-endian mono PCM at that rate, and {"type":"finalize"}, {"type":"keepalive"}, {"type":"pause"}, {"type":"resume"} and {"type":"end"} as JSON text frames.
Server messages: {"type":"ready","session_max_seconds":600} once the session is open; then the provider’s transcript messages as they are (tokens, each {"text","is_final"}, with <end> and <fin> markers; finished after end); and error (error carries the voice routes’ codes, such as voice/disabled, voice/voice_consent_required or voice/monthly_cap, or the socket’s own: stt/provider_account with the provider’s status, stt/provider_failed, stt/unavailable, stt/workspace_openai_exclusive, stt/session_expired) followed by a close (4003 refused, 4011 provider failure, 4400 protocol error, 4408 expired). Voice seconds are charged for the time the session listened, measured by the worker; time between pause and resume is not charged.
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.