Skip to main content
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.
The versioned, machine-readable OpenAPI 3.1 contract is available at https://puntego.com/openapi/v1.json. It covers this supported public boundary only; dashboard session APIs remain intentionally private.

Authentication

The worker uses a different credential for each boundary:
  • POST /boot uses the public app ID plus a verified Origin and 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.
Visitor-authenticated requests send:
Programmatic requests send 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

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.
string
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.
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.
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. When privacy_controls_only is true, the JWT can access only visitor memory/privacy controls; chat and normal runtime routes remain blocked.
boolean
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

string
required
The gp_ app ID that belongs to the API key’s workspace.
string
required
Your stable identifier for the authenticated customer. It is upserted into the workspace’s customer directory and is never inferred from browser input.
object
Optional customer traits. Values may be strings, finite numbers, booleans, null, or arrays of those scalar values; nested objects are rejected.
object
Optional account binding as { external_id, display_name?, traits? }. Supplying it upserts the account and links the customer to it.
number
Token lifetime from 30 to 300 seconds. Defaults to 120 seconds.

Response

string
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.
string
ISO-8601 expiry for the one-time token.
object
The workspace-scoped customer record created or updated by this mint.
object
The linked account record when account was present in the request.
An absent or invalid key returns 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

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.
string[]
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.
string[]
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.
object[]
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:
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.

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

array
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.
string
Opaque forward cursor, or null on the last page.
Proposals, policy blocks, and declined confirmations are not listed: nothing reached a provider, so they are not “what was done on your behalf”. 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. 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.

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:
number
Page size from 1 to 1,000. Invalid or omitted values use 100.
string
Opaque keyset cursor from the prior response’s x-puntego-next-cursor header. Do not parse or construct it yourself.
string
ndjson (default) or csv.
When another page exists, the response includes 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

An active 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.
Hold the two keys as separate secrets. The revise step cannot deploy and the deploy step cannot author, so neither leaked secret is enough to put unreviewed content in front of a visitor.
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 requires Authorization: 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.
string
Optional provider preference: openai-batch, mock, or auto (the default). soniox and openai are no longer minted (410).
string
The provider token the browser uses to open the realtime session.
string
The provider that issued the token: soniox, openai, or mock.
number
Token expiry as a Unix timestamp.
string
realtime, batch, or mock.
string
How to connect: websocket, upload, or mock.
number
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.
string
The SDP answer to apply with setRemoteDescription.
string
Identifies the call on /voice-call/renew and /voice-call/end. It only works with the same visitor session token.
number
Seconds already paid for. Puntego hangs the call up unless it is renewed.
number
How often to renew while the microphone is live.
Refusals: 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.
file
required
The recorded audio blob, sent as a multipart form field.
string
Optional form field: the conversation’s language (en, es, pt, fr, de or it). It leads the transcription hint and never forces a language.
string
The transcribed visitor speech.
string
The transcription model that produced the text.

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.
string
required
The text to synthesize. Must be non-empty and within the length limit.
string
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.
string
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.
When speech is busy (the workspace’s share of voice sessions, or the provider’s, is in use) the answer is 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) and voice_id are 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 (seq increases); at most 2,000 characters each and 8,000 per reply.
  • {"type":"end"} — the reply’s text is complete.
Server messages: 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.