{"openapi":"3.1.0","info":{"title":"Brightshoal API","version":"1.0.0"},"servers":[{"url":"https://api.brightshoal.com"}],"tags":[{"name":"Assistants","description":"An assistant is one agent: its instructions, model, voice, tools and channels. Every call and chat runs on an assistant, and every update creates a new version."},{"name":"Knowledge","description":"Knowledge bases hold the pages, documents and text an assistant answers from. Sources are revised, approved and published as immutable publications, then attached to assistants."},{"name":"Phone numbers","description":"Search, buy or import numbers, then attach an assistant so it answers inbound calls on that number."},{"name":"Calls","description":"Place outbound phone calls, start browser calls, and read every call back with its transcript, costs, recordings and analysis."},{"name":"Publishable keys","description":"Publishable keys (`pk_live_...`) let a browser start web chats with one assistant from the origins you allow. They are safe to ship in page source; secret API keys are not."},{"name":"Public chat API","description":"The versioned API for your own chat interface, in a page or an app: start a conversation with a publishable key, then send messages with the conversation token it returns. It runs the same conversations as the chat widget."},{"name":"WhatsApp","description":"Connect a WhatsApp Business Account from Meta and assign its numbers to assistants."},{"name":"Provider credentials","description":"Bring your own provider accounts (model, voice and telephony providers). Secrets are encrypted at rest and never returned."},{"name":"Voices and models","description":"Discover the voices and models a provider offers, and the registry of everything an assistant can be configured with."},{"name":"Conversations","description":"Web chat conversations with their messages, costs and lead. Your team can take one over, reply as a person and hand it back to the assistant."},{"name":"Forms","description":"Forms on your own site that post to Brightshoal: their fields, keys and approved sites, the submissions they receive, and submissions your server sends itself."},{"name":"Leads","description":"The details an assistant captured from a visitor, and the outcome you report back once your team follows up."},{"name":"Webhooks","description":"Subscribe an HTTPS endpoint to events (calls ending, messages, leads) and inspect every delivery attempt."},{"name":"Call analytics","description":"Call volume and latency over a time range, per project or assistant."},{"name":"Chat analytics","description":"Web chat health, quality, the visitor funnel, trends and incidents, with notification subscriptions."},{"name":"Alerts","description":"Rules that notify you when a metric crosses a threshold."},{"name":"Audit log","description":"Who changed what in your organization, newest first."},{"name":"Projects","description":"Projects group assistants, numbers and keys inside an organization."},{"name":"Members","description":"The people in your organization and their roles."}],"paths":{"/api/assistants":{"post":{"tags":["Assistants"],"summary":"Create an assistant","description":"Creates an assistant at version 1. `config` needs `agent.instructions` and `session.llm`, `session.stt` and `session.tts`, each with a `provider` and `model` from the registry; everything else has a default. An org-wide key must name `project_id`. Validation checks the shape, not that the provider account works: place a sandbox call or chat to be sure.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantCreate"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Assistant"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-assistants","security":[{"apiKey":[]}]},"get":{"tags":["Assistants"],"summary":"List assistants","description":"Every assistant in scope with its full current configuration. Secrets in the config come back as `<key>_set` flags. Archived assistants are left out unless `archived=true`.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's assistants."},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"`true`: only archived assistants. Absent: only live ones."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Assistant"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-assistants","security":[{"apiKey":[]}]}},"/api/assistants/{id}":{"get":{"tags":["Assistants"],"summary":"Get an assistant and its effective business settings","description":"One assistant with its stored configuration and version, archived or not. effective_hours, effective_timezone and effective_team_phone report the runtime values and their assistant/business source, resolved from the current business site profile without copying into config.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Assistant"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"get-assistants-id","security":[{"apiKey":[]}]},"patch":{"tags":["Assistants"],"summary":"Update an assistant","description":"Send `name`, `config` or both. A `config` replaces the whole stored configuration (it is not merged), except that omitted secrets and tool request specs are kept: read the assistant, change what you need and send the full config back. Each update bumps `version`. An archived assistant cannot be changed (409 `assistant_archived`): restore it first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Assistant"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"patch-assistants-id","security":[{"apiKey":[]}]},"delete":{"tags":["Assistants"],"summary":"Delete an archived assistant permanently","description":"Only an archived assistant can be deleted: 409 `not_archived` otherwise. Its versions, knowledge base links, assistant-bound widget keys (preview links) and GA4 delivery status are deleted; phone and WhatsApp numbers bound to it are left without an assistant. Its past calls, conversations and leads stay readable. Cannot be undone.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeleteResult"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_archived`: archive the assistant first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"delete-assistants-id","security":[{"apiKey":[]}]}},"/api/assistants/{id}/archive":{"post":{"tags":["Assistants"],"summary":"Archive an assistant","description":"Its widget, chats and calls stop at once: widget keys answer 404 for it, open chats get no more replies, WhatsApp numbers stop answering, and phone numbers reject calls; numbers and keys keep their binding. Nothing is deleted, edits are refused with 409 `assistant_archived`, and it leaves the assistants list. Archiving an archived assistant is a no-op. Needs the admin role; audited as `assistant.archived`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Assistant"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"post-assistants-id-archive","security":[{"apiKey":[]}]}},"/api/assistants/{id}/restore":{"post":{"tags":["Assistants"],"summary":"Restore an archived assistant","description":"Its widget keys, numbers and chats serve it again. Restoring a live assistant is a no-op. Needs the admin role; audited as `assistant.unarchived`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Assistant"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"post-assistants-id-restore","security":[{"apiKey":[]}]}},"/api/assistant-avatars":{"post":{"tags":["Assistants"],"summary":"Upload an assistant avatar","description":"Stores a PNG, JPEG or WebP (at most 512 KB and 4096 pixels a side) as a public org asset and returns its URL, for `channels.web_chat.appearance.avatar_url`. The same picture always gets the same URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantAvatarUpload"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AssistantAvatar"}},"required":["data"]}}}},"400":{"description":"`invalid_request` for a malformed body, or `avatar_empty`, `avatar_too_large`, `avatar_type_mismatch` (the bytes are not the declared image type) or `avatar_dimensions`, in `error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`asset_storage_not_configured`: this deployment has no storage for uploaded images.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-assistant-avatars","security":[{"apiKey":[]}]}},"/api/assistants/{id}/chat-test-conversation":{"post":{"tags":["Assistants"],"summary":"Start a sandbox chat conversation","description":"Starts a one-hour conversation with an assistant, including when public web chat is off, without a publishable key or an origin check, for trying a prompt from your own tooling. Use the returned token with the public chat routes. Sandbox conversations (mode `test`) carry `metadata.test` and are left out of lists and analytics unless asked for.","responses":{"201":{"description":"Sandbox conversation created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation_id":{"type":"string"},"token":{"type":"string"}},"required":["conversation_id","token"]}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`assistant_archived`: the assistant is archived; restore it first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"post-assistants-id-chat-test-conversation","security":[{"apiKey":[]}]}},"/api/assistants/{id}/draft":{"get":{"tags":["Assistants"],"summary":"Get the assistant's draft","description":"The config being worked on in sandbox mode, or null when there is none. Sandbox chats (sandbox keys and the console's sandbox chat) run it; visitors never do until it is published.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AssistantDraft"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"get-assistants-id-draft","security":[{"apiKey":[]}]},"put":{"tags":["Assistants"],"summary":"Save the assistant's draft","description":"Starts a draft from the live config, or replaces the current one. Credentials and tool request specs left out are kept from the stored draft (or from live for a new draft). 409 `assistant_archived` for an archived assistant.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantDraftSave"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AssistantDraft"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"put-assistants-id-draft","security":[{"apiKey":[]}]},"delete":{"tags":["Assistants"],"summary":"Discard the assistant's draft","description":"Throws the draft away and returns the assistant; the live config is unchanged. Succeeds when there is no draft too.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expected_draft_revision","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"The draft_revision the caller looked at; a newer draft is not discarded (409 draft_conflict)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Assistant"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"delete-assistants-id-draft","security":[{"apiKey":[]}]}},"/api/assistants/{id}/draft/rebase":{"post":{"tags":["Assistants"],"summary":"Update the draft from live","description":"After live changed under a draft (a stale draft), lays what the draft changed since its base version over today's live config, so it can be published without undoing live's change. Settings both changed differently are refused with 409 rebase_conflict and their `paths`, unless keep_draft keeps the draft's values; those paths are returned as `kept_draft`. Also 409 no_draft, draft_conflict, rebase_unavailable when the base version is not in history, or rebase_invalid (with `issues`) when the merged config would not be valid; the draft is then left as it was. 409 `assistant_archived` for an archived assistant.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantDraftRebase"}}}},"responses":{"200":{"description":"The updated draft, and the settings where the draft's value was kept over live's.","content":{"application/json":{"schema":{"type":"object","required":["data","kept_draft"],"properties":{"data":{"$ref":"#/components/schemas/AssistantDraft"},"kept_draft":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"post-assistants-id-draft-rebase","security":[{"apiKey":[]}]}},"/api/assistants/{id}/integrations/google-analytics":{"get":{"tags":["Assistants"],"summary":"Read the assistant's Google Analytics settings","description":"The GA4 settings live chats send with: the assistant-wide property, web chat's own override and its browser options, which property is in effect, and the latest server-side delivery. API secrets are write-only and come back as `api_secret_set`, true when the organization's google_analytics connection for that measurement ID holds one. `effective` follows the server's rule: web chat's property when it has both a measurement ID and a secret, else the assistant's when that has both, else none. `status.last_status` `delivered` means Google accepted the request, which its Measurement Protocol does for almost any payload; use the test endpoint to check one.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Ga4Settings"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"get-assistants-id-integrations-google-analytics","security":[{"apiKey":[]}]},"put":{"tags":["Assistants"],"summary":"Change the assistant's Google Analytics settings","description":"Requires an admin. Every field is optional; only what you send changes. `assistant: null` removes the assistant-wide property and `web_chat.measurement_id: null` removes web chat's own, so web chat falls back to the assistant's. An `api_secret` is stored as the organization's google_analytics connection for that measurement ID (shared by every assistant naming the ID; the config keeps only the ID). It is required when no secret is stored for the ID and none was stored in that place; otherwise leaving it out keeps the stored one. The change lands on the live config and on the draft when there is one, takes effect at once, and keeps a current draft current (its revision is bumped, so reload a draft you hold before saving it). Recorded as an assistant version and audited. Answers with the settings as read.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ga4SettingsUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Ga4Settings"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`assistant_archived`: the assistant is archived; restore it first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"put-assistants-id-integrations-google-analytics","security":[{"apiKey":[]}]}},"/api/assistants/{id}/integrations/google-analytics/test":{"post":{"tags":["Assistants"],"summary":"Send a Google Analytics test event","description":"Requires an admin. Checks a `test_event` (with the assistant's event prefix) against GA4's validation endpoint, then, if it passes, sends it for real with `debug_mode` so it shows in the property's DebugView. Tests the values you send, both or neither; without them, the property live chats send with. GA4's validator checks the payload, not that the secret belongs to the property, so watch DebugView to confirm. Not counted as the assistant's delivery status. At most 10 a minute per assistant.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"measurement_id":{"type":"string","pattern":"^G-[A-Z0-9]{4,20}$"},"api_secret":{"type":"string","minLength":1,"maxLength":128,"writeOnly":true}}}}}},"responses":{"200":{"description":"The test's outcome","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean","description":"GA4's validator found nothing wrong."},"messages":{"type":"array","items":{"type":"string"},"description":"What the validator objected to."},"sent":{"type":"boolean","description":"The real event was accepted."},"reason":{"type":"string","enum":["not_configured","no_identity","rejected","unreachable"],"description":"Why it was not valid or not sent."},"event_name":{"type":"string"},"measurement_id":{"type":["string","null"]}},"required":["valid","messages","sent","event_name","measurement_id"]}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: more than 10 test events this minute. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id, `asst_...`."}],"operationId":"post-assistants-id-integrations-google-analytics-test","security":[{"apiKey":[]}]}},"/api/assistants/{id}/publish":{"post":{"tags":["Assistants"],"summary":"Publish the draft","description":"Makes the draft the live config and records the new version. Refused with 409 no_draft, version_conflict, draft_conflict, live_changed when live was edited after the draft started, or assistant_archived.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantPublish"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Assistant"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"post-assistants-id-publish","security":[{"apiKey":[]}]}},"/api/assistants/{id}/versions":{"get":{"tags":["Assistants"],"summary":"List the assistant's config history","description":"Every live config the assistant has had, newest first (the latest 100).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssistantVersion"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"get-assistants-id-versions","security":[{"apiKey":[]}]}},"/api/assistants/{id}/versions/{version}":{"get":{"tags":["Assistants"],"summary":"Get one version of the assistant's config","description":"The live config the assistant had at that version, as the history list returns it. 404 for a version not in its history.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AssistantVersion"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"operationId":"get-assistants-id-versions-version","security":[{"apiKey":[]}]}},"/api/assistants/{id}/versions/{version}/restore":{"post":{"tags":["Assistants"],"summary":"Restore a version","description":"Brings an old config back with today's credentials and tool auth: into the draft by default, or straight to live with target live. 409 `assistant_archived` for an archived assistant.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantRestore"}}}},"responses":{"200":{"description":"The draft it was restored into, or the assistant with target live.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/AssistantDraft"},{"$ref":"#/components/schemas/Assistant"}]}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"operationId":"post-assistants-id-versions-version-restore","security":[{"apiKey":[]}]}},"/api/assistants/draft-from-website":{"post":{"tags":["Assistants"],"summary":"Draft an assistant from a website","description":"Admin only. Resolves the caller's project, reuses or collects site facts (up to 30 seconds), and uses the project's own model connection (up to 45 seconds). Missing credentials or invalid model output uses a deterministic template. Creates version 1 and an audit entry through normal assistant validation. Public web chat stays off. Organization knowledge access is required to import and attach website pages.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"project_id":{"type":"string","minLength":1},"website":{"type":"string","minLength":1,"maxLength":2048},"goal":{"type":"string","enum":["leads","booking","answers"]},"description":{"type":"string","maxLength":2000}},"required":["goal"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebsiteAssistantDraft"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"project_not_in_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"website_required, or site_unreadable with reason timeout, unreachable or blocked","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["website_required","site_unreadable"]},"reason":{"type":"string","enum":["timeout","unreachable","blocked"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"assistant_draft_failed: a storage or internal operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-assistants-draft-from-website","security":[{"apiKey":[]}]}},"/api/knowledge":{"post":{"tags":["Knowledge"],"summary":"Create a knowledge base","description":"An empty knowledge base. Added public sources are approved immediately and go live automatically once indexing succeeds. Needs an org-wide API key: project keys cannot use organization knowledge.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Trimmed; 1 to 200 characters."},"description":{"type":"string","maxLength":2000,"default":""},"reread_weekly":{"type":"boolean","default":true}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeBase"}},"required":["data"]}}}},"400":{"description":"`invalid_knowledge_payload`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_role` (below admin) or `knowledge_forbidden` (a project-scoped key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge","security":[{"apiKey":[]}]},"get":{"tags":["Knowledge"],"summary":"List knowledge bases","description":"Every knowledge base in the organization, newest first. Needs an org-wide API key: project keys cannot use organization knowledge. A project key gets an empty list.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBase"}}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get-knowledge","security":[{"apiKey":[]}]}},"/api/knowledge/{id}":{"get":{"tags":["Knowledge"],"summary":"Get a knowledge base","description":"The base with its sources (and each one's latest revision), publications, the assistants answering from it (`attachments`) and what open assistant drafts would change (`pending`). Private sources are listed only for admins and above. Poll this after starting a publication until its status is `ready`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeBaseDetail"}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required`: a project-scoped key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get-knowledge-id","security":[{"apiKey":[]}]},"patch":{"tags":["Knowledge"],"summary":"Update a knowledge base","description":"Rename it, change its description, turn it off (`enabled: false` stops every attached assistant using it at once, without deleting anything), or choose how it is searched.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Trimmed; 1 to 200 characters."},"description":{"type":"string","maxLength":2000},"enabled":{"type":"boolean"},"reread_weekly":{"type":"boolean","description":"Fetch non-revoked URL sources about once a week."},"retrieval_mode":{"type":"string","enum":["vector_store","hybrid"],"description":"How assistants search it. New bases use `hybrid`, which takes effect once the live publication's hybrid index is ready; until then search uses the vector store."}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeBase"}},"required":["data"]}}}},"400":{"description":"`invalid_knowledge_payload`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"patch-knowledge-id","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/sources":{"post":{"tags":["Knowledge"],"summary":"Add or revise a source","description":"Adds text, a web page (`url`) or a file (`filename` and `base64`: txt, md, html, docx or pdf up to 5 MB) and saves an approved revision. Approved public content is indexed and activated automatically; a failed build keeps the previous live publication. Pass an existing source `id` to revise it. Only `public` sources are ever published; `audience` defaults to `public` and cannot change later. URL sources must be public HTTPS pages that robots.txt allows, without query or fragment.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"An existing source to revise. Omit to add a new one."},"kind":{"type":"string","enum":["text","url","file"]},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Trimmed; 1 to 200 characters."},"audience":{"type":"string","enum":["public","private"],"default":"public","description":"Fixed when the source is created."},"text":{"type":"string","maxLength":200000,"description":"`text` sources: the content."},"url":{"type":"string","maxLength":2048,"description":"`url` sources: the page to fetch."},"filename":{"type":"string","maxLength":200,"description":"`file` sources: the name, whose extension picks the parser."},"base64":{"type":"string","maxLength":7000000,"description":"`file` sources: the file bytes, base64-encoded."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Stop using the source after this time."}},"required":["kind","title"]}}}},"responses":{"201":{"description":"Created; `data.id` is the source id, `ksrc_...`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"400":{"description":"`invalid_knowledge_payload` (including `text` over 200,000 characters), `source_text_required_or_too_large` (empty text), `invalid_source_id`, or a URL or file code: `invalid_source_url`, `public_https_url_required`, `source_path_not_allowed`, `source_disallowed_by_robots`, `source_address_not_public`, `source_redirect_not_allowed`, `source_too_large`, `source_needs_review_no_text`, `website_content_type_not_supported`, `unsupported_document_type`, `pdf_page_limit_reached`, `document_expansion_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`, or `source_not_found` when revising","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`source_identity_is_immutable` (a revision changed the kind, URL or audience: add a new source instead) or `source_limit_reached` (100 active sources)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`source_fetch_failed`, `source_not_found` or `source_blocked` (the page did not answer 200) or `knowledge_operation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`knowledge_storage_not_configured`: this deployment cannot store sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-sources","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/attachments/{assistantId}":{"post":{"tags":["Knowledge"],"summary":"Attach a knowledge base (retired)","description":"Retired: always 410 `knowledge_attachments_moved`. Which knowledge bases an assistant answers from is part of its config now (`knowledge` on PATCH /assistants/{id}), drafted and published with the rest of it, so a change no longer reaches live chats at once. Requires admin or above.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."},{"name":"assistantId","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id."}],"responses":{"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`knowledge_attachments_moved`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-cli":false,"operationId":"post-knowledge-id-attachments-assistantid","security":[{"apiKey":[]}]},"delete":{"tags":["Knowledge"],"summary":"Detach a knowledge base (retired)","description":"Retired: always 410 `knowledge_attachments_moved`. Which knowledge bases an assistant answers from is part of its config now (`knowledge` on PATCH /assistants/{id}), drafted and published with the rest of it, so a change no longer reaches live chats at once. Requires admin or above.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."},{"name":"assistantId","in":"path","required":true,"schema":{"type":"string"},"description":"Assistant id."}],"responses":{"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`knowledge_attachments_moved`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-cli":false,"operationId":"delete-knowledge-id-attachments-assistantid","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/discover":{"post":{"tags":["Knowledge"],"summary":"Find a site's pages from its sitemap","description":"Reads robots-advertised sitemaps and bounded sitemap indexes, falling back to the homepage and its links. Follows redirects between the apex and www hosts, checks each origin's robots rules, excludes asset URLs and returns up to 100 page URLs without importing anything. Add the ones you want as `url` sources.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048,"description":"Any page on the site; its origin's /sitemap.xml is read."}},"required":["url"]}}}},"responses":{"200":{"description":"Page URLs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","maxItems":100,"items":{"type":"string","format":"uri"}}},"required":["data"]}}}},"400":{"description":"`invalid_knowledge_payload` or a URL code such as `public_https_url_required`, `source_disallowed_by_robots` or `source_address_not_public`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-discover","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/pages":{"post":{"tags":["Knowledge"],"summary":"Import website pages","description":"Durably fetch the selected same-origin public HTTP(S) pages, saving approved public URL sources. Unchanged text is reused. Poll the base for progress. One build is queued at completion.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"urls":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","maxLength":2048}},"reread_weekly":{"type":"boolean"}},"required":["urls"]}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgePageImportAccepted"}},"required":["data"]}}}},"400":{"description":"`invalid_knowledge_payload`, `pages_same_origin_required`, `invalid_source_url`, `public_https_url_required` or `source_path_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`page_import_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-pages","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/publications":{"post":{"tags":["Knowledge"],"summary":"Build a publication","description":"Snapshots every approved public source into a new immutable publication and indexes it in the background (202). Poll the knowledge base until the publication is `ready`, then publish it. Returns the pending build instead when one is already queued. No request body.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"responses":{"202":{"description":"Queued; `data.id` is the publication id, `kpub_...`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"400":{"description":"`no_public_sources`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`review_all_public_sources_first` or `publication_limit_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`knowledge_not_configured`, `knowledge_storage_not_configured` or `knowledge_provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-publications","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/publications/{publicationId}/publish":{"post":{"tags":["Knowledge"],"summary":"Publish a ready publication","description":"Makes a `ready` publication the live one, atomically; publishing an older ready publication rolls back to it. 409 `publication_not_ready`, or `sources_changed_rebuild_publication` when sources changed since it was built.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."},{"name":"publicationId","in":"path","required":true,"schema":{"type":"string"},"description":"Publication id, `kpub_...`."}],"responses":{"200":{"description":"Published","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`publication_not_ready` (also for an unknown publication id) or `sources_changed_rebuild_publication`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-publications-publicationid-publish","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/publications/{publicationId}/retry":{"post":{"tags":["Knowledge"],"summary":"Retry a failed publication","description":"Queues a `failed` publication for indexing again, from the files it already stored. A publication already queued, indexing or ready returns its id unchanged. If a build is already queued for this base, returns that build's id.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."},{"name":"publicationId","in":"path","required":true,"schema":{"type":"string"},"description":"Publication id, `kpub_...`."}],"responses":{"200":{"description":"Queued again","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`, or `failed_publication_not_found` (no failed publication with that id)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-publications-publicationid-retry","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/publications/{publicationId}/test":{"post":{"tags":["Knowledge"],"summary":"Try a publication in sandbox chats","description":"Sandbox chats (on a sandbox publishable key, or the console's sandbox chat) search this `ready` publication instead of the live one, so new content can be tried before it goes live. Live chats are unchanged. Make it live with POST /knowledge/{id}/test-publication/promote. Requires admin or above.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."},{"name":"publicationId","in":"path","required":true,"schema":{"type":"string"},"description":"Publication id, `kpub_...`."}],"responses":{"200":{"description":"Sandbox chats now search it","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`publication_not_ready` (also for an unknown publication id) or `sources_changed_rebuild_publication`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-publications-publicationid-test","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/reread":{"post":{"tags":["Knowledge"],"summary":"Re-read website pages","description":"Durably re-fetch every non-revoked URL source. A failed fetch keeps the previous approved revision. Changed public text is indexed and goes live automatically.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgePageImportAccepted"}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`page_import_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-reread","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/revisions/{revisionId}":{"get":{"tags":["Knowledge"],"summary":"Preview a revision's extracted text","description":"The text extracted from a source revision, to check before approving it. A private source's revision is `revision_not_found` below admin.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string"},"description":"Revision id, `krev_...`, from the source's `revision.id`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeRevisionPreview"}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required`: a project-scoped key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found` or `revision_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`knowledge_storage_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get-knowledge-id-revisions-revisionid","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/revisions/{revisionId}/approve":{"post":{"tags":["Knowledge"],"summary":"Approve a revision","description":"Marks the extracted text as fit to publish. Every public source's latest revision must be approved before a publication can be built. Requires admin or above. No request body.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string"},"description":"Revision id, `krev_...`."}],"responses":{"200":{"description":"Approved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found` or `revision_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-revisions-revisionid-approve","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/search":{"post":{"tags":["Knowledge"],"summary":"Search a knowledge base","description":"Runs a question against the live publication (or, with `publication: test`, the sandbox one that sandbox chats search) and returns the passages an assistant would get, for checking coverage. It only reads, so a viewer key may call it although it is a POST.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":2000},"publication":{"type":"string","enum":["live","test"],"default":"live","description":"`test` searches the publication sandbox chats use."}},"required":["query"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSearchResult"}},"required":["data"]}}}},"400":{"description":"`invalid_knowledge_payload`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required`: a project-scoped key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-search","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/sources/{sourceId}":{"delete":{"tags":["Knowledge"],"summary":"Revoke a source","description":"Answers stop using the source at once, even from the live publication; the next publication leaves it out.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."},{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"},"description":"Source id, `ksrc_...`."}],"responses":{"200":{"description":"Revoked; `data` is the source row with `revoked_at` set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found` or `source_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"delete-knowledge-id-sources-sourceid","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/test-publication":{"delete":{"tags":["Knowledge"],"summary":"Stop trying a publication","description":"Sandbox chats go back to searching the live publication. Requires admin or above.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"responses":{"200":{"description":"Cleared; `data.id` is the knowledge base id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"delete-knowledge-id-test-publication","security":[{"apiKey":[]}]}},"/api/knowledge/{id}/test-publication/promote":{"post":{"tags":["Knowledge"],"summary":"Make the tested publication live","description":"Makes the publication sandbox chats are searching the live one, then clears the sandbox pick. Send `expected_publication_id` to be sure it is the one you tested. Refused when another publication went live after it was picked, since it may lack what that one added: try the publication again, or build a new one. Requires admin or above.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Knowledge base id, `kb_...`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"expected_publication_id":{"type":"string","minLength":1,"description":"The publication you tested, `kpub_...`; 409 `test_publication_changed` when the sandbox pick is another one."}},"required":[]}}}},"responses":{"200":{"description":"Live; `data.id` is the publication id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["data"]}}}},"400":{"description":"`invalid_knowledge_payload`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`organization_knowledge_access_required` (a project-scoped key) or `insufficient_role` (changes need admin or above)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`knowledge_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`no_test_publication`, `test_publication_changed`, `test_publication_stale` (another publication went live after this one was picked), `publication_not_ready` or `sources_changed_rebuild_publication`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`knowledge_operation_failed`: an unexpected failure; retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-knowledge-id-test-publication-promote","security":[{"apiKey":[]}]}},"/api/phone-numbers":{"get":{"tags":["Phone numbers"],"summary":"List phone numbers","description":"Numbers in scope, with the assistant each one is attached to and how it routes calls.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's numbers."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PhoneNumber"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-phone-numbers","security":[{"apiKey":[]}]},"post":{"tags":["Phone numbers"],"summary":"Import a phone number you own","description":"Registers a customer-owned number with `provider: null` (the default) and `forward_to`, an active platform number in the same project. The customer configures forwarding with their carrier; attach the assistant to the platform line. For a carrier-managed number, pass an explicit provider and its carrier identifiers, or use the claim endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberImport"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-phone-numbers","security":[{"apiKey":[]}]}},"/api/phone-numbers/{id}":{"get":{"tags":["Phone numbers"],"summary":"Get a phone number","description":"One number with its assistant, routing mode and status.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number id, `pn_...`."}],"operationId":"get-phone-numbers-id","security":[{"apiKey":[]}]},"patch":{"tags":["Phone numbers"],"summary":"Set a phone number's sandbox mode","description":"Every call to or from a sandbox number is a sandbox call: it runs the assistant's saved draft, reaches sandbox webhooks only and stays out of analytics. A live outbound call cannot use a sandbox number as its caller ID. A database change only; carrier routing (routing_mode) is unchanged. Admins only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number id, `pn_...`."}],"operationId":"patch-phone-numbers-id","security":[{"apiKey":[]}]},"delete":{"tags":["Phone numbers"],"summary":"Release a phone number","description":"Deletes the number from the registry and, when it is carrier-managed and this deployment can reach the carrier, releases it back to the carrier (you lose the number and stop paying for it). Check `data.released`: false means the carrier was not asked, so the number may still be yours and billed there. Detach its assistant first: an attached number is 409 `{\"error\":\"number_attached\"}`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PhoneNumberRelease"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`number_attached`: detach the assistant first. `number_has_forwarding_lines`: customer lines forward to this number; remove them first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number id, `pn_...`."}],"operationId":"delete-phone-numbers-id","security":[{"apiKey":[]}]}},"/api/phone-numbers/{id}/attach":{"post":{"tags":["Phone numbers"],"summary":"Attach an assistant to a phone number","description":"Puts an assistant on the number and configures the carrier so inbound calls reach it. The assistant and number must be in the same project, and the assistant not archived (409 `assistant_archived`; a number already attached to an assistant that is later archived keeps it). `routing_mode` picks the path: `trunk` (SIP straight to the voice runtime, cold transfers) or `pv_webhook` (Twilio Programmable Voice bridge, warm transfers).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberAttach"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`assistant_archived`: the assistant is archived; restore it first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`telephony_not_configured`: this deployment has no carrier account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number id, `pn_...`."}],"operationId":"post-phone-numbers-id-attach","security":[{"apiKey":[]}]},"delete":{"tags":["Phone numbers"],"summary":"Detach the assistant from a phone number","description":"The number stops reaching any assistant. It stays registered and owned; release it to give it up.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number id, `pn_...`."}],"operationId":"delete-phone-numbers-id-attach","security":[{"apiKey":[]}]}},"/api/phone-numbers/{id}/mode":{"post":{"tags":["Phone numbers"],"summary":"Change a phone number's routing mode","description":"Moves an attached number between `trunk` and `pv_webhook` routing and reconfigures the carrier, keeping its assistant.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberMode"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`telephony_not_configured`: this deployment has no carrier account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Phone number id, `pn_...`."}],"operationId":"post-phone-numbers-id-mode","security":[{"apiKey":[]}]}},"/api/phone-numbers/available":{"get":{"tags":["Phone numbers"],"summary":"Search available US phone numbers","description":"Numbers the carrier can sell right now, in the United States only. Each includes locality and region where available, and the local-number monthly current price in the carrier's currency, cached per country for 12 hours. Unavailable or failed pricing is null and does not fail the search. Buy one with the purchase route.","parameters":[{"name":"area_code","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Three-digit US area code, for example `415`."},{"name":"contains","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Digits the number must contain."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many numbers to return."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AvailablePhoneNumber"}}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`telephony_not_configured`: this deployment has no carrier account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get-phone-numbers-available","security":[{"apiKey":[]}]}},"/api/phone-numbers/purchase":{"post":{"tags":["Phone numbers"],"summary":"Buy a phone number","description":"Buys a number from the carrier (it is billed from then on) and registers it in the project, unattached. Attach an assistant next to answer calls on it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberPurchase"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`telephony_not_configured`: this deployment has no carrier account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-phone-numbers-purchase","security":[{"apiKey":[]}]}},"/api/calls":{"post":{"tags":["Calls"],"summary":"Place an outbound phone call","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Use the same key for retries of one dial. The key is scoped to your organization. Replays return the original call without dialing again, including after an unknown provider outcome. Changed request fields with the same key return idempotency_conflict. Claims survive removal of call history."}],"description":"Dispatches the assistant into a fresh room and dials `to` over the outbound SIP trunk. With the default LiveKit runtime the request waits while the phone rings and returns once the callee answers, so allow for a long response; a call that is not answered or fails to connect answers 502 `provider_error` and is marked failed. The 201 body says `status: \"ringing\"` (the body's literal value, not the live state): follow the call through the `call.connected` and `call.ended` webhooks, or read it back by id. The body is not wrapped in `data`. With `mode: test` the call runs the assistant's saved draft (its live config when there is none) and is a sandbox call. 503 `livekit_not_configured` when this deployment cannot place calls.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundCallCreate"}}}},"responses":{"201":{"description":"Ringing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundCallCreated"}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such assistant for this key, or `from` is not an active number in the assistant's project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`test_number_requires_test_mode`: `from` is a sandbox number and the call is live. `idempotency_conflict`: the key was already used with different call details. `outside_contact_hours`: no call is placed outside the regional/project window or while a country route is blocked; the response includes rule, citation and next_allowed_at (ISO timestamp or null). Applies to live and test PSTN calls. Retry at the returned time; this endpoint does not queue calls.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`provider_error`: the call was not answered or could not be placed; it is marked failed and its room is closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`livekit_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-calls","security":[{"apiKey":[]}]},"get":{"tags":["Calls"],"summary":"List calls","description":"Calls newest first, one cursor page at a time. Rows carry the transcript; usage lines, recordings and analysis come with the single call. A project key sees its own project; an org-wide key sees every project unless `project_id` narrows it.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's calls. With a project key, another project's id returns an empty list."},{"name":"assistant_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this assistant's calls."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ringing","in_progress","completed","failed","no_answer","busy","cancelled"]},"description":"Only calls in this state."},{"name":"call_type","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound","web"]},"description":"Only inbound, outbound or browser calls."},{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"Case-insensitive literal substring across call id, phone numbers, assistant id and the captured lead's name."}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or after this time (ISO 8601 with an offset)."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or before this time (ISO 8601 with an offset)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Legacy ISO timestamp cursors are also accepted."}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["live","test","all"],"default":"live","description":"Live calls unless asked: sandbox calls (console sandbox calls, sandbox numbers, mode test) stay out by default."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-calls","security":[{"apiKey":[]}]}},"/api/calls/web":{"post":{"tags":["Calls"],"summary":"Start a browser call","description":"Mints a browser join token: connect to `url` with `token` using a LiveKit client and publish the microphone. The token lasts 15 minutes. For a live call the row exists only once the browser joins and the call starts, so `GET /calls/{id}` can 404 until then. With `mode: test` the call runs the assistant's saved draft (its live config when there is none), and its row (mode `test`) is created before the agent is dispatched. Call this from your server; hand only `url` and `token` to the browser. 503 when LiveKit is not configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebCallCreate"}}}},"responses":{"201":{"description":"Created. Not wrapped in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebCallCreated"}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such assistant for this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`livekit_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-calls-web","security":[{"apiKey":[]}]}},"/api/calls/{id}":{"get":{"tags":["Calls"],"summary":"Get a call","description":"One call with its transcript, usage lines, recordings, latency metrics, post-call analysis and the lifecycle events received for it. API keys see usage quantities but not prices.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CallDetail"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Call id, `call_...`."}],"operationId":"get-calls-id","security":[{"apiKey":[]}]}},"/api/calls/{id}/hangup":{"post":{"tags":["Calls"],"summary":"Hang up a live call","description":"Asks the voice runtime to end a ringing or in-progress call. The call ends shortly after, with a `call.ended` webhook. 409 `call_not_active` once it has ended.","responses":{"200":{"description":"Hangup requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallHangupResponse"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`call_not_active`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`livekit_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Call id, `call_...`."}],"operationId":"post-calls-id-hangup","security":[{"apiKey":[]}]}},"/api/calls/{id}/listen":{"post":{"tags":["Calls"],"summary":"Get a listen-only token for a live call","description":"A LiveKit token that can hear a live call but not speak in it, for supervising from your own interface. Connect to `url` with `token`. 409 when the call is not live.","responses":{"200":{"description":"Listen token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallListenResponse"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`call_not_active`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`livekit_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Call id, `call_...`."}],"operationId":"post-calls-id-listen","security":[{"apiKey":[]}]}},"/api/calls/{id}/recordings":{"get":{"tags":["Calls"],"summary":"List a call's recordings","description":"Each recorded leg of the call with its status and length. Ask the access route for a playback URL once a recording is `ready`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CallRecording"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Call id, `call_...`."}],"operationId":"get-calls-id-recordings","security":[{"apiKey":[]}]}},"/api/calls/{id}/recordings/{recordingId}/access":{"get":{"tags":["Calls"],"summary":"Get a short-lived recording link","description":"Requires access to the parent call. The response is private/no-store. URLs are generated on demand, never stored, and expire after 15 minutes: fetch a new one each time you play.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Call id, `call_...`."},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string"},"description":"Recording id, `rec_...`, from the call's recordings."},{"name":"download","in":"query","schema":{"type":"boolean","default":false},"description":"`true` for a URL that downloads the file; `false` for one that plays in the browser."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecordingAccess"}},"required":["data"]}}}},"400":{"description":"`invalid_download`: `download` must be `true` or `false`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`recording_not_ready`, or `recording_storage_mismatch` (stored by another deployment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`recording_deleted`: the recording was deleted or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`recording_storage_not_configured` or `recording_access_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get-calls-id-recordings-recordingid-access","security":[{"apiKey":[]}]}},"/api/preview-links":{"get":{"tags":["Publishable keys"],"summary":"Get an assistant's preview link","description":"The assistant's live (unrevoked) preview link, expired or not, or null when it has none.","parameters":[{"name":"assistant_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/PreviewLink"},{"type":"null"}]}}}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-preview-links","security":[{"apiKey":[]}]},"post":{"tags":["Publishable keys"],"summary":"Make a preview link (pk_preview_…)","description":"A page where anyone with the link, or only signed-in members of the org, can try the assistant's web chat; it loads from any site and while web chat is off, and its chats are tests that send nothing outside. One live link per assistant: making one turns the previous link off, with its open chats.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":"string"},"access":{"type":"string","enum":["public","team"]},"expires_at":{"type":["string","null"],"format":"date-time","description":"In the future; null works until it is turned off."}},"required":["assistant_id","access","expires_at"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreviewLink"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`assistant_archived`: the assistant is archived; restore it first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-preview-links","security":[{"apiKey":[]}]}},"/api/preview-links/{id}":{"patch":{"tags":["Publishable keys"],"summary":"Change who may open a preview link, or when it expires","description":"The URL and key stay the same.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"access":{"type":"string","enum":["public","team"]},"expires_at":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreviewLink"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"patch-preview-links-id","security":[{"apiKey":[]}]},"delete":{"tags":["Publishable keys"],"summary":"Turn a preview link off","description":"The page stops loading, and the chats open on it end.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreviewLink"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"delete-preview-links-id","security":[{"apiKey":[]}]}},"/api/preview-links/{id}/page":{"get":{"tags":["Publishable keys"],"summary":"Read a preview link for its page","description":"Needs no session. A team-only link returns only `access` and `org_id` unless the caller is a member of that org, who also gets the key.","security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPage"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The link has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"get-preview-links-id-page"}},"/api/publishable-keys":{"get":{"tags":["Publishable keys"],"summary":"List publishable keys","description":"Filter by project_id (covers project-scoped keys) or assistant_id (legacy pinned keys); no filter returns everything in scope. Site keys only unless kind says otherwise. Revoked keys are included, with `revoked_at` set.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only keys for this project."},{"name":"assistant_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only keys pinned to this assistant."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["site","test","all"]},"description":"site (the default) lists the keys for live websites, test the sandbox keys (`kind: test`, `pk_test_...`), all both."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WidgetKey"}}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-publishable-keys","security":[{"apiKey":[]}]},"post":{"tags":["Publishable keys"],"summary":"Create a publishable key","description":"Returns the key in `data.key`: `pk_live_...` for a site key, `pk_test_...` for a sandbox key. `project_id` (or, with a project API key, nothing at all) mints a project-scoped key, usable with any assistant in the project: the embed names the assistant with `data-mlf-assistant` and public chat requests send `assistant`. `assistant_id` mints a key pinned to that assistant. An org-wide API key must send one of the two (400 otherwise). Publishable keys are safe in page source; which sites may use a site key is the assistant's `channels.web_chat.allowed_origins`. `kind: test` mints a sandbox key for a staging site or localhost: it loads only on its own `allowed_origins`, and its chats run the assistant's draft, search the sandbox knowledge publication and reach sandbox webhooks only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"string","minLength":1,"description":"Mint a project-scoped key."},"assistant_id":{"type":"string","minLength":1,"description":"Mint a key pinned to this assistant."},"kind":{"type":"string","enum":["site","test"],"default":"site","description":"`site` for your live site, `test` for a sandbox key (`pk_test_...`) on a staging site or localhost."},"allowed_origins":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Sandbox keys only, and required for them: the HTTP(S) origins the key loads on."}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WidgetKey"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`assistant_not_found` or `project_not_found`: not in this key's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`assistant_archived`: the assistant is archived; restore it first (its existing keys stay)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-publishable-keys","security":[{"apiKey":[]}]}},"/api/publishable-keys/{id}":{"delete":{"tags":["Publishable keys"],"summary":"Revoke a publishable key","description":"Revocation, not deletion: the row stays and gains a `revoked_at`, so an embed that still carries the key gets a clean refusal rather than a missing record.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WidgetKey"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Key record id, `wkey_...` (not the `pk_live_` key itself)."}],"operationId":"delete-publishable-keys-id","security":[{"apiKey":[]}]}},"/api/publishable-keys/site-activity":{"get":{"tags":["Publishable keys"],"operationId":"get-publishable-keys-site-activity","summary":"List web chat install evidence by assistant and site","description":"Viewer role. Live traffic only, within the caller's org and project scope. Counts cover the requested window; last_loaded_at looks back 180 days across widget_loaded events and sampled config/ok outcomes, and last_refused_at looks back 30 days across origin_not_allowed outcomes on any chat route. Refusal counts cover the full requested window, including windows longer than 30 days. Chats count live web_chat conversations by their parent origin. Includes refused sites even if now allowed. Sorted by latest activity descending, at most 200 sites.","parameters":[{"name":"check_url","in":"query","description":"Optional HTTPS page to inspect now. Requires assistant_id. Adds install_check with per-check causes; null when the assistant is outside scope. No page fetch is performed without this parameter.","schema":{"type":"string","format":"uri"}},{"name":"project_id","in":"query","schema":{"type":"string"}},{"name":"assistant_id","in":"query","schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":7}}],"responses":{"200":{"description":"Site activity","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["since","sites"],"properties":{"since":{"type":"string","format":"date-time"},"install_check":{"type":["object","null"],"properties":{"url":{"type":"string"},"checked_at":{"type":"string","format":"date-time"},"cause":{"type":["string","null"]},"checks":{"type":"array","items":{"type":"object","required":["check","status","cause","message","url"],"properties":{"check":{"type":"string"},"status":{"type":"string","enum":["passed","failed","unknown"]},"cause":{"type":["string","null"],"enum":["snippet_missing","script_blocked_by_csp","wrong_key","page_unreachable","origin_not_allowed",null]},"message":{"type":"string"},"url":{"type":["string","null"]}}}}}},"sites":{"type":"array","maxItems":200,"items":{"type":"object","required":["assistant_id","project_id","site","last_loaded_at","loaded_count","last_refused_at","refused_count","chats_count"],"properties":{"assistant_id":{"type":"string"},"project_id":{"type":"string"},"site":{"type":"string","format":"uri","description":"Scheme and host, for example https://www.example.com."},"last_loaded_at":{"type":["string","null"],"format":"date-time"},"loaded_count":{"type":"integer","minimum":0,"description":"widget_loaded page loads in the window; config/ok signals do not increase this count."},"last_refused_at":{"type":["string","null"],"format":"date-time"},"refused_count":{"type":"integer","minimum":0},"chats_count":{"type":"integer","minimum":0}}}}}}}}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"security":[{"apiKey":[]}]}},"/public/v1/config":{"get":{"tags":["Public chat API"],"summary":"Get the widget configuration","description":"What a chat interface needs before the first message: display name, greeting, quick replies, appearance, proactive rules, text overrides and (when on) attachment limits. Safe to call from a browser and cached for 60 seconds. When the assistant lists `allowed_origins`, a request whose `Origin` is not on the list is refused with 403.","security":[],"parameters":[{"name":"key","in":"query","required":true,"schema":{"type":"string"},"description":"Publishable key, `pk_live_...`."},{"name":"assistant","in":"query","required":false,"schema":{"type":"string"},"description":"Required with a project-scoped publishable key; ignored-if-matching for assistant-pinned keys."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicWidgetConfig"}},"required":["data"]}}}},"403":{"description":"`origin_not_allowed`: the request's `Origin` is not in the assistant's `allowed_origins`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: unknown or revoked key, no such assistant for it, or web chat is off for the assistant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-public-v1-config"}},"/public/v1/conversations":{"post":{"tags":["Public chat API"],"summary":"Start a conversation","description":"Starts a conversation with the assistant behind a publishable key and returns its id and token. Send the token as `Authorization: Bearer ct_...` on every later call for this conversation; it is returned only here. The widget starts a conversation when the visitor sends a first message, not when the panel opens. A browser page calling from its own site is checked by its `Origin` header against the assistant's `allowed_origins` (an empty list allows every site).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"widget_key":{"type":"string","minLength":1,"description":"Publishable key, `pk_live_...`."},"assistant":{"type":"string","minLength":1,"description":"Assistant id; required with a project-scoped publishable key."},"parent_origin":{"type":"string","description":"The site the chat runs on, for requests that carry no `Origin` header of their own (your server, for example) and for the widget's own frame. A browser calling from another site is checked by its real `Origin` header instead, and this field is ignored, so a page cannot borrow an allowed site's name."},"visitor_id":{"type":"string","description":"Your stable id for the visitor, so their conversations can be grouped. Stored only when analytics consent is granted or not required."},"visit_id":{"type":"string","maxLength":256,"description":"The visit this conversation started in. Kept in metadata.visit_id only when analytics consent is granted or not required, and only when it is 1 to 128 letters, digits, `_` or `-`; any other string up to 256 characters is ignored, and a longer one answers 400."},"timezone":{"type":"string","maxLength":64,"description":"The visitor's IANA time zone (for example `America/New_York`), so dates and callback times are theirs. A recognised zone is stored as metadata.visitor_timezone; an unknown one is ignored."},"attribution":{"$ref":"#/components/schemas/ChatAttribution","description":"Where the visitor came from. Sanitized, never a reason to refuse the chat. Only chat_page is kept without analytics consent."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form context stored on the conversation and sent in its webhooks (for example a region or campaign). The `preview` and `attribution` keys are reserved and dropped; send attribution in `attribution`."},"client_message_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"The id of the first message you are about to send, so this request is linked to it in chat analytics."},"page_view_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"The page view the chat started on, as reported to POST /public/v1/telemetry."},"consent":{"type":"string","enum":["granted","denied","not_required"],"description":"The visitor's analytics consent, which decides whether analytics ids are stored."},"preamble":{"type":"array","maxItems":5,"items":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":2000}},"required":["content"]},"description":"Assistant lines your interface already showed (a greeting or proactive teaser), stored first so the transcript reads as the visitor saw it."}},"required":["widget_key"]}}}},"responses":{"201":{"description":"Conversation created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation_id":{"type":"string"},"token":{"type":"string","description":"Conversation token, `ct_...`: send it as `Authorization: Bearer ct_...` on this conversation's routes. Returned once; valid for at most 30 days (less when a sandbox key behind it is revoked, or a preview link turned off or expired)."},"status":{"type":"string","enum":["open"]},"messages":{"type":"array","items":{"$ref":"#/components/schemas/PublicMessage"},"description":"Any `preamble` lines you sent, stored as the assistant's first messages."},"config":{"$ref":"#/components/schemas/PublicWidgetConfig"}},"required":["conversation_id","token","status","messages","config"]}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`origin_not_allowed`: the calling site is not in the assistant's `allowed_origins` (see `parent_origin` for which site that is)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: unknown or revoked key, no such assistant for it, or web chat is off for the assistant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`key_quota_exceeded`: the publishable key has used a budget shared by every visitor of your site: 300 new conversations an hour, 30 an hour from one IP address, or 5,000 assistant replies a day. `rate_limited` is the ordinary per-address limit. Both carry `Retry-After`, in seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-public-v1-conversations"}},"/public/v1/conversations/{id}/messages":{"post":{"tags":["Public chat API"],"summary":"Send a message and stream the reply","description":"Sends the visitor's message and streams the reply as server-sent events (see ChatSseEvents): usually `message.accepted`, then `message.delta` chunks and any `tool.status`, always ending with exactly one `message.completed` or `error`. A 200 status does not mean the turn succeeded: read to the terminal event. While a person has taken over, the stream is a single `message.completed` with `message: null`, and their reply arrives through the updates route. One turn runs at a time per conversation. Send a `client_message_id` so a retry after a dropped connection replays the stored result as one terminal event instead of answering twice. A retry of a turn whose reply was cut off (none stored, or a truncated one) is answered again when no person has taken over and nothing but read-only work (such as knowledge searches) ran; otherwise it ends with `error` `turn_interrupted`.","x-sse-events":{"$ref":"#/components/schemas/ChatSseEvent"},"security":[{"conversationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_message_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Your id for this message, unique within the conversation. Resending the same id with the same content replays the stored turn; with different content or files it is 409 `message_id_conflict`."},"content":{"type":"string","maxLength":4000,"default":"","description":"May be empty when `attachment_ids` is given. A message needs non-empty content, attachment_ids, or both (otherwise 422 `invalid_content`)."},"consent":{"type":"string","enum":["granted","denied","not_required"],"description":"The visitor's analytics consent as your interface knows it now."},"attachment_ids":{"type":"array","maxItems":5,"items":{"type":"string","minLength":1,"maxLength":64},"description":"Ids returned by POST /public/v1/conversations/{id}/attachments for this conversation, at most 5. Each file can be sent once."},"page":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"title":{"type":"string","maxLength":200}},"required":["url","title"],"description":"The host page the visitor sent this from. A new message stores its path (no origin, query or hash) and title as `rich.metadata.page`, and a web chat model reads them beside that message. A retry keeps the page stored first. A malformed or non-http(s) page is ignored, never refused."},"page_view_id":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"The page view the visitor sent this from, as reported to POST /public/v1/telemetry. Ignored when malformed."},"test":{"type":"boolean","enum":[true],"description":"Marks the conversation as a test from now on, for a chat that began before the page was marked as one. Cannot be undone."}}}}}},"responses":{"200":{"description":"SSE assistant turn","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/ChatSseEvents"}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`attachments_disabled`: the assistant's web chat `attachments.enabled` is false","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`turn_in_progress` (another turn is still running), `conversation_ended`, `message_id_conflict` (a replayed `client_message_id` with different content or attachments), `attachment_already_sent` or `llm_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`invalid_content` (no text and no files, or text over 4,000 characters), `attachment_not_found` or `too_many_attachments`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`key_quota_exceeded`: the publishable key has used a budget shared by every visitor of your site: 300 new conversations an hour, 30 an hour from one IP address, or 5,000 assistant replies a day. `rate_limited` is the ordinary per-address limit. Both carry `Retry-After`, in seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`chat_temporarily_unavailable`: retry after `Retry-After` seconds (1)","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-messages"}},"/public/v1/conversations/{id}/updates":{"get":{"tags":["Public chat API"],"summary":"Poll for new messages","description":"Messages after a sequence number, plus the conversation's state. Poll this while a person has taken over (their replies arrive here, not on the send stream) or after a dropped stream. Keep the highest `seq` you have seen and pass it as `after_seq`. Polling has its own rate limit: 60 a minute per conversation and IP address.","security":[{"conversationToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."},{"name":"after_seq","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Return messages with a `seq` greater than this. A missing or invalid value reads as 0 (everything)."}],"responses":{"200":{"description":"Conversation state and visible messages after the cursor","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation":{"type":"object","properties":{"status":{"type":"string","enum":["open","ended"]},"resumable":{"type":"boolean","description":"Ended only because the visitor went quiet: the next message reopens it."},"handoff_requested_at":{"type":["string","null"],"format":"date-time"},"taken_over":{"type":"boolean"},"lead_id":{"type":["string","null"],"description":"The lead this conversation created, once the visitor's details are in."},"callback_requested_at":{"type":["string","null"],"format":"date-time","description":"When the visitor's callback request was stored; null without one."},"lead":{"anyOf":[{"$ref":"#/components/schemas/PublicChatLead"},{"type":"null"}],"description":"Present only when the assistant's web chat `dynamic_ui.lead_panel` or `dynamic_ui.guided` is on: what this visitor has given so far (before the lead is saved too), or null before they have given anything."},"phone_captured":{"type":"boolean","description":"Present only when the assistant's web chat `consent_capture` is on: the chat has the visitor's phone, so the consent boxes can be offered."}},"required":["status","handoff_requested_at","taken_over"]},"messages":{"type":"array","items":{"$ref":"#/components/schemas/PublicMessage"}}},"required":["conversation","messages"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-public-v1-conversations-id-updates"}},"/public/v1/conversations/{id}":{"get":{"tags":["Public chat API"],"summary":"Get a conversation's visible history","description":"Everything the visitor can see, for rebuilding the chat after a reload: status, whether a quiet conversation can be reopened, handoff state and the visible messages. `lead_name` is the first name of the captured lead, when there is one.","security":[{"conversationToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicConversation"}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"get-public-v1-conversations-id"}},"/public/v1/conversations/{id}/attachments":{"post":{"tags":["Public chat API"],"summary":"Upload a file for a message","description":"The request body is the raw file bytes (any content type), not a multipart form. Send the file name URI-encoded in `X-MLF-Filename`. The type is detected from the bytes, not the header or extension: JPEG, PNG, WebP, GIF, PDF and DOCX are accepted. Limits: 10 MB per file, 5 per message, 20 per conversation. Refused unless the assistant's web chat `attachments.enabled` is true. The file joins a message when POST /public/v1/conversations/{id}/messages names its id in `attachment_ids`.","security":[{"conversationToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."},{"name":"X-MLF-Filename","in":"header","required":false,"schema":{"type":"string"},"description":"URI-encoded file name. Defaults to `file`."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"File stored","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationAttachment"}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`attachments_disabled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conversation_ended` or `attachment_limit_reached` (20 files per conversation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`attachment_too_large` (over 10 MB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"`attachment_type_not_supported`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`attachment_empty`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`attachments_unavailable`: this deployment cannot store files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"post-public-v1-conversations-id-attachments"}},"/public/chat/attachments/{id}":{"get":{"tags":["Public chat API"],"summary":"Download an attachment","description":"Public: the signed link is the only credential. Links come from API responses (`url` on an upload or on a message's `rich.attachments`) and from webhook payloads. Links from the widget and console API last 24 hours; links in webhooks last 7 days. Both stop working sooner when the chat came from a sandbox key that is revoked or a preview link that is turned off or expires.","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Attachment id, `att_...`."},{"name":"expires","in":"query","required":true,"schema":{"type":"integer"},"description":"Link expiry, Unix seconds."},{"name":"signature","in":"query","required":true,"schema":{"type":"string"},"description":"The link's signature. Use the URL as given; do not build it yourself."}],"responses":{"200":{"description":"The file bytes, with the file's own Content-Type. Content-Disposition is inline for images and attachment for documents.","headers":{"Content-Disposition":{"schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Invalid or expired link, or the file no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-public-chat-attachments-id"}},"/public/v1/conversations/{id}/end":{"post":{"tags":["Public chat API"],"summary":"End a conversation","description":"Ends the conversation for good when the visitor closes it, and triggers its `conversation.ended` webhook and analysis. A conversation that ended only because the visitor went quiet reopens on their next message; one ended here does not.","security":[{"conversationToken":[]}],"responses":{"200":{"description":"Conversation ended","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ended"]}},"required":["status"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-end"}},"/public/v1/conversations/{id}/messages/{messageId}/feedback":{"post":{"tags":["Public chat API"],"summary":"Rate an assistant reply","description":"Thumbs up or down on one of the assistant's replies, with an optional reason for a thumbs down. Sending again replaces the verdict; `none` takes it back. Feeds the quality view in chat analytics.","security":[{"conversationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rating":{"type":"string","enum":["up","down","none"]},"reason":{"type":"string","enum":["wrong","unhelpful","incomplete","other"]}},"required":["rating"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"rating":{"type":"string","enum":["up","down","none"]}},"required":["rating"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: the message is not one of this conversation's assistant replies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`invalid_feedback`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"An assistant reply in this conversation, `msg_...`."}],"operationId":"post-public-v1-conversations-id-messages-messageid-feedback"}},"/public/v1/conversations/{id}/rating":{"post":{"tags":["Public chat API"],"summary":"Rate the conversation","description":"The visitor's 1 to 5 rating of the whole chat, with an optional comment. Sending again replaces it.","security":[{"conversationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string","maxLength":500}},"required":["rating"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"rating":{"type":"integer","minimum":1,"maximum":5}},"required":["rating"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`invalid_rating`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-rating"}},"/public/v1/conversations/{id}/presence":{"post":{"tags":["Public chat API"],"summary":"Report the visitor is still here","description":"A heartbeat while the chat is open, so a person who has taken over can see the visitor is still on the page. Presence lapses 150 seconds after the last call; send one every minute or so. No request body.","security":[{"conversationToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-presence"}},"/public/v1/conversations/{id}/consent":{"post":{"tags":["Public chat API"],"summary":"Update the visitor's analytics consent","description":"Call when the visitor answers your cookie banner while a chat is open, so later analytics follow their choice.","security":[{"conversationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"consent":{"type":"string","enum":["granted","denied","not_required"]}},"required":["consent"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"consent":{"type":"string","enum":["granted","denied","not_required"]}},"required":["consent"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`invalid_consent`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-consent"}},"/public/v1/telemetry":{"post":{"tags":["Public chat API"],"summary":"Report chat analytics events","description":"The funnel events a chat interface reports (loaded, shown, opened, typed, sent, result, and how the page view ended), up to 50 per batch, which chat analytics is built from. Optional for a custom interface. Rate limited to 120 a minute per IP address (429). Past the limiter it always answers 204 with no body, even for a body it cannot read or a key it does not know, so analytics never breaks a page; such batches are dropped.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"widget_key":{"type":"string","minLength":1,"maxLength":256,"description":"Publishable key, `pk_live_...`."},"assistant":{"type":"string","minLength":1,"maxLength":128,"description":"Assistant id; needed with a project-scoped publishable key."},"parent_origin":{"type":"string","maxLength":2048,"description":"Read as on conversation start: ignored from a browser on another site."},"visitor_id":{"type":"string","maxLength":128},"page":{"type":"string","maxLength":2048,"description":"The page URL the events happened on."},"page_view_id":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"visit_id":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,128}$","description":"The visit this page view belongs to. Stored only with analytics consent."},"visit_number":{"type":"integer","minimum":1,"maximum":1000000,"description":"Which visit this is for the visitor: 1 for the first."},"consent":{"type":"string","enum":["granted","denied","not_required"]},"widget_version":{"type":"string","maxLength":40},"referrer":{"type":"string","maxLength":2048},"landing":{"type":"string","maxLength":2048,"description":"The landing URL's query, read for campaign tags and never stored. With analytics consent, a `widget_loaded` event whose landing carries an ad click id stores which one in its `properties.click_id_type` (`gclid`, `gbraid`, `wbraid`, `fbclid`, `msclkid` or `oppref`, the first present in that order), never the id's value, so click-id coverage can be counted per page view and visit."},"test":{"type":"boolean"},"ga_client_id":{"type":"string","maxLength":128},"ga_session_id":{"type":"string","maxLength":64},"language":{"type":"string","maxLength":35,"description":"The browser's language (`navigator.language`, e.g. `en-US`). Stored only with analytics consent; the visitor's country and region come from the request itself, under the same rule."},"automated":{"type":"boolean","description":"`navigator.webdriver` was set: an automated browser, likely a bot."},"events":{"type":"array","minItems":1,"maxItems":50,"description":"Each event is checked on its own: one with a name this API does not know, or a malformed one, is dropped and the rest of the batch is stored.","items":{"type":"object","properties":{"event_id":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,128}$","description":"Unique per event, so a resent batch counts once."},"name":{"type":"string","enum":["widget_loaded","widget_shown","widget_opened","composer_typed","message_send","message_result","page_exit","link_clicked","card_shown","card_dismissed"]},"occurred_at":{"type":"integer","exclusiveMinimum":0,"description":"Milliseconds since the epoch, browser clock."},"reason":{"type":"string","enum":["proactive","visitor","api"],"description":"`widget_opened`: why the panel opened."},"page":{"type":"string","maxLength":2048},"conversation_id":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"client_message_id":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"status":{"type":"string","enum":["ok","rescued","failed"],"description":"`message_result` only."},"error_code":{"type":"string","pattern":"^[a-z0-9_]{1,64}$"},"duration_ms":{"type":"integer","minimum":0,"maximum":3600000},"first_token_ms":{"type":"integer","minimum":0,"maximum":3600000},"attempts":{"type":"integer","minimum":0,"maximum":20},"quick_reply":{"type":"boolean"},"reply_shown":{"type":"boolean"},"visible_s":{"type":"integer","minimum":0,"maximum":86400,"description":"`page_exit`: seconds the page was visible."},"scroll":{"type":"integer","enum":[0,25,50,75,100],"description":"`page_exit`: the deepest scroll reached, as a percentage of the page."},"closed":{"type":"boolean","description":"`page_exit`: the panel opened and the visitor closed it. A card put away is `card_dismissed`, not a close."},"banner":{"type":"boolean","description":"`page_exit`: a cookie or consent banner was up during the page view."},"viewport":{"type":"string","enum":["s","m","l"],"description":"`widget_loaded`: the window width: `s` under 480px, `m` under 1024px, `l` wider."},"card":{"type":"string","enum":["nudge","continue","follow_up","teaser"],"description":"`card_shown` and `card_dismissed`: which card."},"rule":{"type":"string","maxLength":128,"description":"`card_shown`: the matched `url_rules` pattern; absent for the assistant-wide opener."},"answers":{"type":"integer","minimum":0,"maximum":20,"description":"`card_shown`: how many answers the card offered."},"from":{"type":"string","enum":["launcher","nudge","continue","continue_fresh","follow_up","teaser"],"description":"`widget_opened` with reason `visitor`: what the visitor opened the chat with."},"source":{"type":"string","enum":["typed","reply","starter","nudge","continue","contact"],"description":"`message_send`: how the message was written or picked. `quick_reply` is still sent for older consumers."},"channel":{"type":"string","enum":["email","phone"],"description":"`message_send` from the contact card: the channel given."},"switched":{"type":"boolean","description":"`message_send` from the contact card: the visitor changed channel."},"invalid":{"type":"integer","minimum":0,"maximum":20,"description":"`message_send` from the contact card: submits refused as invalid before this one."},"closed_after_s":{"type":"integer","minimum":0,"maximum":86400,"description":"`page_exit`: seconds between the panel opening and the visitor closing it."},"auto_open":{"type":"string","enum":["opened","off","url_rule","already_used","left_early","chat_open","hidden","crawler","claim_refused","frame_not_ready","already_chatting","visitor_typing","seen_before","consent_held","not_fired"],"description":"`page_exit`: whether the proactive opener fired, and if not, why: `off` (no opener), `url_rule` (no rule matched the page), `already_used` (used or closed earlier in the visit), `left_early` (the page ended before the delay), `chat_open`, `hidden` (the site hid the chat), `crawler`, `claim_refused` (the once-per-visit claim was refused for another reason, such as a tab not in view), `frame_not_ready` (the chat frame never said ready while the page was in view), `already_chatting` (the visitor had already written in the chat), `visitor_typing` (a draft was in the composer), `seen_before` (shown or dismissed within `repeat_after_days`), `consent_held` (a card was ready but waited while a cookie banner was up; a card shown later still reports `opened`), or `not_fired` (unknown; older widgets send it for all of these). Send one `page_exit` per page view under one `event_id`; a later report with more visible time replaces it."}},"required":["event_id","name"]}}},"required":["widget_key","events"]}}}},"responses":{"204":{"description":"Accepted (or ignored). No body."},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-public-v1-telemetry"}},"/public/v1/conversations/{id}/contact-consent":{"post":{"tags":["Public chat API"],"summary":"Record the visitor's consent to be contacted","description":"The boxes the visitor ticked, from the widget config's `contact_consent`, once the chat has their phone. Each becomes a grant in the consent ledger for the chat's phone with the wording shown, the page, the visitor's address and user agent, the seller and the lead and conversation. Every tick must be an option the assistant offers, in the project's current wording version, or nothing is recorded. An empty list records nothing.","security":[{"conversationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"consents":{"type":"array","maxItems":6,"items":{"type":"object","properties":{"channel":{"type":"string","enum":["whatsapp","sms","voice_human"]},"purpose":{"type":"string","enum":["service","marketing"]},"wording_version":{"type":"integer","minimum":1}},"required":["channel","purpose","wording_version"]}}},"required":["consents"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recorded":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string"},"purpose":{"type":"string"},"wording_version":{"type":"integer"},"event_id":{"type":"string"}}}}},"required":["recorded"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`phone_required`: the chat has no phone yet; `wording_outdated`: the wording changed, reload the settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`invalid_consent`, or `consent_not_offered`: the assistant does not offer that channel and purpose","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-contact-consent"}},"/public/v1/conversations/{id}/link-follow-up":{"post":{"tags":["Public chat API"],"summary":"Ask for a follow-up on a linked page","description":"The visitor opened a page the latest assistant reply linked and has stayed on it without replying: the assistant writes one short message about that page, stored with `rich.metadata.follow_up` (`of`: the reply that linked it, `page`). One model call with no tools, on the chat's own model and prompt. Allowed once per reply, only while the chat can be resumed, nobody has taken it over or been asked for, `message_id` is the latest message and an assistant reply under 30 minutes old, and one of its links (markdown or link button) has the page's path. Any other case is a 409 and nothing is written.","security":[{"conversationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","description":"The assistant reply whose link the visitor opened."},"page":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"title":{"type":"string","maxLength":200}},"required":["url","title"]},"page_view_id":{"type":"string"}},"required":["message_id","page"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/PublicMessage"}},"required":["message"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_web_chat`, `conversation_ended`, `taken_over`, `handoff_in_progress`, `already_followed_up`, `not_latest_message`, `link_not_found`, `link_too_old`, `conversation_full`, `llm_not_configured` or `turn_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`invalid_follow_up`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`key_quota_exceeded`: the publishable key has used a budget shared by every visitor of your site: 300 new conversations an hour, 30 an hour from one IP address, or 5,000 assistant replies a day. `rate_limited` is the ordinary per-address limit. Both carry `Retry-After`, in seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`llm_error`: the model did not answer; nothing was stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-link-follow-up"}},"/public/v1/conversations/{id}/voice":{"post":{"tags":["Public chat API"],"summary":"Start a voice session","description":"Lets the visitor talk to the assistant through their microphone, in the same conversation. Available when the assistant's web chat `voice.enabled` is on (the widget config then has `voice`), never in a preview link's chat. Join the LiveKit room at `url` with `token` before `expires_at`, publish the microphone and play the agent's audio. The agent knows the conversation so far and carries on from it. Live captions arrive as LiveKit text streams on topic `lk.transcription`: the visitor's words come from identity `web_{voice_session_id}`, the assistant's from the agent, with attributes `lk.segment_id` and `lk.transcription_final`. The session ends after `max_seconds`, when either side hangs up, or when the browser never joins. The spoken turns then join the conversation as messages with `rich.metadata.channel` `voice` (read them through the updates route), and the conversation is checked for a lead. One session per conversation at a time.","security":[{"conversationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"consent":{"type":"object","properties":{"microphone":{"type":"boolean","enum":[true]}},"required":["microphone"],"description":"The visitor agreed to use their microphone. Ask before you call this."}},"required":["consent"]}}}},"responses":{"201":{"description":"Voice session started","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voice_session_id":{"type":"string","description":"Keep it to read or end the session."},"url":{"type":"string","description":"The LiveKit server to join, `wss://...`."},"token":{"type":"string","description":"A room token for this browser only."},"expires_at":{"type":"string","format":"date-time","description":"Join before this. The session itself then runs up to `max_seconds`."},"max_seconds":{"type":"integer","description":"The session's length cap, 60 to 600 seconds."}},"required":["voice_session_id","url","token","expires_at","max_seconds"]}},"required":["data"]}}}},"400":{"description":"`consent_required`: the body did not carry `consent.microphone: true`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`voice_disabled` (voice is off for the assistant, or this is a preview chat) or `origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`voice_session_active` (one is already running: end it first; `voice_session_id` names it when known), `conversation_ended`, or `conversation_taken_over` (a person is answering)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`key_quota_exceeded`: the publishable key has started 60 voice sessions this hour, 10 from this IP address, or used its 300 voice minutes for the UTC day. `voice_busy`: the key already has 5 sessions running. `rate_limited`: the ordinary per-address limit. All carry `Retry-After`, in seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`voice_unavailable`: voice calls cannot be placed right now. When the cause is passing it carries `Retry-After` (5 seconds); without the header, voice is not set up on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-voice"}},"/public/v1/conversations/{id}/voice/{voiceSessionId}":{"get":{"tags":["Public chat API"],"summary":"Get a voice session","description":"Whether the session is still connecting, running or over, and why it ended. Only sessions of this conversation are found.","security":[{"conversationToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voice_session_id":{"type":"string","description":"The voice session's id, which is also its call's id."},"status":{"type":"string","enum":["connecting","active","ended"]},"ended_reason":{"type":["string","null"],"description":"Null until the session ends. Then the call's ended reason (for example `customer_hangup`, `assistant_ended` or `max_duration`), `visitor_ended` when you ended it through this API, `not_joined` when the browser never joined, or `expired`."},"max_seconds":{"type":["integer","null"],"description":"The session's length cap, in seconds."}},"required":["voice_session_id","status","ended_reason","max_seconds"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such voice session in this conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."},{"name":"voiceSessionId","in":"path","required":true,"schema":{"type":"string"},"description":"The `voice_session_id` that starting the session returned."}],"operationId":"get-public-v1-conversations-id-voice-voicesessionid"}},"/public/v1/conversations/{id}/voice/{voiceSessionId}/end":{"post":{"tags":["Public chat API"],"summary":"End a voice session","description":"Hangs up for both sides. Safe to repeat: a session that already ended answers with its state. The conversation stays open for typing.","security":[{"conversationToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"voice_session_id":{"type":"string","description":"The voice session's id, which is also its call's id."},"status":{"type":"string","enum":["connecting","active","ended"]},"ended_reason":{"type":["string","null"],"description":"Null until the session ends. Then the call's ended reason (for example `customer_hangup`, `assistant_ended` or `max_duration`), `visitor_ended` when you ended it through this API, `not_joined` when the browser never joined, or `expired`."},"max_seconds":{"type":["integer","null"],"description":"The session's length cap, in seconds."}},"required":["voice_session_id","status","ended_reason","max_seconds"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such voice session in this conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`voice_unavailable`: the call could not be ended just now and may still be running. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."},{"name":"voiceSessionId","in":"path","required":true,"schema":{"type":"string"},"description":"The `voice_session_id` that starting the session returned."}],"operationId":"post-public-v1-conversations-id-voice-voicesessionid-end"}},"/public/v1/conversations/{id}/whatsapp-ref":{"post":{"tags":["Public chat API"],"summary":"Get the Continue on WhatsApp link","description":"The `wa.me` link for the assistant's WhatsApp number, its text the configured prefill (or \"Hi, I was chatting on your website.\") followed by \"(ref CODE)\". The first WhatsApp message carrying the code links the WhatsApp conversation to this one and copies this chat's attribution as far as its analytics consent allows. The code lasts 7 days and is reused until then, so calling again returns the same link. No request body.","security":[{"conversationToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}},"required":["url","expires_at"]}},"required":["data"]}}}},"401":{"description":"Missing, wrong or expired conversation token, or a conversation id the token does not belong to (`unauthorized`; an unknown id is a 401, never a 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`whatsapp_not_configured`: the assistant offers no WhatsApp number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`. An id the token does not belong to answers 401."}],"operationId":"post-public-v1-conversations-id-whatsapp-ref"}},"/api/integrations/whatsapp/connections":{"get":{"tags":["WhatsApp"],"responses":{"200":{"description":"Connections","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppConnection"}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-connections","summary":"List WhatsApp accounts and numbers","description":"Every connected WhatsApp Business Account with its numbers, the assistant each number is assigned to, and counts of replies and turns that failed. Credentials are never returned. Needs an org-wide key.","security":[{"apiKey":[]}]},"post":{"tags":["WhatsApp"],"responses":{"201":{"description":"Connected","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppConnection"}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-connections","summary":"Connect a WhatsApp Business account","description":"Checks the credentials with Meta, stores them encrypted and imports the account's phone numbers, unassigned. Then subscribe the account to its callback and assign numbers to assistants. Needs an org-wide key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","waba_id","credentials"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Your label for the account."},"waba_id":{"type":"string","pattern":"^[0-9]+$","description":"The WhatsApp Business Account id (digits)."},"api_version":{"type":"string","default":"v25.0","pattern":"^v[0-9]+\\.0$","description":"Graph API version."},"credentials":{"type":"object","required":["access_token","app_secret","verify_token"],"description":"From your Meta app. Write-only: stored encrypted and never returned.","properties":{"access_token":{"type":"string","minLength":1,"maxLength":8192,"writeOnly":true,"description":"A system user access token with WhatsApp permissions."},"app_secret":{"type":"string","minLength":1,"maxLength":256,"writeOnly":true,"description":"Verifies Meta's callback signatures."},"verify_token":{"type":"string","minLength":16,"maxLength":256,"writeOnly":true,"description":"Any string you choose; Meta echoes it when it verifies the callback."}}}}}}}},"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}":{"patch":{"tags":["WhatsApp"],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppConnection"}},"required":["data"]}}}},"400":{"description":"Invalid body, or resuming would route a number to an assistant whose chat model cannot answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"patch-integrations-whatsapp-connections-id","summary":"Update a WhatsApp connection","description":"`enabled: false` pauses every number on the account; `true` resumes. New `credentials` are checked with Meta before they replace the stored ones. A disconnected account needs `credentials` to resume (409 `whatsapp_credentials_required`).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"enabled":{"type":"boolean"},"credentials":{"type":"object","required":["access_token","app_secret","verify_token"],"description":"From your Meta app. Write-only: stored encrypted and never returned.","properties":{"access_token":{"type":"string","minLength":1,"maxLength":8192,"writeOnly":true,"description":"A system user access token with WhatsApp permissions."},"app_secret":{"type":"string","minLength":1,"maxLength":256,"writeOnly":true,"description":"Verifies Meta's callback signatures."},"verify_token":{"type":"string","minLength":16,"maxLength":256,"writeOnly":true,"description":"Any string you choose; Meta echoes it when it verifies the callback."}}}}}}}},"security":[{"apiKey":[]}]},"delete":{"tags":["WhatsApp"],"responses":{"200":{"description":"Disconnected","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"disconnected":{"type":"boolean","enum":[true]}},"required":["disconnected"]}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"delete-integrations-whatsapp-connections-id","summary":"Disconnect a WhatsApp account","description":"Disconnects the account: messages stop being answered and the stored credentials are erased. Numbers, assignments and conversation history stay, so reconnecting with new credentials picks up where it left off.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/embedded/retry":{"post":{"tags":["WhatsApp"],"responses":{"200":{"description":"The connection; `embedded_signup.failed_step` says which step to retry","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppConnection"}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_not_embedded_signup` (connected by hand) or `whatsapp_disconnected`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-connections-id-embedded-retry","summary":"Retry the remaining Embedded Signup steps","description":"Reruns the steps still pending (subscribe, register, sync); steps already done are not repeated, and each is safe to run again. Answers with the connection and, if a step failed again, which one. Admin role; needs an org-wide key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/numbers/{numberId}":{"put":{"tags":["WhatsApp"],"responses":{"200":{"description":"Assigned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppNumber"}},"required":["data"]}}}},"400":{"description":"Invalid body, or the assistant's chat model has no chat adapter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection); or `assistant_archived` when the assistant is archived (restore it first; a number already assigned to it keeps it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"put-integrations-whatsapp-connections-id-numbers-numberid","summary":"Assign a WhatsApp number to an assistant","description":"Routes the number's WhatsApp messages to an assistant (`assistant_id: null` unassigns it), optionally pausing just this number. The assistant answers with its web chat model, so that model must be one chat supports.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."},{"name":"numberId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp number id, from the connection's `numbers`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_id":{"type":["string","null"],"minLength":1,"description":"Assistant id, or null to unassign. Omitted keeps the current one."},"enabled":{"type":"boolean","description":"False pauses this number only."},"mode":{"type":"string","enum":["live","test"]},"ad_instructions":{"type":["string","null"],"maxLength":2000,"description":"Instructions for people who arrive from a Click-to-WhatsApp ad, added to the assistant's prompt for those conversations only. Empty or null clears them; omitted keeps them."}}}}}},"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/operator-alerts":{"get":{"tags":["WhatsApp"],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppOperatorAlerts"}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-connections-id-operator-alerts","summary":"Read an account's operator alert settings","description":"Who is alerted on WhatsApp when a chat in the organization (web chat or WhatsApp, live chats only) asks for a person, from which number and with which template. Off and empty until saved. Viewer role; needs an org-wide key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"security":[{"apiKey":[]}]},"put":{"tags":["WhatsApp"],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppOperatorAlerts"}},"required":["data"]}}}},"400":{"description":"`whatsapp_alert_number_invalid`, `whatsapp_alert_template_invalid`, `whatsapp_alert_staff_numbers_invalid`, `whatsapp_alert_incomplete` (with a `message`), or `invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"put-integrations-whatsapp-connections-id-operator-alerts","summary":"Save an account's operator alert settings","description":"Replaces the settings. `number_id` must be one of this account's numbers; the template must be an approved utility template on this account whose body takes at most 3 values (customer, assistant, chat link, in that order) and whose header and buttons take none; staff numbers are E.164, unique, at most 10. Turning alerts on needs all three. Each staff number gets one alert per request; requests more than 15 minutes old when first seen are not alerted; staff numbers that opted out of the sending number are skipped. Admin role; needs an org-wide key; audited.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"number_id":{"type":["string","null"]},"template_name":{"type":["string","null"]},"template_language":{"type":["string","null"]},"staff_numbers":{"type":"array","items":{"type":"string"},"maxItems":10}}}}}},"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/operator-alerts/test":{"post":{"tags":["WhatsApp"],"responses":{"200":{"description":"One result per staff number","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"staff_number":{"type":"string"},"status":{"type":"string","enum":["sent","failed","skipped"]},"error":{"type":["string","null"],"description":"Meta's code, or `whatsapp_contact_opted_out` when skipped."}}}}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_disconnected`, `whatsapp_alert_incomplete` (save a number, template and staff numbers first), or `whatsapp_alert_template_invalid`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-connections-id-operator-alerts-test","summary":"Send a test operator alert","description":"Sends the saved template once to each staff number now, with sample values and a link to Chats, whether alerts are on or off. Admin role; needs an org-wide key; audited.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/subscribe":{"post":{"tags":["WhatsApp"],"responses":{"200":{"description":"Subscribed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"subscribed":{"type":"boolean","enum":[true]}},"required":["subscribed"]}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-connections-id-subscribe","summary":"Subscribe an account to its message callback","description":"Tells Meta to post this account's messages to its callback, then Meta verifies it with your `verify_token`. Use the public API origin with the connection's `webhook_path` (`/public/whatsapp/webhooks/{id}`); the older `/whatsapp/webhooks/{id}` path is also accepted. `callback_url` must be HTTPS with no query, fragment or credentials, at one of those paths (otherwise 400 `whatsapp_public_https_webhook_required`).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["callback_url"],"properties":{"callback_url":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"}}}}}},"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/sync":{"post":{"tags":["WhatsApp"],"responses":{"200":{"description":"The account's numbers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppNumber"}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-connections-id-sync","summary":"Sync an account's phone numbers","description":"Fetches the account's current phone numbers from Meta, and each one's quality rating, messaging limit tier, status and display name review (a number Meta will not describe keeps what it had). New numbers arrive unassigned; existing ones keep their assistant.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/templates":{"get":{"tags":["WhatsApp"],"responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppTemplate"}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-connections-id-templates","summary":"List an account's message templates","description":"The account's message templates as last synced from Meta (every hour, on a status callback for a template not seen yet, and on demand), any status. Needs an org-wide key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"security":[{"apiKey":[]}]},"post":{"tags":["WhatsApp"],"responses":{"201":{"description":"Submitted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppTemplate"}},"required":["data"]}}}},"400":{"description":"Invalid body, placeholders not numbered in order, or missing examples","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_template_exists` (same name and language) or `whatsapp_disconnected`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused it: `meta_<code>`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-connections-id-templates","summary":"Create a message template","description":"Submits a new text template to Meta for review and stores it as Meta answered, usually `PENDING`; approval or rejection arrives by Meta's status callback and the hourly sync. Placeholders are numbered (`{{1}}`, `{{2}}`...) and each needs an example. Meta may settle on a different category than the one asked. Audited. Admin; needs an org-wide key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","language","category","body"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9_]{1,512}$","description":"Lowercase letters, digits and underscores."},"language":{"type":"string","description":"Template language code, e.g. `en_US` or `hi`."},"category":{"type":"string","enum":["UTILITY","MARKETING"]},"header":{"type":"string","minLength":1,"maxLength":60,"description":"Text header, at most one placeholder `{{1}}`."},"header_example":{"type":"string","maxLength":60,"description":"Required when the header has a placeholder."},"body":{"type":"string","minLength":1,"maxLength":1024,"description":"With `{{1}}` to `{{n}}` in order, none skipped."},"body_examples":{"type":"array","items":{"type":"string"},"description":"One non-empty sample value per body placeholder, in order."},"buttons":{"type":"array","maxItems":10,"description":"Quick replies and at most 2 URL buttons.","items":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL"]},"text":{"type":"string","minLength":1,"maxLength":25},"url":{"type":"string","maxLength":2000,"description":"URL buttons: https, optionally ending in `{{1}}`."},"example":{"type":"string","maxLength":2000,"description":"Required when the URL ends in `{{1}}`."}}}}}}}}},"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/templates/{name}":{"delete":{"tags":["WhatsApp"],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"deleted":{"type":"integer","description":"How many languages were removed here."}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found` (no such connection) or `whatsapp_template_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_disconnected`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused it: `meta_<code>`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"delete-integrations-whatsapp-connections-id-templates-name","summary":"Delete a message template","description":"Deletes the template at Meta, every language of the name, then here. Messages already queued with it fail when sent. Audited. Admin; needs an org-wide key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."},{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"Template name."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/{id}/templates/sync":{"post":{"tags":["WhatsApp"],"responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppTemplate"}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-connections-id-templates-sync","summary":"Sync an account's message templates","description":"Fetches the account's templates from Meta now: new ones are added, changed ones updated, and ones deleted in Meta removed. Admin; needs an org-wide key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp connection id."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/connections/embedded":{"post":{"tags":["WhatsApp"],"responses":{"201":{"description":"The connection; `embedded_signup.failed_step` says which step to retry","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppConnection"}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_embedded_signup_disabled` (the platform app is not configured) or `whatsapp_already_connected`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the code exchange or the token: `{error: meta_<code>, step: exchange | create, message}`, the same `error` codes as the other WhatsApp routes' 422s, with `step` beside it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-connections-embedded","summary":"Connect an account through Embedded Signup","description":"Exchanges the code Meta's Embedded Signup returned for a business token, creates the connection (same uniqueness rules as connecting by hand; Meta signs its callbacks with the platform app's secret), then subscribes the account to its callback, registers the number (with a two-step verification PIN kept in the encrypted credentials) and syncs numbers. A failed exchange or creation creates nothing (422 with `step`: `exchange` or `create`; 400 `whatsapp_unknown_number` for a `phone_number_id` the account does not list). The organization's own disconnected connection for the same account is taken over in place. A step after creation that fails keeps the connection and the other steps still run: the response is still 201 and `embedded_signup` names the first failed step and Meta's error code; retry with `.../embedded/retry`. Admin role; needs an org-wide key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","waba_id","callback_url"],"properties":{"code":{"type":"string","minLength":1,"maxLength":2048,"writeOnly":true,"description":"From Meta's Embedded Signup popup."},"waba_id":{"type":"string","pattern":"^[0-9]+$","description":"From the popup's session info."},"coexistence":{"type":"boolean","default":false,"description":"Set true for WhatsApp Business app onboarding. Keeps the app's existing registration and skips Cloud API registration, including on retries."},"phone_number_id":{"type":"string","pattern":"^[0-9]+$","description":"The number to register, from the popup's session info. Omitted: registration is skipped."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Your label; defaults to `WhatsApp <waba_id>`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://","description":"The public API origin (or it plus `/public/whatsapp/webhooks`): HTTPS, no query, fragment or credentials. The connection's own webhook path is added to it."}}}}}},"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/contacts/{contactId}/marketing-opt-in":{"put":{"tags":["WhatsApp"],"responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppContact"}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"put-integrations-whatsapp-contacts-contactid-marketing-opt-in","summary":"Record or withdraw marketing consent","description":"Records that the person agreed to marketing templates (`opted_in: true`) and where that consent came from, or withdraws it. Audited. It does not undo a STOP: an opted-out contact gets no template until they send START. Member role; needs an org-wide key.","parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp contact id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["opted_in","source"],"properties":{"opted_in":{"type":"boolean"},"source":{"type":"string","minLength":1,"maxLength":200,"description":"Where the consent came from."}}}}}},"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/conversations/{conversationId}/contact":{"get":{"tags":["WhatsApp"],"responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/WhatsAppContact"},{"type":"null"}]}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-conversations-conversationid-contact","summary":"Get a conversation's WhatsApp contact","description":"The sender's contact on this number: when they wrote, whether they opted out (STOP), and any recorded marketing opt-in with the name of the user who recorded it. `data` is null for a sender not recorded yet. Viewer role.","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp conversation id."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/conversations/{conversationId}/deliveries":{"get":{"tags":["WhatsApp"],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"message_id":{"type":"string"},"status":{"type":"string","enum":["failed","unknown","pending","sending","sent","delivered","read"]},"error":{"type":["string","null"],"description":"`meta_<code>` when failed."},"updated_at":{"type":"string","format":"date-time"},"parts":{"type":"integer"}}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-conversations-conversationid-deliveries","summary":"Delivery state of a conversation's messages","description":"Per message sent on WhatsApp in this conversation: its delivery state (the least advanced of the parts it was sent as; a failed part makes it `failed`), Meta's error code when it failed, when it last changed and how many parts it was sent as. Messages never sent on WhatsApp are not listed. Viewer role; a project key reaches its own project's conversations.","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp conversation id."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/conversations/{conversationId}/template":{"post":{"tags":["WhatsApp"],"responses":{"201":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The transcript message id."},"conversation_id":{"type":"string","description":"Where it was added: a new conversation if the old one had ended."},"role":{"type":"string","enum":["agent"]},"content":{"type":"string","description":"The rendered template text."},"seq":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"Invalid body, parameter counts that do not match the template, or a template with a media header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found` (no such WhatsApp conversation in scope) or `whatsapp_template_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_template_not_approved`, `whatsapp_contact_opted_out`, `whatsapp_marketing_opt_in_required`, `whatsapp_disconnected` or `client_message_id_reused`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-conversations-conversationid-template","summary":"Send a template message","description":"Sends an approved template to the conversation's sender. Works when the 24-hour service window has closed (that is what templates are for) and needs no takeover; the assistant keeps answering their reply unless the chat is taken over. The rendered text is added to the transcript as an operator message carrying the template; the delivery worker sends it. If the sender's conversation has ended, a new conversation is started for the same number and sender. Refused for a contact who opted out (STOP), and for a marketing template without a recorded marketing opt-in. Member role; a project key reaches its own project's conversations.","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp conversation id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","language"],"properties":{"name":{"type":"string","minLength":1,"maxLength":512},"language":{"type":"string","minLength":1,"maxLength":32,"description":"Template language code, e.g. `en_US`."},"parameters":{"type":"object","description":"Values for the template's placeholders, in order: as many as the template's `parameters` counts say. Each is non-empty text without new lines, tabs or more than four spaces in a row; header values up to 60 characters, body up to 1,024, button up to 2,000.","properties":{"header":{"type":"array","items":{"type":"string"}},"body":{"type":"array","items":{"type":"string"}},"buttons":{"type":"array","description":"`buttons[i]` fills the i-th button (only URL buttons take a value).","items":{"type":"array","items":{"type":"string"}}}}},"agent":{"type":"object","description":"Who is sending, for an API key. A signed-in user is recorded as themselves.","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"client_message_id":{"type":"string","minLength":1,"maxLength":200,"description":"Set per send; a retry with the same id returns the original instead of sending again."}}}}}},"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/conversations/{conversationId}/templates":{"get":{"tags":["WhatsApp"],"responses":{"200":{"description":"Approved templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppTemplate"}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such WhatsApp conversation in scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-conversations-conversationid-templates","summary":"List the templates a conversation can be sent","description":"The approved templates of the account the conversation's number belongs to, with how many values each part takes. Member role; a project key sees its own project's conversations.","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp conversation id."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/embedded-signup":{"get":{"tags":["WhatsApp"],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"enabled":{"type":"boolean"},"app_id":{"type":["string","null"]},"config_id":{"type":["string","null"]},"graph_api_version":{"type":"string"}}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such connection or number in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-embedded-signup","summary":"Embedded Signup settings","description":"What the console needs to open Meta's Embedded Signup: the platform app id, its configuration id and the Graph API version. `enabled` is false (and the ids null) unless the platform app is configured. The app secret is never returned. Admin role; needs an org-wide key.","security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/numbers/{numberId}/links":{"get":{"tags":["WhatsApp"],"responses":{"200":{"description":"Links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppLink"}}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such number in your organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-numbers-numberid-links","summary":"List a number's campaign links","description":"The number's campaign links that are not archived, newest first, each with its `wa.me` URL and how many WhatsApp conversations it started. Needs an org-wide key.","parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp number id, from the connection's `numbers`."}],"security":[{"apiKey":[]}]},"post":{"tags":["WhatsApp"],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppLink"}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such number in your organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-integrations-whatsapp-numbers-numberid-links","summary":"Create a campaign link","description":"A named link that opens WhatsApp to this number with `prefill` (default \"Hi\") followed by \"(ref CODE)\". A conversation whose first message carries the code records the link and its utm tags as its first touch (`attribution.first.whatsapp_link_id`). Admin, org-wide key; audited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppLinkInput","required":["name"]}}}},"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp number id, from the connection's `numbers`."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/numbers/{numberId}/links/{linkId}":{"patch":{"tags":["WhatsApp"],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppLink"}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such link on this number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"patch-integrations-whatsapp-numbers-numberid-links-linkid","summary":"Update a campaign link","description":"Changes its name, prefill or tags; the code stays. Null or empty clears an optional field. Admin; audited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppLinkInput"}}}},"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp number id, from the connection's `numbers`."},{"name":"linkId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign link id (`wal_...`)."}],"security":[{"apiKey":[]}]},"delete":{"tags":["WhatsApp"],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WhatsAppLink"}},"required":["data"]}}}},"400":{"description":"`invalid_request`: the body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`org_scope_required` (needs an org-wide key; project keys get 403) or the role is too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such link on this number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`whatsapp_already_connected`, `whatsapp_credentials_required`, `whatsapp_disconnected`, or on sync `whatsapp_number_already_connected` (a number already belongs to another connection)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Meta refused the request (`meta_<Meta error code>`, or `meta_http_<status>`), or could not be reached (`meta_unreachable`, which says nothing about whether Meta acted on it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"delete-integrations-whatsapp-numbers-numberid-links-linkid","summary":"Archive a campaign link","description":"Hides it from the list. Its code still resolves, so a printed QR code keeps attributing, and conversations it started keep their attribution. Admin; audited.","parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string"},"description":"WhatsApp number id, from the connection's `numbers`."},{"name":"linkId","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign link id (`wal_...`)."}],"security":[{"apiKey":[]}]}},"/api/integrations/whatsapp/numbers/templates":{"get":{"tags":["WhatsApp"],"summary":"List project WhatsApp numbers and approved templates","description":"Viewer read for reminder pickers. Enabled live numbers on enabled accounts with stored credentials, assigned to an assistant in this project. Templates are the last synced approved versions; supported indicates whether this API can send them. Unknown or inaccessible projects return an empty list. No provider request is made.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Required for an org-wide key; a project key defaults to its project."}],"responses":{"200":{"description":"Connected numbers with approved templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppNumberTemplates"}}}}},"required":["data"]}}}},"400":{"description":"Project required or conflicts with the project key"},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations-whatsapp-numbers-templates","security":[{"apiKey":[]}]}},"/api/integrations":{"get":{"tags":["Provider credentials"],"summary":"List provider credentials","description":"Which providers have a credential stored for the project (model, speech and telephony providers), with when it was saved; the secrets themselves are never returned. Credentials belong to one project; an org-wide key must name `project_id`.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"The project. Required with an org-wide key."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Integration"}}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-integrations","security":[{"apiKey":[]}]}},"/api/integrations/{provider}":{"put":{"tags":["Provider credentials"],"summary":"Save a provider credential","description":"Saves your own account's key for a provider, so assistants in the project run on it. It is stored encrypted and never returned. Where the provider can be checked, the key is tried first and a refused key is not stored (422). `verified: false` means it could not be checked; it is stored anyway.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationCreate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IntegrationStatus"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"credential_rejected: the provider refused the key. Nothing is stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"},"description":"Provider slug, for example `openai`, `perplexity`, `deepgram`, `elevenlabs`, `twilio`."}],"operationId":"put-integrations-provider","security":[{"apiKey":[]}]},"delete":{"tags":["Provider credentials"],"summary":"Remove a provider credential","description":"Deletes the project's stored key for this provider.","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"},"description":"Provider slug, for example `openai`, `perplexity`, `deepgram`, `elevenlabs`, `twilio`."},{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"The project. Required with an org-wide key."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IntegrationDeleteResult"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"delete-integrations-provider","security":[{"apiKey":[]}]}},"/api/registry":{"get":{"tags":["Voices and models"],"summary":"Get the provider and model registry","description":"Static catalog aligned with the supported LiveKit Agents SDK version.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderRegistry"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-registry","security":[{"apiKey":[]}]}},"/api/tts/{provider}/library":{"get":{"tags":["Voices and models"],"summary":"Browse a provider's shared voice library","description":"Loads a page from a provider's public voice library using the project's stored credential.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderLibraryResponse"}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"project_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"gender","in":"query","required":false,"schema":{"type":"string"}},{"name":"language","in":"query","required":false,"schema":{"type":"string"}}],"operationId":"get-tts-provider-library","security":[{"apiKey":[]}]}},"/api/tts/{provider}/library/add":{"post":{"tags":["Voices and models"],"summary":"Add a shared voice to the provider account","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddLibraryVoiceRequest"}}}},"responses":{"200":{"description":"Voice added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddLibraryVoiceResponse"}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"Provider request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"project_id","in":"query","required":false,"schema":{"type":"string"}}],"operationId":"post-tts-provider-library-add","security":[{"apiKey":[]}]}},"/api/tts/{provider}/models":{"get":{"tags":["Voices and models"],"summary":"Discover provider models","description":"Loads current TTS models, Anthropic models, or Bedrock chat models using tenant credentials or the platform connection.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderModelsResponse"}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"project_id","in":"query","required":false,"schema":{"type":"string"}}],"operationId":"get-tts-provider-models","security":[{"apiKey":[]}]}},"/api/tts/{provider}/voices":{"get":{"tags":["Voices and models"],"summary":"Discover a provider's TTS voices","description":"Loads the current voice inventory from the provider using the project's stored credential.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderVoicesResponse"}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"project_id","in":"query","required":false,"schema":{"type":"string"}}],"operationId":"get-tts-provider-voices","security":[{"apiKey":[]}]}},"/api/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","description":"Web chat and WhatsApp conversations, newest first by default, one cursor page at a time. Each row is the conversation without its messages; fetch one by id for the transcript. Sandbox conversations are left out unless `include_test=true`.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's conversations (an org-wide key sees every project by default)."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants' conversations. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","ended"]},"description":"Only open or only ended conversations."},{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"Case-insensitive literal substring across conversation id, lead name/email/phone, analysis summary and visitor messages."}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or after this time (ISO 8601 with an offset)."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or before this time (ISO 8601 with an offset)."},{"name":"engagement","description":"`engaged`: the visitor replied at least once. `no_reply`: they never did.","in":"query","required":false,"schema":{"type":"string","enum":["engaged","no_reply","all"],"default":"all"}},{"name":"handoff","in":"query","required":false,"description":"requested: a handoff was asked for. pending: asked for, nobody has taken over, chat open. answered: a human took over at or after the request. missed: the chat ended before anyone took over (never an abandoned chat). missed_in_hours: missed, asked while advisors were said to be available. out_of_hours: asked while advisors were said to be unavailable (outside working hours). active: someone holds the seat now. taken_over: a human took over at least once, asked for or not. abandoned: a human took over and then left the visitor waiting (human_outcome abandoned).","schema":{"type":"string","enum":["requested","pending","answered","missed","missed_in_hours","out_of_hours","active","taken_over","abandoned"]}},{"name":"callback","in":"query","required":false,"description":"requested: the visitor left a callback request. open: requested and not yet marked called. done: marked called (PUT /conversations/{id}/callback).","schema":{"type":"string","enum":["requested","open","done"]}},{"name":"include_test","in":"query","required":false,"description":"Sandbox chats (metadata.test, e.g. the console's sandbox chat) are left out unless this is true. Ignored when `mode` is given.","schema":{"type":"boolean","default":false}},{"name":"mode","in":"query","required":false,"description":"Which chats to include, by the mode the server gave each. Absent: sandbox and preview chats are left out, and so are live chats a page marked as a test, as before. live: every live-mode chat, including those a page marked as a test. test: sandbox chats (stored mode `test`). preview: preview chats. all: every chat.","schema":{"type":"string","enum":["live","test","preview","all"]}},{"name":"traffic","in":"query","required":false,"description":"Comma-separated subset of real, sandbox and test: only chats of those kinds. When given it replaces the default view (and `include_test`); an explicit `mode` still narrows. Absent: the default view, unchanged.","schema":{"type":"string","examples":["real,sandbox"]}},{"name":"needs_review","in":"query","required":false,"description":"When true, only conversations whose analysis flagged the human advisor's replies with severity 2 or more (see ConversationAnalysis.human_review).","schema":{"type":"boolean"}},{"name":"intent","in":"query","required":false,"description":"Only chats whose outcome label has this intent (ConversationAnalysis outcome).","schema":{"type":"string","enum":["new_enquiry","information","existing_customer","human_request","job_or_vendor","spam_or_test","other","unknown"]}},{"name":"exclude_intent","in":"query","required":false,"description":"Exclude chats with this latest analysis intent; keep chats without analysis or intent.","schema":{"type":"string","enum":["new_enquiry","information","existing_customer","human_request","job_or_vendor","spam_or_test","other","unknown"]}},{"name":"goal","in":"query","required":false,"description":"Only chats whose outcome label says whether the visitor got what they came for.","schema":{"type":"string","enum":["met","partly_met","not_met","unknown"]}},{"name":"friction","in":"query","required":false,"description":"Only chats whose outcome label lists this friction sign.","schema":{"type":"string","enum":["contact_pushed","price_not_given","question_unanswered","repeated_question","wrong_or_unclear_answer","forced_choice","bot_error"]}},{"name":"rating","in":"query","required":false,"description":"Only chats the visitor rated with this many stars.","schema":{"type":"integer","minimum":1,"maximum":5}},{"name":"lead","in":"query","required":false,"description":"`yes`: only chats that saved a lead. `no`: only chats without one. `missed`: only missed leads (see `missed_lead` on Conversation).","schema":{"type":"string","enum":["yes","no","missed"]}},{"name":"ended_reason","in":"query","required":false,"description":"Only chats that ended this way and that the visitor wrote in.","schema":{"type":"string","enum":["visitor_ended","idle_timeout","max_messages","error"]}},{"name":"source","in":"query","required":false,"description":"Only chats with this source on the `touch` attribution: the UTM source, else the referrer host without www, else `direct`; on `latest_paid`, the ad platform (`google`, `meta`, `microsoft`, `openai`), else the UTM source, else `paid`. `not_recorded` matches chats with no such touch.","schema":{"type":"string"}},{"name":"touch","in":"query","required":false,"description":"Which attribution touch `source` reads.","schema":{"type":"string","enum":["first","visit","latest_paid"],"default":"visit"}},{"name":"channel","in":"query","required":false,"description":"Only chats on this channel.","schema":{"type":"string","enum":["web_chat","whatsapp"]}},{"name":"lead_from","in":"query","required":false,"description":"Only chats whose lead was saved at or after this time (ISO 8601 with offset).","schema":{"type":"string","format":"date-time"}},{"name":"lead_to","in":"query","required":false,"description":"Only chats whose lead was saved before this time (ISO 8601 with offset).","schema":{"type":"string","format":"date-time"}},{"name":"taken_over_by","in":"query","required":false,"schema":{"type":"string"},"description":"Only conversations this operator id (the takeover `agent.id`) holds or held."},{"name":"sort","in":"query","required":false,"description":"Sort by creation time or by number of messages.","schema":{"type":"string","enum":["created_at","message_count"],"default":"created_at"}},{"name":"dir","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"cursor","in":"query","required":false,"description":"`next_cursor` from the previous page. Keep the same filters and sort while paging.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"include_total","in":"query","required":false,"description":"When true, the response carries `total`: the number of conversations matching every filter, ignoring the cursor.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"next_cursor":{"type":["string","null"],"description":"Opaque pagination cursor."},"has_more":{"type":"boolean"},"total":{"type":"integer","minimum":0,"description":"Conversations matching the filters across all pages. Present only when include_total=true."},"live_handoff":{"type":"boolean","description":"Whether the org takes web chats over live. When false, takeover is refused and handoff requests are callback requests."}},"required":["data","next_cursor","has_more","live_handoff"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-conversations","security":[{"apiKey":[]}]}},"/api/conversations/{id}":{"get":{"tags":["Conversations"],"summary":"Get a conversation","description":"The conversation with its messages, usage lines, lead and latest analysis. Tool and system rows, and assistant tool-call steps, are returned only to instance staff, org admins and owners, and API keys. Members and viewers get the transcript the visitor saw.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`."}],"operationId":"get-conversations-id","security":[{"apiKey":[]}]}},"/api/conversations/{id}/callback":{"put":{"tags":["Conversations"],"summary":"Mark a callback made, or reopen it","description":"`done: true` stamps `done_at`, `done_by` and `done_by_name` on the conversation's callback; repeating it keeps the first stamp. `done: false` clears them. Works on ended chats and when the org has live handoff off. 409 `no_callback` when the visitor left no callback request. With an API key, name the person in `agent`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCallbackRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationCallbackState"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`."}],"operationId":"put-conversations-id-callback","security":[{"apiKey":[]}]}},"/api/conversations/{id}/journey":{"get":{"tags":["Conversations"],"summary":"The visits this conversation's visitor made to the site","description":"Up to 20 recent visits, newest first, across the organization's projects, by the conversation's visitor id and by the visitor ids of other conversations in the same organization whose lead shares its email, phone number (digits only, at least 7) or customer id (at most 10 visitors, listed in `visitors`); test traffic excluded. A conversation without a visitor id (no analytics consent, or an older widget) and without linked chats returns visitors and visits empty.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VisitorJourney"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"operationId":"get-conversations-id-journey","security":[{"apiKey":[]}]}},"/api/conversations/{id}/messages":{"post":{"tags":["Conversations"],"summary":"Send a message as a person","description":"Only the operator holding the seat may send (403 otherwise). With `client_message_id`, a retry by the same operator returns the original message instead of sending it again; reusing the id for different content is 409 `client_message_id_reused`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":4000},"agent":{"$ref":"#/components/schemas/AgentIdentityInput"},"client_message_id":{"type":"string","minLength":1,"maxLength":200,"description":"Unique per message from this operator; makes a retried send safe."}},"required":["content"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationMessage"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`."}],"operationId":"post-conversations-id-messages","security":[{"apiKey":[]}]}},"/api/conversations/{id}/release":{"post":{"tags":["Conversations"],"summary":"Hand a conversation back to the assistant","description":"The holder releases their own seat; org admins and API keys may release anyone's, which is recorded as a forced release naming the previous holder. Send the same `agent` you took over with, so the release is recorded as yours rather than forced. Release still works when the org has turned live handoff off.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationTakeoverRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationTakeover"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`."}],"operationId":"post-conversations-id-release","security":[{"apiKey":[]}]}},"/api/conversations/{id}/reply-suggestions":{"post":{"tags":["Conversations"],"summary":"Draft unsent replies for a conversation","description":"Member role. Generates two or three text drafts from the current transcript and stored analysis, using this project's configured analysis model (or chat model). Requires the project's provider credentials. Sends nothing, executes no tools and stores no messages. through_seq identifies the transcript read; analysis_through_seq can lag or be null.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Unsent text drafts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["replies","through_seq","analysis_through_seq"],"properties":{"replies":{"type":"array","minItems":2,"maxItems":3,"items":{"type":"string"}},"through_seq":{"type":"integer"},"analysis_through_seq":{"type":["integer","null"]}}}}}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"model_connection_required"},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"reply_draft_failed"}},"operationId":"post-conversations-id-reply-suggestions","security":[{"apiKey":[]}]}},"/api/conversations/{id}/takeover":{"post":{"tags":["Conversations"],"summary":"Take over a conversation","description":"Only one operator holds a seat: when another already does, 409 `already_taken_over` names them in `taken_over_by`. Taking over a seat you hold refreshes it. 409 `live_handoff_disabled` when the org does not take web chats over live. Heartbeat and operator messages refuse the same way. With an API key, name the person in `agent` (otherwise the holder is `api_key`) and send the same `agent` on every message, heartbeat and release. A seat with no heartbeat for three minutes is released.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationTakeoverRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationTakeover"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`."}],"operationId":"post-conversations-id-takeover","security":[{"apiKey":[]}]}},"/api/conversations/{id}/takeover/heartbeat":{"post":{"tags":["Conversations"],"summary":"Keep a takeover alive","description":"Call at least once a minute while a person is working the chat. A seat with no heartbeat for three minutes is released and the assistant answers again. Send the same `agent` you took over with.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationTakeoverRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationTakeoverHeartbeat"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation id, `conv_...`."}],"operationId":"post-conversations-id-takeover-heartbeat","security":[{"apiKey":[]}]}},"/api/conversations/handoff-summary":{"get":{"tags":["Conversations"],"summary":"Summarize human handoffs","description":"Conversations created in the range (inclusive), sandbox conversations excluded unless `mode` says otherwise. answer_seconds runs from the handoff request to the first takeover. first_response_seconds and longest_wait_seconds are taken over the conversations with human_metrics.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's conversations."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants' conversations. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or after this time."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or before this time."},{"name":"mode","in":"query","required":false,"description":"Which chats to include, by the mode the server gave each. Absent: sandbox and preview chats are left out, and so are live chats a page marked as a test, as before. live: every live-mode chat, including those a page marked as a test. test: sandbox chats (stored mode `test`). preview: preview chats. all: every chat.","schema":{"type":"string","enum":["live","test","preview","all"]}},{"name":"traffic","in":"query","required":false,"description":"Comma-separated subset of real, sandbox and test: only chats of those kinds. When given it replaces the default view (and `include_test`); an explicit `mode` still narrows. Absent: the default view, unchanged.","schema":{"type":"string","examples":["real,sandbox"]}},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","enum":["none","assistant"],"default":"none"},"description":"`assistant` returns only `by_assistant` (ConversationHandoffsByAssistant): the plain counts for each assistant with conversations in the range, under the same filters, without the whole-range figures."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/ConversationHandoffSummary"},{"$ref":"#/components/schemas/ConversationHandoffsByAssistant"}]}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-conversations-handoff-summary","security":[{"apiKey":[]}]}},"/api/test-data":{"get":{"tags":["Conversations"],"summary":"Count a project's sandbox data","description":"What POST /v1/test-data/clear would delete now: sandbox and preview chats, their files, the leads they captured, and sandbox telemetry. An estimate, as sandbox chats may start meanwhile.","parameters":[{"name":"project_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project_id":{"type":"string"},"conversations":{"type":"integer","description":"Sandbox and preview chats there are now."},"leads":{"type":"integer","description":"Sandbox and preview leads."},"events":{"type":"integer","description":"Chat events and request outcomes."},"attachments":{"type":"integer","description":"Uploaded files."},"calls":{"type":"integer","description":"Finished sandbox calls (with their costs, analysis and recording rows)."}},"required":["project_id","conversations","leads","events","attachments"]}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-test-data","security":[{"apiKey":[]}]}},"/api/test-data/clear":{"post":{"tags":["Conversations"],"summary":"Clear a project's sandbox and preview chats and leads","description":"Deletes the project's sandbox and preview chats started before the request (with their messages, files, analysis, telemetry and webhook events) and the leads they captured. Live chats are never touched, nor are live chats whose page only claimed to be a test. Sends no webhooks. Returns what it deleted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"project_id":{"type":"string"}},"required":["project_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project_id":{"type":"string"},"conversations":{"type":"integer","description":"Sandbox and preview chats deleted."},"leads":{"type":"integer","description":"Sandbox and preview leads."},"events":{"type":"integer","description":"Chat events and request outcomes."},"attachments":{"type":"integer","description":"Uploaded files."},"calls":{"type":"integer","description":"Finished sandbox calls (with their costs, analysis and recording rows)."},"attachment_failures":{"type":"integer","description":"Files whose delete failed (logged)."}},"required":["project_id","conversations","leads","events","attachments"]}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-test-data-clear","security":[{"apiKey":[]}]}},"/api/forms":{"post":{"tags":["Forms"],"summary":"Create a form","description":"Creates a form with one live and one test key. Needs the admin role.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormCreate"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-forms","security":[{"apiKey":[]}]},"get":{"tags":["Forms"],"summary":"List forms","description":"Forms in scope, newest first, each with the keys that accept posts (the test key only for the admin role). Archived forms are left out unless `archived=true`.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's forms."},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"`true`: only archived forms. Absent: only live ones."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Form"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-forms","security":[{"apiKey":[]}]}},"/api/forms/{id}":{"get":{"tags":["Forms"],"summary":"Get a form","description":"The form with the keys that accept posts (the test key only for the admin role), its health, and its live posts over the last 24 hours and 7 days (`stats`).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"get-forms-id","security":[{"apiKey":[]}]},"patch":{"tags":["Forms"],"summary":"Update a form","description":"Change any setting; send at least one. `field_map` keeps the keys it does not name. `turnstile: \"on\"` creates the form's Cloudflare Turnstile widget with its approved sites as hostnames (1 to 10 sites); the widget follows later changes to the sites. An archived form cannot be changed: restore it first. Needs the admin role.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`form_archived`: restore the form first. `turnstile_not_configured`: this deployment has no Cloudflare credentials for Turnstile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`turnstile_needs_sites` or `turnstile_too_many_sites`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"502":{"description":"`turnstile_unavailable`: Cloudflare refused or did not answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"patch-forms-id","security":[{"apiKey":[]}]},"delete":{"tags":["Forms"],"summary":"Delete an archived form","description":"Permanent: deletes the form, its keys, its Turnstile widget and its submissions with their files (the files first; 503 `files_not_deleted` when one could not be: the rows are kept, and a retry finishes). Leads made from them stay. Only an archived form can be deleted: 409 `not_archived` otherwise. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeleteResult"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_archived`: archive the form first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`files_not_deleted`: try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"delete-forms-id","security":[{"apiKey":[]}]}},"/api/forms/{id}/submissions":{"post":{"tags":["Forms"],"summary":"Send a submission from a server","description":"For a server that collected the form itself: the same field checks, sensitive drop, normalisation, kind and spam check as `POST /public/forms/{key}`, without the approved sites, Turnstile, the per-address limits or the missing Origin signal. 600 an hour per form; a repeat within 10 minutes answers with the first receipt. JSON only, at most 64 KiB; no files. Needs the admin role, or any API key that may write (not a viewer key).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormServerSubmission"}}}},"responses":{"201":{"description":"Stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormReceipt"}}}},"400":{"description":"`invalid_fields` (with `fields`) or `invalid_request`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormRefusal"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`form_archived` or `form_paused`, or the key may not write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormRefusal"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormRefusal"}}}},"429":{"description":"`rate_limited`: wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormRefusal"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"post-forms-id-submissions","security":[{"apiKey":[]}]},"get":{"tags":["Forms"],"summary":"List a form's submissions","description":"Newest first. Page with `cursor`: pass the previous page's `next_cursor`, null on the last page. Archived submissions are left out unless `archived=true`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"`true`: only archived submissions. Absent: only live ones."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["accepted","held","released"]},"description":"Only submissions in this state (`held`: waiting for review). Absent: any."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page. Keep the same filters while paging."},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only submissions received before this time. Kept for older callers: rows received in the same instant as a page's last can be skipped; use `cursor`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmission"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-forms-id-submissions","security":[{"apiKey":[]}]}},"/api/forms/{id}/archive":{"post":{"tags":["Forms"],"summary":"Archive a form","description":"Its keys stop accepting posts (403 `form_archived`) and it leaves the forms list. Nothing is deleted: its keys, Turnstile widget, submissions, files and leads all stay, and it can be restored (or then deleted for good). Archiving an archived form is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"post-forms-id-archive","security":[{"apiKey":[]}]}},"/api/forms/{id}/google":{"get":{"tags":["Forms"],"summary":"Get a Google lead form's setup","description":"The webhook URLs and the Google key to paste into the Google Ads lead form, the question id overrides, who exports and uploads, and what has arrived. 404 for a website form. Needs the admin role.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormGoogleSetup"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"get-forms-id-google","security":[{"apiKey":[]}]},"patch":{"tags":["Forms"],"summary":"Update a Google lead form's setup","description":"The question id overrides and who exports and uploads (recorded, not enforced). Needs the admin role; audited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormGooglePatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormGoogleSetup"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`form_archived`: restore the form first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"patch-forms-id-google","security":[{"apiKey":[]}]}},"/api/forms/{id}/google/rotate-key":{"post":{"tags":["Forms"],"summary":"Rotate a Google lead form's key","description":"A new Google key; the old one keeps working for 7 days, so the Google Ads lead form can be updated. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormGoogleSetup"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`form_archived`: restore the form first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"post-forms-id-google-rotate-key","security":[{"apiKey":[]}]}},"/api/forms/{id}/keys/{keyId}/revoke":{"post":{"tags":["Forms"],"summary":"Revoke a form key","description":"Stops the key at once, for a key that leaked. Needs the admin role.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"},"description":"The key's id."}],"operationId":"post-forms-id-keys-keyid-revoke","security":[{"apiKey":[]}]}},"/api/forms/{id}/keys/rotate":{"post":{"tags":["Forms"],"summary":"Rotate a form key","description":"Issues a new key of this mode. The current one keeps working for 7 days, so the site can be updated first; with `grace: false` it stops at once. Needs the admin role.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["live","test"]},"grace":{"type":"boolean","description":"False stops the current key at once instead of after 7 days."}},"required":["mode"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`form_archived`: restore the form first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"post-forms-id-keys-rotate","security":[{"apiKey":[]}]}},"/api/forms/{id}/restore":{"post":{"tags":["Forms"],"summary":"Restore an archived form","description":"Its keys accept posts again. Restoring a live form is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Form"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."}],"operationId":"post-forms-id-restore","security":[{"apiKey":[]}]}},"/api/forms/{id}/submissions/{sid}":{"get":{"tags":["Forms"],"summary":"Get a submission","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormSubmission"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"Submission id, `fsub_...`."}],"operationId":"get-forms-id-submissions-sid","security":[{"apiKey":[]}]},"delete":{"tags":["Forms"],"summary":"Delete an archived submission","description":"Permanent: its files are deleted first (503 `files_not_deleted` when one could not be: the rows are kept, and a retry finishes), then the submission. Its lead, if it made one, stays. Only an archived submission can be deleted: 409 `not_archived` otherwise. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeleteResult"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_archived`: archive the submission first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}},"503":{"description":"`files_not_deleted`: try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"Submission id, `fsub_...`."}],"operationId":"delete-forms-id-submissions-sid","security":[{"apiKey":[]}]}},"/api/forms/{id}/submissions/{sid}/archive":{"post":{"tags":["Forms"],"summary":"Archive a submission","description":"It leaves the submissions list and the export. Nothing is deleted: its files stay and still download, its lead stays, and it can be restored (or then deleted for good). Archiving an archived submission is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormSubmission"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"Submission id, `fsub_...`."}],"operationId":"post-forms-id-submissions-sid-archive","security":[{"apiKey":[]}]}},"/api/forms/{id}/submissions/{sid}/files/{fileId}":{"get":{"tags":["Forms"],"summary":"Download a submission's file","description":"Answers 302 to a download link (`/public/forms/files/{fileId}`) signed for 10 minutes. With malware scanning on, a new file downloads once its scan is clean, usually within seconds of the post.","responses":{"302":{"description":"The signed link, in `Location`."},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`file_scanning`: its malware scan is not done yet. Try again in a minute (`Retry-After`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`file_infected`: the scan found malware and the file was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"Submission id, `fsub_...`."},{"name":"fileId","in":"path","required":true,"schema":{"type":"string"},"description":"File id, `ffile_...`."}],"operationId":"get-forms-id-submissions-sid-files-fileid","security":[{"apiKey":[]}]}},"/api/forms/{id}/submissions/{sid}/release":{"post":{"tags":["Forms"],"summary":"Release a held submission","description":"Accepts a submission the spam check held: it then makes its lead and sends `form.submitted`, as an accepted one does. Releasing one twice is a no-op. 409 `submission_archived` for an archived one: restore it first. Needs the admin role.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormSubmission"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"Submission id, `fsub_...`."}],"operationId":"post-forms-id-submissions-sid-release","security":[{"apiKey":[]}]}},"/api/forms/{id}/submissions/{sid}/replay":{"post":{"tags":["Forms"],"summary":"Replay a submission's webhooks","description":"Sends the submission's `form.submitted` and `lead.captured` events again to the subscriptions that match them now, with the same event ids and idempotency keys, so receivers dedupe. A replayed `form.submitted` carries its file links signed again for 7 days from the replay. Needs the admin role; audited.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"string","enum":["form.submitted","lead.captured"]},"description":"Default: both."}},"additionalProperties":false}}}},"responses":{"200":{"description":"How many deliveries were queued.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"integer"}},"required":["queued"]}}}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`held`: a held submission has sent nothing; release it. `submission_archived`: restore it first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"Submission id, `fsub_...`."}],"operationId":"post-forms-id-submissions-sid-replay","security":[{"apiKey":[]}]}},"/api/forms/{id}/submissions/{sid}/restore":{"post":{"tags":["Forms"],"summary":"Restore an archived submission","description":"It is listed and exported again. Restoring a live submission is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormSubmission"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"sid","in":"path","required":true,"schema":{"type":"string"},"description":"Submission id, `fsub_...`."}],"operationId":"post-forms-id-submissions-sid-restore","security":[{"apiKey":[]}]}},"/api/forms/{id}/submissions/export":{"get":{"tags":["Forms"],"summary":"Export a form's submissions as CSV","description":"Every live submission (with `archived=true`, every archived one), newest first. Columns: `submission_id`, `received_at`, `status`, `mode`, the defined fields in order (headed by label, else key), other field keys in first-seen order, `page_url`, `referrer`, the five UTMs, `gclid`, `lead_id`, `files` (the file names) and `files_scan_status` (each file's scan status, in the same order). A cell starting with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`. Needs the admin role; audited.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Form id, `form_...`."},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"`true`: only archived submissions. Absent: only live ones."}],"responses":{"200":{"description":"CSV.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-forms-id-submissions-export","security":[{"apiKey":[]}]}},"/api/forms/erasures":{"post":{"tags":["Forms"],"summary":"Erase a person's form data","description":"The way to delete one person's data (with the forms' retention, and deleting an archived form or submission). Deletes the submissions in the org (or `project_id`), archived ones and those of archived forms included, where a contact field (one defined as `email` or `phone`, the form's `field_map` email or phone key, or on a form with no definition the key `email` or `phone`) is this email (any case) or phone (digits compared, the last 10 when longer), the form leads they made or with that email or phone, the webhook events about them, and the submissions' files (first; 503 when one could not be deleted: the rows are kept, and a retry finishes). `dry_run` only counts. Needs the admin role; audited with the counts and a keyed hash (HMAC) of the identifier, never the identifier.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"string"},"email":{"type":"string","format":"email","description":"An email address."},"phone":{"type":"string","description":"A phone number: 7 to 15 digits."},"dry_run":{"type":"boolean"}},"additionalProperties":false,"description":"At least one of `email` and `phone`."}}}},"responses":{"200":{"description":"What was (or, on a dry run, would be) erased.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"submissions":{"type":"integer"},"files":{"type":"integer"},"leads":{"type":"integer"},"dry_run":{"type":"boolean"}},"required":["submissions","files","leads","dry_run"]}}}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-forms-erasures","security":[{"apiKey":[]}]}},"/api/forms/health":{"get":{"tags":["Forms"],"summary":"List form health incidents","description":"Problems the form health checker found, newest first: a form gone quiet against its own history (`form_quiet`), refusing posts (`form_refusing`, one per reason), failing to store them (`form_failing`), or whose `form.submitted` deliveries are not arriving (`form_undelivered`). Live posts only.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","resolved"]}},{"name":"form_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque `next_cursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FormHealthIncident"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-forms-health","security":[{"apiKey":[]}]}},"/api/forms/health/{incidentId}/resolve":{"post":{"tags":["Forms"],"summary":"Resolve a form health incident","description":"Closes it by hand (`resolution: manual`); the same problem does not reopen for 24 hours. Sends `form.health.resolved`. A resolved incident is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FormHealthIncident"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"incidentId","in":"path","required":true,"schema":{"type":"string"},"description":"`fhinc_...`."}],"operationId":"post-forms-health-incidentid-resolve","security":[{"apiKey":[]}]}},"/api/leads":{"get":{"tags":["Leads"],"summary":"List leads","description":"Leads from chat, calls, SMS, WhatsApp and forms, newest first, one cursor page at a time. Merged leads are excluded. A lead is created when the assistant takes the visitor's details and updated as the conversation goes on; subscribe to the `lead.captured` webhook to hear about each one as it happens.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's leads."},{"name":"assistant_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only leads captured by this assistant, intersected with the caller's org and project scope. Unknown or inaccessible assistants return an empty page."},{"name":"form_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only leads captured by this form, intersected with the caller's project scope. Unknown or inaccessible forms return an empty page."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or after this time."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or before this time."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["live","test","preview","all"],"default":"live"},"description":"Live excludes effective test leads (sandbox, rule-caught and marked as test). Test includes non-live chats and leads classified or marked as test. Preview filters capture mode; all includes every mode. Merged leads are always excluded."},{"name":"traffic","in":"query","required":false,"description":"Comma-separated subset of real, sandbox and test: only leads of those kinds. When given it replaces the default view (and `include_test`); an explicit `mode` still narrows. Absent: the default view, unchanged.","schema":{"type":"string","examples":["real,sandbox"]}},{"name":"channel","in":"query","required":false,"schema":{"type":"string"},"description":"Only leads captured on this channel (the lead's `source`): `web_chat`, `web_call`, `phone_call`, `sms`, `whatsapp`, `form`, `ad_form`, `scheduling`, `other`. Several, comma separated, list any of them (`web_chat,web_call`). Absent: every channel."},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Another name for `channel`, with the same values and comma separated lists; read when `channel` is absent."},{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"Only leads with this status: `new`, `contacted`, `qualified`, `won` or `lost`. Several, comma separated, list any of them."},{"name":"attention","in":"query","required":false,"schema":{"type":"string","enum":["uncontacted","overdue","due_today","any"]},"description":"Needs attention, oldest first: `uncontacted` (status `new` and never contacted, by `created_at`), `overdue` (open, with `next_follow_up_at` before the start of today, by that date), `due_today` (open, with `next_follow_up_at` today, by that date) or `any` (all three, each lead by the earlier of its keys). Days are read in `tz`. The other filters still apply."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","examples":["Asia/Kolkata"]},"description":"IANA time zone for `attention`'s days. Default: the project's `timezone` when you see one project, else UTC. An unknown zone is 400."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search: a case-insensitive substring of the name, email, phone or any captured field value. A query with digits also matches the phone's digits alone, so `98765 43210` finds `+91 98765-43210`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Legacy ISO timestamp cursors are also accepted."}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page."},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-leads","security":[{"apiKey":[]}]},"post":{"tags":["Leads"],"summary":"Add a lead by hand","description":"Requires a member. Saves a lead someone typed in, optionally linked to a call or conversation in the selected project. Capture method is manual. Linked leads retain their assistant, mode and test rules; unlinked leads have no assistant and default to source other. It needs an email or phone. Missing or foreign origins are 404; an origin already linked to a lead is 409 already_has_lead. It sends no lead.captured webhook or owner email. The change is audited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadDetail"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-leads","security":[{"apiKey":[]}]}},"/api/leads/{id}":{"get":{"tags":["Leads"],"summary":"Get a lead","description":"One lead with the details the assistant captured, the conversation it came from, any outcome you reported, its status history and the chat's callback request.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadDetail"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Lead id, `lead_...`."}],"operationId":"get-leads-id","security":[{"apiKey":[]}]},"patch":{"tags":["Leads"],"summary":"Set a lead's test override","description":"Requires a member. Set test to true or false, or null to use automatic classification. Capture mode stays unchanged. The change is audited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"test":{"type":["boolean","null"]}},"required":["test"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Member role required."},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Lead id, `lead_...`."}],"operationId":"patch-leads-id","security":[{"apiKey":[]}]}},"/api/leads/{id}/contacts":{"post":{"tags":["Leads"],"summary":"Log a contact","description":"Requires a member. Records that someone reached the lead. A `new` lead moves to `contacted` (a status change, with `lead.status_changed`); a won or lost lead takes the contact without a status change. Sets `first_contacted_at` and `last_contacted_at`, and `next_follow_up_at` when given. With an API key the contact is `via: api`; name the person in `agent`. Audited, without contact details.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"channel":{"type":"string","enum":["phone","whatsapp","email","sms","in_person","other"]},"via":{"type":"string","enum":["button","manual"],"description":"The console's: a contact button or Log contact. Always `api` for an API key."},"contacted_at":{"type":"string","format":"date-time","description":"When it happened. Default now; not in the future, not before the lead, at most 30 days back."},"next_follow_up_at":{"type":["string","null"],"format":"date-time","description":"When to contact again: within a year, not more than 5 minutes past. Null clears it; absent leaves it. A date on a won or lost lead is 409 `lead_closed`."},"agent":{"description":"With an API key: who made the contact, as `PUT /status` takes it, or just a name.","anyOf":[{"type":"string"},{"$ref":"#/components/schemas/AgentIdentityInput"}]}},"required":["channel"]}}}},"responses":{"201":{"description":"Logged","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/LeadContact"},"lead":{"$ref":"#/components/schemas/LeadDetail"}},"required":["contact","lead"]}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`lead_closed`: a reminder date on a won or lost lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Lead id, `lead_...`."}],"operationId":"post-leads-id-contacts","security":[{"apiKey":[]}]}},"/api/leads/{id}/contacts/{contactId}/void":{"post":{"tags":["Leads"],"summary":"Undo a contact","description":"Requires a member. Voids a contact within 24 hours of logging it; a repeat changes nothing. The contact times are recomputed, and a contact that moved the lead from `new` moves it back while it is still `contacted`. Audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/LeadDetail"}},"required":["lead"]}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`void_window_passed`: more than 24 hours since it was logged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Lead id, `lead_...`."},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"},"description":"Contact id, `lcon_...`."}],"operationId":"post-leads-id-contacts-contactid-void","security":[{"apiKey":[]}]}},"/api/leads/{id}/facts/{field}":{"patch":{"tags":["Leads"],"summary":"Edit one captured lead fact","description":"Member role. Edits name, email, phone or a custom field. Null clears it. Records manual provenance, original capture time, edit time and actor. Does not send a message or lead webhook. Merged leads cannot be edited.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"field","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]{0,99}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["value"],"properties":{"value":{"type":["string","null"],"minLength":1,"maxLength":500}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"patch-leads-id-facts-field","security":[{"apiKey":[]}]}},"/api/leads/{id}/follow-up":{"put":{"tags":["Leads"],"summary":"Set a lead's reminder","description":"Requires a member. Sets or clears the reminder (`next_follow_up_at`). Audited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"next_follow_up_at":{"type":["string","null"],"format":"date-time","description":"When to contact again: within a year, not more than 5 minutes past. Null clears it; absent leaves it. A date on a won or lost lead is 409 `lead_closed`."}},"required":["next_follow_up_at"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadDetail"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`lead_closed`: the lead is won or lost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Lead id, `lead_...`."}],"operationId":"put-leads-id-follow-up","security":[{"apiKey":[]}]}},"/api/leads/{id}/merge":{"post":{"tags":["Leads"],"summary":"Merge a duplicate lead","description":"Requires a member. Both leads must be visible in the same project. Keeps this lead, filling only blank contact values and fields from duplicate_id. Statuses and origin links stay on their rows; earlier merges move to this lead. The duplicate stays readable by id with merged_into_id set, but is excluded from lists, attention, speed and new work. Audited as lead.merged; no webhook.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"duplicate_id":{"type":"string","minLength":1}},"required":["duplicate_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadDetail"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Either lead is outside scope, missing or in a different project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_merged: either lead has already been merged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The lead to keep."}],"operationId":"post-leads-id-merge","security":[{"apiKey":[]}]}},"/api/leads/{id}/not-duplicate":{"post":{"tags":["Leads"],"summary":"Dismiss a duplicate suggestion","description":"Requires a member. Both leads must be visible in the same project and neither may be merged. Records the dismissal on both leads so neither suggests the other. Idempotent. Audited as lead.not_duplicate.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"duplicate_id":{"type":"string","minLength":1}},"required":["duplicate_id"]}}}},"responses":{"200":{"description":"Dismissed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_merged: either lead has already been merged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Lead id, lead_..."}],"operationId":"post-leads-id-not-duplicate","security":[{"apiKey":[]}]}},"/api/leads/{id}/outcome":{"put":{"tags":["Leads"],"summary":"Report a lead's outcome","description":"Call from your CRM when a lead turns into a booking, is lost, or goes back to open, so chat analytics can count bookings and revenue. Replaces the whole outcome: a field you leave out is cleared, and `at` defaults to now. `customer_id` is separate: leaving it out keeps the stored one.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadOutcomeInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Lead id, `lead_...`."}],"operationId":"put-leads-id-outcome","security":[{"apiKey":[]}]}},"/api/leads/{id}/status":{"put":{"tags":["Leads"],"summary":"Set a lead's status","description":"Requires a member. Moves the lead to `new`, `contacted`, `qualified`, `won` or `lost` and records who and when, in the lead's `status_history` and the audit log. Setting the status it already has changes nothing. A change to `won` or `lost` clears `next_follow_up_at`. A change out of `new` by a person or key counts as the first contact when none was logged. With an API key, name the person in `agent`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["new","contacted","qualified","won","lost"]},"agent":{"$ref":"#/components/schemas/AgentIdentityInput"}},"required":["status"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadDetail"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Lead id, `lead_...`."}],"operationId":"put-leads-id-status","security":[{"apiKey":[]}]}},"/api/leads/attention":{"get":{"tags":["Leads"],"summary":"Count leads that need attention","description":"How many live leads are uncontacted, overdue and due today (the `attention` buckets of the list). `total` counts a lead in two buckets once.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's leads."},{"name":"tz","in":"query","required":false,"schema":{"type":"string"},"description":"IANA time zone for the days. Default: the project's `timezone` when you see one project, else UTC."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadAttention"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-leads-attention","security":[{"apiKey":[]}]}},"/api/leads/settings":{"get":{"tags":["Leads"],"summary":"Get lead reminder settings","description":"When a new lead counts as waiting too long (`lead.uncontacted`). A project with no settings has the defaults.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadsSettings"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"The project. Required with an org-wide key; a project key uses its own."}],"operationId":"get-leads-settings","security":[{"apiKey":[]}]},"put":{"tags":["Leads"],"summary":"Set lead reminder settings","description":"Requires an admin. `uncontacted_after_minutes` from 15 to 1,440, or null to stop `lead.uncontacted` for the project. The change is audited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"uncontacted_after_minutes":{"type":["integer","null"],"minimum":15,"maximum":1440}},"required":["uncontacted_after_minutes"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadsSettings"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"The project. Required with an org-wide key; a project key uses its own."}],"operationId":"put-leads-settings","security":[{"apiKey":[]}]}},"/api/leads/speed":{"get":{"tags":["Leads"],"summary":"Speed to lead","description":"How long leads waited for a first contact, wall clock. Counts live leads that are not test and were not added by hand, created between `from` and `to` (default the last 30 days). The median and 90th percentile cover contacted leads only; `uncontacted` says how many never were.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's leads."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"channel","in":"query","required":false,"schema":{"type":"string"},"description":"Only these channels (the lead's `source`), comma separated."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadSpeed"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-leads-speed","security":[{"apiKey":[]}]}},"/api/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create a webhook subscription","description":"Subscribes an HTTPS endpoint to events in one project. Each delivery is a JSON POST signed with `X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the secret>`; answer with any 2xx within 10 seconds. The response carries the signing `secret` this once: store it. Send your own `secret`, or one is minted for you. Event types: `call.started`, `call.connected`, `call.ended`, `conversation.started`, `conversation.message.created`, `conversation.handoff_requested`, `conversation.callback_requested`, `conversation.takeover.started`, `conversation.takeover.released`, `conversation.analyzed`, `conversation.ended`, `lead.captured`, `search_reporting.report_ready`, `search_reporting.alert_raised`, `search_reporting.alert_resolved`, `scheduling.routing_matched`, `scheduling.routing_fallback`, `booking.created`, `booking.processing`, `booking.confirmed`, `booking.requested`, `booking.rejected`, `booking.expired`, `booking.completed`, `booking.attendance_updated`, `booking.guests_updated`, `booking.reassigned`, `booking.rescheduled`, `booking.cancelled`, `form.submitted`, `lead.status_changed`, `lead.uncontacted`, `lead.follow_up_due`, `form.health.opened`, `form.health.resolved`, `outreach.enrollment.started`, `outreach.enrollment.stopped`, `outreach.enrollment.completed`, `outreach.step.completed`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionCreate"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscriptionCreated"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-webhooks","security":[{"apiKey":[]}]},"get":{"tags":["Webhooks"],"summary":"List webhook subscriptions","description":"Subscriptions in scope, without their signing secrets (a secret is shown only when the subscription is created). Archived subscriptions are left out unless `archived=true`.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's subscriptions."},{"name":"archived","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"`true`: only archived subscriptions. Absent: only live ones."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-webhooks","security":[{"apiKey":[]}]}},"/api/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook subscription","description":"One subscription, without its signing secret.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription id, `whsub_...`."}],"operationId":"get-webhooks-id","security":[{"apiKey":[]}]},"patch":{"tags":["Webhooks"],"summary":"Update a webhook subscription","description":"Change the URL, the events, the secret, or turn the subscription off and on. Send at least one field. A new `secret` applies to the next attempt, including retries already queued; it is not echoed back. An archived subscription cannot be changed: 409 `webhook_archived`, restore it first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`webhook_archived`: restore the subscription first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription id, `whsub_...`."}],"operationId":"patch-webhooks-id","security":[{"apiKey":[]}]},"delete":{"tags":["Webhooks"],"summary":"Delete an archived webhook subscription","description":"Only an archived subscription can be deleted: 409 `not_archived` otherwise. Deletes it for good with its delivery log. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeleteResult"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription id, `whsub_...`."}],"operationId":"delete-webhooks-id","security":[{"apiKey":[]}]}},"/api/webhooks/{id}/archive":{"post":{"tags":["Webhooks"],"summary":"Archive a webhook subscription","description":"It gets no new deliveries, its retries still pending are not sent (they fail with `subscription archived`), it cannot be changed, and it leaves the subscriptions list. Nothing is deleted: its delivery log stays, and it can be restored. Archiving an archived subscription is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription id, `whsub_...`."}],"operationId":"post-webhooks-id-archive","security":[{"apiKey":[]}]}},"/api/webhooks/{id}/restore":{"post":{"tags":["Webhooks"],"summary":"Restore an archived webhook subscription","description":"It gets deliveries again from the next event (unless it is turned off); deliveries that failed while it was archived are not resent. Restoring a live subscription is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription id, `whsub_...`."}],"operationId":"post-webhooks-id-restore","security":[{"apiKey":[]}]}},"/api/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List a subscription's recent deliveries","description":"The latest 100 deliveries, newest first: one row per event, with the cumulative `attempts` and the latest attempt's status and error, without the event body. Each event is tried up to 10 times with backoff from 10 seconds (about 85 minutes in all). `failed` means it never got a 2xx: every attempt failed, the subscription was turned off or archived meanwhile, or it was still pending after 24 hours.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription id, `whsub_...`."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","delivered","failed"]},"description":"Only deliveries in this state."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-webhooks-id-deliveries","security":[{"apiKey":[]}]}},"/api/analytics/latency":{"get":{"tags":["Call analytics"],"summary":"Get call latency","description":"End-to-end response latency (p50 and p95, in milliseconds) and per-stage percentiles over the window, the number of calls measured (`calls`), and the slowest calls. Percentiles are null when there are no measured calls. The body is not wrapped in `data`.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's calls (an org-wide key covers every project by default)."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the window, ISO 8601 with an offset. Default: 30 days before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End of the window. Default: now."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsLatency"}}}},"400":{"description":"`invalid_range`: `from` or `to` is not a valid timestamp, or `from` is not before `to`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-analytics-latency","security":[{"apiKey":[]}]}},"/api/analytics/search/ai-visits":{"get":{"tags":["Call analytics"],"summary":"AI referral visits by assistant and landing page","description":"AI referral visits (Analytics sessions whose source is an AI assistant host, classification ai-referrers-v1) for the overview's window: period, or start_date and end_date, the same rules as GET /analytics/search/overview. ai_referral_visits.value equals the overview's ai_referral_visits.value, and by_assistant (chatgpt, perplexity, gemini, claude, copilot, other) sums to it; both are null when no day was imported. by_landing_page reads an Analytics import split by landing page and source: pages lists up to limit (1 to 50, default 50) pages on the site's origin and included paths, most visits first; visits_outside_site_scope counts AI visits whose landing page is not set, on another origin or outside the included paths; pages is null without such an import or an imported day. Each page's tracked_questions_citing_page lists up to 10 of the site's tracked AI visibility questions whose valid AI answers sampled in the window cite that page, with how many answers did. These are the questions the site tracks, not the prompts that sent the visitors: assistants report no prompt. A page with visits and no citing question has an empty list. tracked_question_answers counts the valid AI answers read. Missing days stay gaps: compare collected_days with expected_days.","parameters":[{"name":"site_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","28d","90d"],"default":"28d"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSearchAiVisits"}}}},"400":{"description":"invalid_request: site_id missing, or an invalid window or limit"},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Site not found in caller scope"},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-analytics-search-ai-visits","security":[{"apiKey":[]}]}},"/api/analytics/search/goals":{"get":{"tags":["Call analytics"],"summary":"Search goal progress","description":"The site's active goals (GET /search/sites/{id}/goals) with progress. current gives every metric's value, with or without a goal: clicks and leads from search for the last complete month, and money searches on page one (services queries at position 10 or better over the keyword window). Each goal adds current, percent (of target, whole number, may pass 100) and status: done once current reaches the target, on_track while current is at least the target times the share of time passed from the goal's creation to the end of its due date, else behind. Null current means unknown, and then percent and status are null.","parameters":[{"name":"site_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSearchGoals"}}}},"400":{"description":"invalid_request: site_id is missing"},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Site not found in caller scope"},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-analytics-search-goals","security":[{"apiKey":[]}]}},"/api/analytics/search/keywords":{"get":{"tags":["Call analytics"],"summary":"Search keyword groups","description":"Query rows Google reported over the 28 days ending yesterday in the business time zone, each query's rows summed across days and pages. Groups, and a query may be in several: defend (average position 3 or better, at least one click), near_page_one (position 8 to 20 with at least 50 impressions), services (a commercial word such as cost, price, near me, book, hire, repair), places (a ZIP or postcode, or a place from the site's markets), dated (a year, a month name, deal or offer). counts are full group sizes; groups list up to 100 rows each, most impressions first. counts are null when no query import qualifies or no day was imported.","parameters":[{"name":"site_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSearchKeywords"}}}},"400":{"description":"invalid_request: site_id is missing"},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Site not found in caller scope"},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-analytics-search-keywords","security":[{"apiKey":[]}]}},"/api/analytics/search/monthly":{"get":{"tags":["Call analytics"],"summary":"Search results month by month","description":"The last 6 complete calendar months in the business time zone, newest first, each with the same month a year earlier (year_earlier) and the change against it. Clicks, impressions, ctr and position come from the one unfiltered property-totals Search Console import; queries_top_3 and queries_top_10 from the query rows Google reports (query_scope reported_by_google: anonymized searches are left out). A figure is null unless every day of its month was imported (coverage gives collected and expected days): a gap is never a zero. Months use the provider's reporting dates. countries lists up to 10 countries by clicks in the latest month against the year-earlier month, from an import split by country but not by query; country is the code Google reports (ISO 3166-1 alpha-3, lowercase). leads_recorded_from is the day the business joined Brightshoal.","parameters":[{"name":"site_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSearchMonthly"}}}},"400":{"description":"invalid_request: site_id is missing"},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Site not found in caller scope"},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-analytics-search-monthly","security":[{"apiKey":[]}]}},"/api/analytics/search/overview":{"get":{"tags":["Call analytics"],"summary":"Search overview through capture","description":"Read-only owner-facade projection. Includes official search coverage, AI mention numerator/denominator and planned/failed/missing samples, ai_mention_rate.by_surface with those counts per surface present in the period points except serp (sorted by surface), classified referral sessions, real conversations, captured leads and verified interventions. Surfaces are separate populations and must not be added together; pooled AI fields remain for compatibility. Missing series remain null/incomplete; no sales attribution is inferred. Defaults to period whole UTC days ending yesterday inclusive. end_date overrides the inclusive end; start_date optionally overrides the start (requires end_date, maximum 90 days). window gives inclusive dates; interval gives equivalent half-open UTC timestamps. previous contains the immediately preceding equal-length window and all the same figures and coverage. coverage gives collected_days and expected_days for each measure. Search and referral days count complete/incomplete imported reports; AI collected days count distinct days with valid answers; AI expected days count scheduled UTC panel dates and materialised manual run dates, including missed weekly slots, rather than calendar days; owned event measures cover every queried day, including observed zero days. captured_leads_by_source splits captured_leads by where the visit came from, every key present and summing to captured_leads: google (organic), google_ads (a Google click id, or a paid utm_medium such as cpc from Google), bing (organic), ai_assistants, direct (no referrer and no UTM), other (any other referrer or ad platform) and not_recorded (no touch kept: no analytics consent, an older widget, or a form submission). It reads the visit's touch, else the visitor's first touch. captured_leads_by_page lists up to 50 pages, most leads first: {path, total, from_search}, where path is the touch's landing page, else the page the lead was captured on, as a path on the site's origin and scope (other origins, queries and fragments are dropped), and from_search counts google, bing and ai_assistants leads. analytics_key_events is null unless exactly one unfiltered Analytics import for the whole site reads landingPage by sessionDefaultChannelGroup with keyEvents (or conversions, its earlier name); otherwise {collected_days, expected_days, total, organic_search, by_page, complete}: key events summed over the imported rows, organic_search those GA4 groups as Organic Search, by_page up to 50 landing pages with key events, most first ({path, total, organic_search}; rows without a landing page count in the totals only). Figures are null until a day is collected; complete is false when a day is missing, thresholded, sampled or has an (other) row. Measurement only: these are not leads Brightshoal captured.","parameters":[{"name":"site_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","28d","90d"],"default":"28d"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Scoped overview with window, interval, per-measure coverage and previous figures in data envelope","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"ai_mention_rate":{"type":"object","properties":{"by_surface":{"type":"array","items":{"type":"object","properties":{"surface":{"type":"string","enum":["consumer","model_api"]},"numerator":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"denominator":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"value":{"description":"Numerator divided by denominator, null when denominator is zero.","type":["number","null"]},"planned":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"missing":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["surface","numerator","denominator","value","planned","failed","missing"],"additionalProperties":false},"description":"One entry per surface present in the period points except serp, sorted by surface. Surfaces are separate populations and must not be added together."}},"required":["by_surface"],"additionalProperties":{}},"previous":{"type":"object","properties":{"ai_mention_rate":{"type":"object","properties":{"by_surface":{"type":"array","items":{"type":"object","properties":{"surface":{"type":"string","enum":["consumer","model_api"]},"numerator":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"denominator":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"value":{"description":"Numerator divided by denominator, null when denominator is zero.","type":["number","null"]},"planned":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"missing":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["surface","numerator","denominator","value","planned","failed","missing"],"additionalProperties":false},"description":"One entry per surface present in the period points except serp, sorted by surface. Surfaces are separate populations and must not be added together."}},"required":["by_surface"],"additionalProperties":{}}},"required":["ai_mention_rate"],"additionalProperties":{}}},"required":["ai_mention_rate","previous"],"additionalProperties":{}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"invalid_request"},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Site not found in caller scope"},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-analytics-search-overview","security":[{"apiKey":[]}]}},"/api/analytics/staffing":{"get":{"tags":["Call analytics"],"summary":"Lead arrivals and assistant handling by channel","description":"Viewer role. One project, resolved from project_id or the caller's scope. Half-open period [from,to), default 30 days, at most 400 days. Uses the project's business timezone, or UTC if unset; tz overrides it. Arrival cells are sparse (omitted cells are zero), weekday 0 is Sunday, hour 0 to 23. Real unmerged leads only. Handling counts chats by creation time: handled means ended with an assistant reply and no handoff or takeover; handed means requested a human or was taken over, including unanswered requests. Calls: handled means connected and completed without transfer; handed means a transfer was attempted or completed. Open chats without handoff, unanswered calls and failures are in neither count. No handling counts are invented for form-only channels.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's calls (an org-wide key covers every project by default)."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the window, ISO 8601 with an offset. Default: 30 days before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End of the window. Default: now."},{"name":"tz","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","schema":{"type":"string"},"description":"Optional lead channel, such as web_chat, whatsapp, phone_call or form."}],"responses":{"200":{"description":"Staffing aggregates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffingInsightsResponse"}}}},"400":{"description":"Invalid range, timezone, channel or project selection"},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project outside scope"},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-analytics-staffing","security":[{"apiKey":[]}]}},"/api/analytics/volume":{"get":{"tags":["Call analytics"],"summary":"Get call volume","description":"Call counts and minutes over the window: totals, by status, by call type, by why calls ended, and per day. The window defaults to the last 30 days. The body is not wrapped in `data`.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's calls (an org-wide key covers every project by default)."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the window, ISO 8601 with an offset. Default: 30 days before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End of the window. Default: now."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsVolume"}}}},"400":{"description":"`invalid_range`: `from` or `to` is not a valid timestamp, or `from` is not before `to`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-analytics-volume","security":[{"apiKey":[]}]}},"/api/chat-analytics/engagement":{"get":{"tags":["Chat analytics"],"summary":"Get chat depth, timing and busy hours","description":"Counted web chats started in the window by visitor messages (with how many saved a lead), seconds from a page view's first open to its first send, seconds and visitor messages from a chat's first message to its lead, chats and leads by weekday and hour in `tz`, and how many started while the assistant's working hours were closed.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: 24 hours before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: now. Ranges over 90 days are rejected."},{"name":"tz","in":"query","required":false,"schema":{"type":"string"},"description":"IANA time zone the weekday and hour heatmap counts in. Default: the first working-hours zone among the assistants asked for, else UTC."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatEngagement"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-engagement","security":[{"apiKey":[]}]}},"/api/chat-analytics/failures":{"get":{"tags":["Chat analytics"],"summary":"List failed chat requests","description":"Each public chat request (config, events, start, send) that failed or was refused, with its status, outcome code, site, browser and request id, for chasing a broken embed. A malformed cursor is a 400.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: 24 hours before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: now. Ranges over 90 days are rejected."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`next_cursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatFailure"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-failures","security":[{"apiKey":[]}]}},"/api/chat-analytics/funnel":{"get":{"tags":["Chat analytics"],"summary":"Get the visitor funnel","description":"Page views at each stage (loaded, shown, card, opened, typed, sent), then sends, conversations, leads, handoffs and bookings, optionally split by a dimension and compared with the window before.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: 24 hours before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: now. Ranges over 90 days are rejected."},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","enum":["none","site","page","device","browser","source","hour","hour_of_day","open_reason","visitor_type","assistant","campaign","medium","ad_platform","url_rule"],"default":"none"},"description":"Split the funnel into one group per value of this dimension. `hour` keys each UTC hour of the window; `hour_of_day` keys the hour of the day (`00` to `23`) in `tz`, adding up every day in the window. `campaign` and `medium` key the visit's `utm_campaign` and `utm_medium`, and `ad_platform` the ad click id its landing carried (`google`, `meta`, `microsoft`, `openai`); `none` when there was none and `unknown` without analytics consent. `url_rule` keys the `url_rules` pattern whose card showed on the page view (`card_shown`): `none` for the assistant-wide opener, `no_card` when no card showed."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","default":"UTC"},"description":"IANA time zone `hour_of_day` counts its hours in, e.g. `Europe/London`."},{"name":"compare","in":"query","required":false,"schema":{"type":"string","enum":["previous","average_7"]},"description":"`previous` adds each group's counts for the window of the same length just before. `average_7` adds the mean of the same window on each of the seven days before (or of the seven windows before, for a window of a day or longer), to one decimal; it takes windows of 7 days or less."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatFunnel"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-funnel","security":[{"apiKey":[]}]}},"/api/chat-analytics/health":{"get":{"tags":["Chat analytics"],"summary":"Get chat health by site","description":"For each site the chat runs on: page views, shown and opened panels, sends, failures and refusals, reply time percentiles, the last successful reply and open incidents, with a status (`ok`, `warning`, `critical`, `idle`). Defaults to the last 24 hours.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: 24 hours before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: now. Ranges over 90 days are rejected."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatHealth"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-health","security":[{"apiKey":[]}]}},"/api/chat-analytics/incidents":{"get":{"tags":["Chat analytics"],"summary":"List chat health incidents","description":"Problems the health checker opened on its own (for example a site whose sends started failing), newest activity first. An incident resolves itself when the site recovers or goes quiet, or by hand.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants' incidents. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","resolved","all"],"default":"open"},"description":"Which incidents to list."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`next_cursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatIncident"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-incidents","security":[{"apiKey":[]}]}},"/api/chat-analytics/incidents/{id}/mute":{"post":{"tags":["Chat analytics"],"summary":"Mute an incident","description":"Stops notifications for this incident for 15 minutes to 7 days. The incident stays open and keeps counting.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatIncidentMute"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatIncident"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Incident id."}],"operationId":"post-chat-analytics-incidents-id-mute","security":[{"apiKey":[]}]}},"/api/chat-analytics/incidents/{id}/resolve":{"post":{"tags":["Chat analytics"],"summary":"Resolve an incident","description":"Closes the incident as `manual`. No request body. 409 `already_resolved` if it is closed already; a new failure opens a new incident.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatIncident"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Incident id."}],"operationId":"post-chat-analytics-incidents-id-resolve","security":[{"apiKey":[]}]}},"/api/chat-analytics/incidents/{id}/unmute":{"post":{"tags":["Chat analytics"],"summary":"Unmute an incident","description":"Resumes notifications for a muted incident. No request body.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatIncident"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Incident id."}],"operationId":"post-chat-analytics-incidents-id-unmute","security":[{"apiKey":[]}]}},"/api/chat-analytics/lead-sources":{"get":{"tags":["Chat analytics"],"summary":"Get leads by first touch and latest paid touch","description":"Counted web chat leads saved in the window, grouped by the visitor's first-ever touch (UTM source, else referrer host, else `direct`; `not_recorded` without one) and by their latest paid touch within 90 days (the ad platform its click id names, else its UTM source). Sorted by valid leads, at most 20 rows each.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: 24 hours before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: now. Ranges over 90 days are rejected."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatLeadSources"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-lead-sources","security":[{"apiKey":[]}]}},"/api/chat-analytics/outcomes/backfill":{"post":{"tags":["Chat analytics"],"summary":"Label how already analysed chats ended (staff only)","description":"Queues ended, counted web chats in the window whose analysis has no outcome label for an outcome-only run. It sends nothing to any CRM or webhook. At most 500 per call; call again while `remaining` is true.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: 24 hours before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: now. Ranges over 90 days are rejected."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatOutcomesBackfill"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-chat-analytics-outcomes-backfill","security":[{"apiKey":[]}]}},"/api/chat-analytics/quality":{"get":{"tags":["Chat analytics"],"summary":"Get chat quality","description":"How well the chat is doing for visitors: reply and first-token time, missing replies, handoffs answered, how complete leads are, cost per lead, the assistant lines visitors most often stop after, and `improvement` (reply feedback, conversation ratings, containment, unanswered knowledge questions, unhelpful answers and comments, suggested fixes, where chats stop and flags on the assistant's answers, with emails, phone numbers and common name patterns masked).","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: 24 hours before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: now. Ranges over 90 days are rejected."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatQuality"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-quality","security":[{"apiKey":[]}]}},"/api/chat-analytics/subscriptions":{"get":{"tags":["Chat analytics"],"summary":"List notification subscriptions","description":"Where health alerts and the digest are sent: your own HTTPS endpoint or an email address. Needs the admin role, which API keys have.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatSubscription"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-subscriptions","security":[{"apiKey":[]}]},"post":{"tags":["Chat analytics"],"summary":"Create a notification subscription","description":"Sends `health` alerts (incidents opening and resolving) or a `digest` summary to an HTTPS URL or an email address. An org-wide key must name `project_id`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSubscriptionCreate"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatSubscription"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-chat-analytics-subscriptions","security":[{"apiKey":[]}]}},"/api/chat-analytics/subscriptions/{id}":{"patch":{"tags":["Chat analytics"],"summary":"Update a notification subscription","description":"Turn a subscription on or off, or change where it sends or its time zone. Send at least one field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSubscriptionPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatSubscription"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription id."}],"operationId":"patch-chat-analytics-subscriptions-id","security":[{"apiKey":[]}]},"delete":{"tags":["Chat analytics"],"summary":"Delete a notification subscription","description":"Stops the subscription for good. Answers 204 with no body.","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription id."}],"operationId":"delete-chat-analytics-subscriptions-id","security":[{"apiKey":[]}]}},"/api/chat-analytics/trend":{"get":{"tags":["Chat analytics"],"summary":"Get daily or weekly chat totals","description":"Funnel totals per day or per ISO week (weeks start on Monday), for charts over a longer range than the live views.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project. An org-wide key covers every project by default."},{"name":"assistant_id","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: 90 days before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Default: now. Up to 400 days."},{"name":"interval","in":"query","required":false,"schema":{"type":"string","enum":["day","week"],"default":"day"},"description":"One point per day or per week."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatTrend"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-chat-analytics-trend","security":[{"apiKey":[]}]}},"/api/alerts":{"get":{"tags":["Alerts"],"summary":"List alerts","description":"Alert rules in scope, with their thresholds and where they notify. Archived alerts are left out unless `archived=true`.","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this project's alerts."},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"`true`: only archived alerts. Absent: only live ones."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-alerts","security":[{"apiKey":[]}]},"post":{"tags":["Alerts"],"summary":"Create an alert","description":"A rule that watches one call metric (count, total cost, average latency or error rate) over a rolling window and notifies a webhook, Slack incoming webhook or email address when it crosses the threshold, and again when it recovers. It does not repeat while it stays breached. An org-wide key must name `project_id`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertCreate"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Alert"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-alerts","security":[{"apiKey":[]}]}},"/api/alerts/{id}":{"get":{"tags":["Alerts"],"summary":"Get an alert","description":"One alert rule, archived or not.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Alert"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Alert id."}],"operationId":"get-alerts-id","security":[{"apiKey":[]}]},"patch":{"tags":["Alerts"],"summary":"Update an alert","description":"Change any field of the rule, or turn it off with `enabled: false`. Send at least one field. An archived alert cannot be changed: restore it first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Alert"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`alert_archived`: restore the alert first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Alert id."}],"operationId":"patch-alerts-id","security":[{"apiKey":[]}]},"delete":{"tags":["Alerts"],"summary":"Delete an alert permanently","description":"Only an archived alert can be deleted: 409 `not_archived` otherwise. Removes the rule for good; its audit entries stay. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeleteResult"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_archived`: archive the alert first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Alert id."}],"operationId":"delete-alerts-id","security":[{"apiKey":[]}]}},"/api/alerts/{id}/archive":{"post":{"tags":["Alerts"],"summary":"Archive an alert","description":"It stops firing at once and leaves the alerts list. Nothing is deleted and it can be restored. Archiving an archived alert is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Alert"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Alert id."}],"operationId":"post-alerts-id-archive","security":[{"apiKey":[]}]}},"/api/alerts/{id}/restore":{"post":{"tags":["Alerts"],"summary":"Restore an archived alert","description":"It is evaluated again on the next sweep (if enabled). Restoring a live alert is a no-op. Needs the admin role; audited.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Alert"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Alert id."}],"operationId":"post-alerts-id-restore","security":[{"apiKey":[]}]}},"/api/audit-log":{"get":{"tags":["Audit log"],"summary":"List audit log entries","description":"Who changed what (assistants, keys, numbers, knowledge, takeovers and more), newest first, one cursor page at a time. A project-scoped key sees only that project's entries.","parameters":[{"name":"actor_id","in":"query","required":false,"description":"Exact actor ID. All filters combine with AND.","schema":{"type":"string"}},{"name":"actor_type","in":"query","required":false,"description":"Actor type.","schema":{"type":"string","enum":["user","api_key","system"]}},{"name":"action","in":"query","required":false,"description":"Comma-separated actions, up to 20 nonempty values. Whitespace around values is ignored. Match any exact action or prefix ending in a dot. Percent and underscore in prefixes are literal.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Inclusive creation time lower bound as an ISO 8601 date or date-time. Dates use midnight UTC; date-times without a timezone use UTC.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Exclusive creation time upper bound as an ISO 8601 date or date-time. Dates use midnight UTC; date-times without a timezone use UTC.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"`next_cursor` from the previous page.","schema":{"type":"string","description":"Opaque next_cursor from the previous page. Legacy ISO timestamp cursors are also accepted."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntry"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page."},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-audit-log","security":[{"apiKey":[]}]}},"/api/projects":{"get":{"tags":["Projects"],"summary":"List projects","description":"Projects in the organization, newest first. A project-scoped key sees only its own project. Archived projects are left out unless `archived=true`.","parameters":[{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"`true`: only archived projects. Absent: only active ones."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-projects","security":[{"apiKey":[]}]},"post":{"tags":["Projects"],"summary":"Create a project","description":"A new project to hold assistants, numbers, keys and webhooks. It becomes the default when the organization has none. Needs an org-wide key: a project-scoped key gets 403 `invalid_request` (\"A project-scoped key cannot create projects.\").","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreate"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"post-projects","security":[{"apiKey":[]}]}},"/api/projects/{id}":{"get":{"tags":["Projects"],"summary":"Get a project","description":"One project, archived or not.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Project id, `proj_...`."}],"operationId":"get-projects-id","security":[{"apiKey":[]}]},"patch":{"tags":["Projects"],"summary":"Update a project","description":"Rename a project, set its default phone country (the ISO 3166 alpha-2 country a lead's phone typed without a country code is read in when the visitor's own country is unknown), or set its timezone and contact hours (when outreach may message and call people). `null` clears any of the last three. Needs the admin role.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"400":{"description":"Validation error: usually `invalid_request`, with the failing fields in `issues` when there are any","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Project id, `proj_...`."}],"operationId":"patch-projects-id","security":[{"apiKey":[]}]}},"/api/projects/{id}/archive":{"post":{"tags":["Projects"],"summary":"Archive a project","description":"Pauses everything the project runs: its assistants stop answering chats and calls, its website chat, forms and booking pages stop taking visitors, follow-ups stop sending, Search starts no checks, and its webhooks and alerts stop. Its live calls are ended. Its records stay readable, phone numbers stay on the account, and nothing is deleted. It leaves the projects list (see `archived=true`). Archiving an archived project is a no-op. Needs the admin role and an org-wide key (a project-scoped key gets 403 `invalid_request`); audited as `project.archived`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`is_default`: make another project the default first. `last_business`: the organization's only active project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Project id, `proj_...`."}],"operationId":"post-projects-id-archive","security":[{"apiKey":[]}]}},"/api/projects/{id}/default":{"post":{"tags":["Projects"],"summary":"Make a project the default","description":"Makes this project the organization's default. The flag moves from the old default in one step; making the default the default again is a no-op. Needs the admin role and an org-wide key (a project-scoped key gets 403 `invalid_request`); audited as `project.default_set`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`archived`: restore the project first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Project id, `proj_...`."}],"operationId":"post-projects-id-default","security":[{"apiKey":[]}]}},"/api/projects/{id}/restore":{"post":{"tags":["Projects"],"summary":"Restore an archived project","description":"Everything the project runs starts again. Restoring an active project is a no-op. Needs the admin role and an org-wide key (a project-scoped key gets 403 `invalid_request`); audited as `project.restored`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused, for example a viewer key on a write (`read_only_key`), a role too low for the route (`insufficient_role`), or a route that needs a console session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or outside what the key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Project id, `proj_...`."}],"operationId":"post-projects-id-restore","security":[{"apiKey":[]}]}},"/api/members":{"get":{"tags":["Members"],"summary":"List organization members","description":"The whole organization roster with roles, without pagination. Needs an org-wide key: a project-scoped key gets 403 `project_key_not_allowed`. Viewer keys are allowed.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrgMember"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (`unauthorized`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`project_key_not_allowed`: this route needs an org-wide API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`). Wait `Retry-After` seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the current 60-second window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets, in Unix seconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}},"operationId":"get-members","security":[{"apiKey":[]}]}}},"components":{"schemas":{"AddLibraryVoiceRequest":{"type":"object","properties":{"public_owner_id":{"type":"string"},"voice_id":{"type":"string"},"name":{"type":"string"}},"required":["public_owner_id","voice_id","name"]},"AddLibraryVoiceResponse":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"AgentIdentityInput":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"Alert":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"metric":{"type":"string","enum":["call_count","cost_total","avg_latency_ms","error_rate"]},"comparator":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"string","description":"Decimal serialized as a string (numeric column)."},"window_seconds":{"type":"string","description":"Integer serialized as a string (numeric column)."},"channel":{"$ref":"#/components/schemas/AlertChannel"},"enabled":{"type":"boolean"},"archived_at":{"type":["string","null"],"format":"date-time","description":"When it was archived; null while live. An archived alert never fires."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","org_id","project_id","name","metric","comparator","threshold","window_seconds","channel","enabled"]},"AlertChannel":{"oneOf":[{"type":"object","required":["type","url"],"properties":{"type":{"type":"string","enum":["webhook"]},"url":{"type":"string","format":"uri","pattern":"^https://","description":"Public HTTPS destination. Private addresses and redirects are refused."}}},{"type":"object","required":["type","url"],"properties":{"type":{"type":"string","enum":["slack"]},"url":{"type":"string","format":"uri","description":"Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/."}}},{"type":"object","required":["type","to"],"properties":{"type":{"type":"string","enum":["email"]},"to":{"type":"string","format":"email","maxLength":254}}}]},"AlertCreate":{"type":"object","properties":{"project_id":{"type":"string","description":"Required for an org-wide key."},"name":{"type":"string","minLength":1},"metric":{"type":"string","enum":["call_count","cost_total","avg_latency_ms","error_rate"]},"comparator":{"type":"string","enum":["gt","gte","lt","lte"],"description":"How the metric compares with the threshold to fire."},"threshold":{"type":"number"},"window_seconds":{"type":"integer","minimum":1,"description":"The rolling window the metric is measured over."},"channel":{"$ref":"#/components/schemas/AlertChannel"},"enabled":{"type":"boolean","description":"Default true."}},"required":["name","metric","comparator","threshold","window_seconds","channel"]},"AlertPatch":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1},"metric":{"type":"string","enum":["call_count","cost_total","avg_latency_ms","error_rate"]},"comparator":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"window_seconds":{"type":"integer","minimum":1},"channel":{"$ref":"#/components/schemas/AlertChannel"},"enabled":{"type":"boolean"}}},"AnalyticsCount":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]},"AnalyticsLatency":{"type":"object","properties":{"calls":{"type":"integer","description":"Live calls with latency measurements in the window and filters. Test calls are not counted."},"e2e":{"$ref":"#/components/schemas/AnalyticsPercentiles"},"stages":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AnalyticsPercentiles"},{"type":"object","properties":{"stage":{"type":"string"}},"required":["stage"]}]}},"slowest":{"type":"array","maxItems":10,"items":{"type":"object","properties":{"call_id":{"type":"string"},"e2e_p95":{"type":"number"},"assistant_id":{"type":"string"},"started_at":{"type":["string","null"],"format":"date-time"}},"required":["call_id","e2e_p95","assistant_id","started_at"]}}},"required":["calls","e2e","stages","slowest"]},"AnalyticsPercentiles":{"type":"object","properties":{"p50":{"type":["number","null"]},"p95":{"type":["number","null"]}},"required":["p50","p95"]},"AnalyticsSearchAiVisits":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"site_id":{"type":"string"},"period":{"type":"string"},"window":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"timezone":{"type":"string"}},"required":["start_date","end_date","timezone"],"additionalProperties":false},"interval":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"classification_version":{"type":"string"},"ai_referral_visits":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"value":{"type":["number","null"]},"complete":{"type":"boolean"}},"required":["collected_days","expected_days","value","complete"],"additionalProperties":false},"by_assistant":{"anyOf":[{"type":"object","properties":{"chatgpt":{"type":"number"},"perplexity":{"type":"number"},"gemini":{"type":"number"},"claude":{"type":"number"},"copilot":{"type":"number"},"other":{"type":"number"}},"required":["chatgpt","perplexity","gemini","claude","copilot","other"],"additionalProperties":false},{"type":"null"}],"description":"Sums to ai_referral_visits.value; null when it is null."},"by_landing_page":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"complete":{"type":"boolean"},"pages":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"visits":{"type":"number"},"by_assistant":{"type":"object","properties":{"chatgpt":{"type":"number"},"perplexity":{"type":"number"},"gemini":{"type":"number"},"claude":{"type":"number"},"copilot":{"type":"number"},"other":{"type":"number"}},"required":["chatgpt","perplexity","gemini","claude","copilot","other"],"additionalProperties":false},"tracked_questions_citing_page":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"citing_answers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["question","citing_answers"],"additionalProperties":false},"description":"Tracked questions whose AI answers in the window cite this page; not the prompts that sent visitors. Empty when none cites it."}},"required":["path","visits","by_assistant","tracked_questions_citing_page"],"additionalProperties":false}},{"type":"null"}]},"page_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Pages with AI visits before the limit."},"visits_outside_site_scope":{"type":["number","null"]}},"required":["collected_days","expected_days","complete","pages","page_count","visits_outside_site_scope"],"additionalProperties":false},"tracked_question_answers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["site_id","period","window","interval","classification_version","ai_referral_visits","by_assistant","by_landing_page","tracked_question_answers"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"AnalyticsSearchGoals":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"site_id":{"type":"string"},"timezone":{"type":"string"},"current":{"type":"object","properties":{"clicks_from_search_per_month":{"type":"object","properties":{"value":{"type":["number","null"]},"start_date":{"type":"string"},"end_date":{"type":"string"}},"required":["value","start_date","end_date"],"additionalProperties":false},"leads_from_search_per_month":{"type":"object","properties":{"value":{"type":["number","null"]},"start_date":{"type":"string"},"end_date":{"type":"string"}},"required":["value","start_date","end_date"],"additionalProperties":false},"money_searches_on_page_one":{"type":"object","properties":{"value":{"type":["number","null"]},"start_date":{"type":"string"},"end_date":{"type":"string"}},"required":["value","start_date","end_date"],"additionalProperties":false}},"required":["clicks_from_search_per_month","leads_from_search_per_month","money_searches_on_page_one"],"additionalProperties":false},"sources":{"type":"object","properties":{"queries":{"type":["string","null"]}},"required":["queries"],"additionalProperties":false},"goals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"site_id":{"type":"string"},"metric":{"type":"string","enum":["clicks_from_search_per_month","leads_from_search_per_month","money_searches_on_page_one"]},"target":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"due_date":{"type":"string"},"label":{"type":["string","null"]},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"archived_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"current":{"type":["number","null"]},"percent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"status":{"anyOf":[{"type":"string","enum":["on_track","behind","done"]},{"type":"null"}]}},"required":["id","site_id","metric","target","due_date","label","version","archived_at","created_at","updated_at","current","percent","status"],"additionalProperties":false}}},"required":["site_id","timezone","current","sources","goals"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"AnalyticsSearchKeywords":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"site_id":{"type":"string"},"window":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"timezone":{"type":"string"}},"required":["start_date","end_date","timezone"],"additionalProperties":false},"source":{"type":["string","null"]},"coverage":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"complete":{"type":"boolean"}},"required":["collected_days","expected_days","complete"],"additionalProperties":false},"query_scope":{"type":"string","const":"reported_by_google"},"thresholds":{"type":"object","properties":{"defend_max_position":{"type":"number"},"near_page_one_min_position":{"type":"number"},"near_page_one_max_position":{"type":"number"},"near_page_one_min_impressions":{"type":"number"}},"required":["defend_max_position","near_page_one_min_position","near_page_one_max_position","near_page_one_min_impressions"],"additionalProperties":false},"counts":{"type":"object","properties":{"defend":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"near_page_one":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"services":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"places":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"dated":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["defend","near_page_one","services","places","dated"],"additionalProperties":false},"groups":{"type":"object","properties":{"defend":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"position":{"description":"Impression-weighted average position over the window.","type":["number","null"]},"clicks":{"type":"number"},"impressions":{"type":"number"},"top_page":{"description":"The page with most clicks, then impressions: a path on the site, else a URL.","type":["string","null"]}},"required":["query","position","clicks","impressions","top_page"],"additionalProperties":false}},"near_page_one":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"position":{"description":"Impression-weighted average position over the window.","type":["number","null"]},"clicks":{"type":"number"},"impressions":{"type":"number"},"top_page":{"description":"The page with most clicks, then impressions: a path on the site, else a URL.","type":["string","null"]}},"required":["query","position","clicks","impressions","top_page"],"additionalProperties":false}},"services":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"position":{"description":"Impression-weighted average position over the window.","type":["number","null"]},"clicks":{"type":"number"},"impressions":{"type":"number"},"top_page":{"description":"The page with most clicks, then impressions: a path on the site, else a URL.","type":["string","null"]}},"required":["query","position","clicks","impressions","top_page"],"additionalProperties":false}},"places":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"position":{"description":"Impression-weighted average position over the window.","type":["number","null"]},"clicks":{"type":"number"},"impressions":{"type":"number"},"top_page":{"description":"The page with most clicks, then impressions: a path on the site, else a URL.","type":["string","null"]}},"required":["query","position","clicks","impressions","top_page"],"additionalProperties":false}},"dated":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"position":{"description":"Impression-weighted average position over the window.","type":["number","null"]},"clicks":{"type":"number"},"impressions":{"type":"number"},"top_page":{"description":"The page with most clicks, then impressions: a path on the site, else a URL.","type":["string","null"]}},"required":["query","position","clicks","impressions","top_page"],"additionalProperties":false}}},"required":["defend","near_page_one","services","places","dated"],"additionalProperties":false}},"required":["site_id","window","source","coverage","query_scope","thresholds","counts","groups"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"AnalyticsSearchMonthly":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"site_id":{"type":"string"},"timezone":{"type":"string"},"query_scope":{"type":"string","const":"reported_by_google"},"leads_recorded_from":{"type":"string"},"sources":{"type":"object","properties":{"search":{"type":["string","null"]},"queries":{"type":["string","null"]},"countries":{"type":["string","null"]}},"required":["search","queries","countries"],"additionalProperties":false},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"YYYY-MM"},"start_date":{"type":"string"},"end_date":{"type":"string"},"clicks":{"description":"Null unless every day of the month was imported.","type":["number","null"]},"impressions":{"description":"Null unless every day of the month was imported.","type":["number","null"]},"ctr":{"description":"Clicks divided by impressions, 0 to 1.","type":["number","null"]},"position":{"description":"Impression-weighted average position from the property totals.","type":["number","null"]},"queries_top_3":{"description":"Queries Google reported with a month average position of 3 or better.","type":["number","null"]},"queries_top_10":{"description":"The same, 10 or better.","type":["number","null"]},"leads_from_search":{"description":"Leads from Google, Bing and AI assistants captured that month; null for a month that ended before leads_recorded_from.","type":["number","null"]},"coverage":{"type":"object","properties":{"search":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["collected_days","expected_days"],"additionalProperties":false},"queries":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["collected_days","expected_days"],"additionalProperties":false}},"required":["search","queries"],"additionalProperties":false},"year_earlier":{"type":"object","properties":{"month":{"type":"string","description":"YYYY-MM"},"start_date":{"type":"string"},"end_date":{"type":"string"},"clicks":{"description":"Null unless every day of the month was imported.","type":["number","null"]},"impressions":{"description":"Null unless every day of the month was imported.","type":["number","null"]},"ctr":{"description":"Clicks divided by impressions, 0 to 1.","type":["number","null"]},"position":{"description":"Impression-weighted average position from the property totals.","type":["number","null"]},"queries_top_3":{"description":"Queries Google reported with a month average position of 3 or better.","type":["number","null"]},"queries_top_10":{"description":"The same, 10 or better.","type":["number","null"]},"leads_from_search":{"description":"Leads from Google, Bing and AI assistants captured that month; null for a month that ended before leads_recorded_from.","type":["number","null"]},"coverage":{"type":"object","properties":{"search":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["collected_days","expected_days"],"additionalProperties":false},"queries":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["collected_days","expected_days"],"additionalProperties":false}},"required":["search","queries"],"additionalProperties":false}},"required":["month","start_date","end_date","clicks","impressions","ctr","position","queries_top_3","queries_top_10","leads_from_search","coverage"],"additionalProperties":false},"change":{"type":"object","properties":{"clicks_pct":{"description":"Whole percent; null when either month is null or the year-earlier one is zero.","type":["number","null"]},"impressions_pct":{"type":["number","null"]},"queries_top_3_pct":{"type":["number","null"]},"queries_top_10_pct":{"type":["number","null"]},"ctr_points":{"description":"Percentage points, one decimal.","type":["number","null"]},"position_gain":{"description":"Year-earlier position minus this one, one decimal: positive means higher up.","type":["number","null"]},"leads_from_search_delta":{"type":["number","null"]}},"required":["clicks_pct","impressions_pct","queries_top_3_pct","queries_top_10_pct","ctr_points","position_gain","leads_from_search_delta"],"additionalProperties":false}},"required":["month","start_date","end_date","clicks","impressions","ctr","position","queries_top_3","queries_top_10","leads_from_search","coverage","year_earlier","change"],"additionalProperties":false}},"countries":{"anyOf":[{"type":"object","properties":{"month":{"type":"string"},"year_earlier_month":{"type":"string"},"coverage":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["collected_days","expected_days"],"additionalProperties":false},"year_earlier_coverage":{"type":"object","properties":{"collected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["collected_days","expected_days"],"additionalProperties":false},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"clicks":{"type":"number"},"year_earlier_clicks":{"type":["number","null"]},"change_pct":{"type":["number","null"]}},"required":["country","clicks","year_earlier_clicks","change_pct"],"additionalProperties":false}},{"type":"null"}],"description":"Null unless every day of the month was imported."}},"required":["month","year_earlier_month","coverage","year_earlier_coverage","items"],"additionalProperties":false},{"type":"null"}],"description":"Null when no import is split by country."}},"required":["site_id","timezone","query_scope","leads_recorded_from","sources","months","countries"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"AnalyticsVolume":{"type":"object","properties":{"total_calls":{"type":"integer"},"total_minutes":{"type":"number"},"completed":{"type":"integer"},"failed":{"type":"integer"},"by_status":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AnalyticsCount"},{"type":"object","properties":{"status":{"type":"string"}},"required":["status"]}]}},"by_call_type":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AnalyticsCount"},{"type":"object","properties":{"call_type":{"type":"string"}},"required":["call_type"]}]}},"by_canonical_ended_reason":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AnalyticsCount"},{"type":"object","properties":{"ended_reason":{"type":"string"}},"required":["ended_reason"]}]}},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"calls":{"type":"integer"},"minutes":{"type":"number"}},"required":["date","calls","minutes"]}}},"required":["total_calls","total_minutes","completed","failed","by_status","by_call_type","by_canonical_ended_reason","daily"]},"Assistant":{"type":"object","properties":{"effective_hours":{"type":"object","description":"Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.","properties":{"value":{"type":["array","null"],"items":{"type":"object","properties":{"day":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"open":{"type":"string"},"close":{"type":"string"}},"required":["day","open","close"]}},"source":{"type":["string","null"],"enum":["assistant","business",null]}},"required":["value","source"]},"effective_timezone":{"type":"object","description":"Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.","properties":{"value":{"type":["string","null"]},"source":{"type":["string","null"],"enum":["assistant","business",null]}},"required":["value","source"]},"effective_team_phone":{"type":"object","description":"Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.","properties":{"value":{"type":["string","null"]},"source":{"type":["string","null"],"enum":["assistant","business",null]}},"required":["value","source"]},"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"config":{"$ref":"#/components/schemas/AssistantConfig"},"version":{"type":"integer"},"draft_revision":{"type":"integer","description":"The revision a draft save names as expected_draft_revision; 0 before the first draft."},"draft":{"type":["object","null"],"description":"Whether a draft exists, without its config (GET /assistants/{id}/draft has it).","properties":{"revision":{"type":"integer"},"base_version":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time","description":"When it was archived; null while live. Archived, no widget, chat or call serves it."}},"required":["id","org_id","project_id","name","config","version","effective_hours","effective_timezone","effective_team_phone"]},"AssistantAvatar":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]},"AssistantAvatarUpload":{"type":"object","properties":{"content_type":{"type":"string","enum":["image/png","image/jpeg","image/webp"]},"base64":{"type":"string","description":"The file's bytes, base64-encoded."}},"required":["content_type","base64"]},"AssistantConfig":{"type":"object","description":"The runtime profile minus per-call fields. agent.instructions and either session.realtime or the complete session.{llm,stt,tts} pipeline are required. Realtime requires provider; its model may use the runtime default. A pipeline LLM may omit provider for a LiveKit-hosted model id. Credentials are write-only: recording.s3.{access_key,secret,session_token} come back as `<key>_set: boolean`, and a write that omits one keeps the stored value. GA4 API secrets are not part of the config: they are set with PUT /v1/assistants/{id}/integrations/google-analytics and stored as the organization's google_analytics connection; integrations.google_analytics and channels.web_chat.analytics.ga4 keep the measurement ID and read back `api_secret_set: true` when its secret is stored, and a write that sends `api_secret` in either place is refused with 400. Chat (web or WhatsApp) answers with channels.web_chat.llm, defaulting independently to openai/gpt-6.1-terra with medium reasoning; creating or enabling web chat, or changing that model while web chat or WhatsApp routing is live, is refused with 400 when chat has no adapter for its provider.","properties":{"scheduling":{"type":"object","additionalProperties":false,"required":["version","event_type_ids"],"properties":{"version":{"type":"integer","const":1},"event_type_ids":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string"}}},"description":"Events this assistant may offer. Every event must be published, active, public and in the assistant project. Test calls/chats use the draft selection and test occupancy."},"agent":{"type":"object","properties":{"instructions":{"type":"string"}},"required":["instructions"]},"tools":{"$ref":"#/components/schemas/AssistantTools"},"session":{"type":"object","properties":{"llm":{"type":"object","properties":{"provider":{"type":"string","minLength":1},"model":{"type":"string","minLength":1}},"required":["model"],"additionalProperties":true},"realtime":{"type":"object","properties":{"provider":{"type":"string","minLength":1},"model":{"type":"string","minLength":1}},"required":["provider"],"additionalProperties":true},"stt":{"$ref":"#/components/schemas/ProviderModel"},"tts":{"$ref":"#/components/schemas/ProviderModel"},"tools":{"$ref":"#/components/schemas/AssistantTools"}},"anyOf":[{"required":["realtime"]},{"required":["llm","stt","tts"]}],"additionalProperties":true},"variables":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/AssistantVariableDef"},"description":"Authoring-time schema for {{key}} placeholders in agent.instructions, agent.context, agent.first_message, and agent.first_message_instructions; never delivered to the runtime."},"lead_capture":{"type":"object","additionalProperties":true,"description":"Which lead details the assistant asks for, on every channel: enabled, prompt, require_complete and fields (key, label, type `string`, `email` or `phone`, required, options). When set it replaces `channels.web_chat.lead_capture` as a whole object, with no field merge; that older key is still read when this one is absent.","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"},"require_complete":{"type":"boolean"},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["string","email","phone","number"]},"required":{"type":"boolean"},"options":{"type":"array","maxItems":6,"items":{"type":"string","minLength":1,"maxLength":60}}},"required":["key"]}}}},"knowledge":{"type":"object","maxProperties":50,"additionalProperties":{"type":"object","properties":{"chat":{"type":"boolean","description":"Search it in web chat and WhatsApp."},"voice":{"type":"boolean","description":"Search it on calls. Needs a pipeline session, not realtime."},"priority":{"type":"integer","minimum":0,"maximum":100,"description":"Each search reaches up to four of the attached bases that have a live publication, highest priority first (then by id), and searches them in parallel."}},"required":["chat","voice","priority"],"additionalProperties":false},"description":"The knowledge bases the assistant answers from, by knowledge base id (`kb_...`). Unlike the rest of the config, leaving it out of a write keeps the stored selection; send `{}` to detach every base. An entry with both `chat` and `voice` false counts as detached. Changing it needs an org-wide key and editor access to each base: 403 `organization_knowledge_access_required` for a project key or `knowledge_forbidden` without editor access, 400 `knowledge_base_not_found` for an unknown id, 409 `knowledge_voice_requires_pipeline_assistant` for voice on a realtime session. Each refusal names the base in `knowledge_base_id`."}},"required":["agent","session"],"additionalProperties":true},"AssistantCreate":{"type":"object","properties":{"project_id":{"type":"string","description":"Required for an org-wide key; ignored (must match) for a project-scoped key."},"name":{"type":"string","minLength":1},"config":{"$ref":"#/components/schemas/AssistantConfig"}},"required":["name","config"]},"AssistantDraft":{"type":["object","null"],"required":["effective_hours","effective_timezone","effective_team_phone"],"properties":{"effective_hours":{"type":"object","description":"Effective handoff weekly windows, resolved at read time. Omitted or null weekly inherits the current business site profile; an explicit empty array overrides it with unrestricted hours. Holidays remain assistant-owned.","properties":{"value":{"type":["array","null"],"items":{"type":"object","properties":{"day":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"open":{"type":"string"},"close":{"type":"string"}},"required":["day","open","close"]}},"source":{"type":["string","null"],"enum":["assistant","business",null]}},"required":["value","source"]},"effective_timezone":{"type":"object","description":"Effective handoff IANA time zone. Missing or blank inherits the business site profile. Both value and source are null when neither has a value.","properties":{"value":{"type":["string","null"]},"source":{"type":["string","null"],"enum":["assistant","business",null]}},"required":["value","source"]},"effective_team_phone":{"type":"object","description":"Effective team contact phone. Missing or blank inherits the first effective phone in the business site profile; it does not authorize voice transfers. Both value and source are null when unset.","properties":{"value":{"type":["string","null"]},"source":{"type":["string","null"],"enum":["assistant","business",null]}},"required":["value","source"]},"assistant_id":{"type":"string"},"config":{"$ref":"#/components/schemas/AssistantConfig"},"hidden_changes":{"type":"array","items":{"type":"string"},"description":"Paths that differ from live but read back the same: credentials and tool request specs. Values are never returned."},"revision":{"type":"integer"},"base_version":{"type":"integer","description":"The live version the draft started from."},"live_version":{"type":"integer"},"stale":{"type":"boolean","description":"Live was edited after the draft started; publishing is refused."},"updated_at":{"type":"string","format":"date-time"}}},"AssistantDraftRebase":{"type":"object","properties":{"expected_draft_revision":{"type":"integer","minimum":0},"keep_draft":{"type":"boolean","description":"Keep the draft's value where live changed the same setting differently."}}},"AssistantDraftSave":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/AssistantConfig"},"expected_draft_revision":{"type":"integer","minimum":0,"description":"The draft_revision the caller read. A save over a newer draft is refused with 409 draft_conflict."},"expected_version":{"type":"integer","minimum":1,"description":"The live version the caller edited from. A save that starts a new draft is refused with 409 live_changed when live has moved on since."}},"required":["config"]},"AssistantPatch":{"type":"object","description":"At least one of `name` and `config`.","minProperties":1,"properties":{"name":{"type":"string","minLength":1},"config":{"$ref":"#/components/schemas/AssistantConfig"},"expected_version":{"type":"integer","minimum":1,"description":"The version the caller read. A save over a newer version is refused with 409 version_conflict and the current_version."}}},"AssistantPublish":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"expected_draft_revision":{"type":"integer","minimum":0},"note":{"type":"string","maxLength":500}}},"AssistantRestore":{"type":"object","properties":{"target":{"type":"string","enum":["draft","live"],"default":"draft"},"expected_version":{"type":"integer","minimum":1},"expected_draft_revision":{"type":"integer","minimum":0}}},"AssistantToolDefinition":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","additionalProperties":true,"description":"JSON Schema for the arguments, as exposed to the model."},"enabled":{"type":"boolean","default":true,"description":"False keeps the tool saved, with its request, but offers it on no channel."},"channels":{"type":"array","items":{"type":"string","enum":["text","voice"]},"minItems":1,"uniqueItems":true,"description":"Where the tool is offered: text is web chat and WhatsApp, voice is every call including browser sandbox calls. Absent means both."},"read_only":{"type":"boolean","default":false,"description":"True when the tool only looks things up. Sandbox and preview chats call only read-only tools; any other tool answers that requests are off in a sandbox chat."},"request":{"type":"object","writeOnly":true,"description":"Server-side HTTP execution spec, never returned on reads. A write that omits it keeps the stored spec for the same tool name; removing or renaming the tool drops it.","properties":{"url":{"type":"string","format":"uri"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"timeout_ms":{"type":"integer","minimum":1,"maximum":120000}},"required":["url"]}},"required":["name"],"additionalProperties":true},"AssistantTools":{"type":"object","description":"Custom tools. config.tools is the canonical home; the legacy session.tools is read only when config.tools is absent.","properties":{"definitions":{"type":"array","items":{"$ref":"#/components/schemas/AssistantToolDefinition"}}},"additionalProperties":true},"AssistantVariableDef":{"type":"object","properties":{"key":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_.-]*$","maxLength":64},"label":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":500},"default":{"type":"string","maxLength":2000}},"required":["key"],"additionalProperties":true},"AssistantVersion":{"type":"object","properties":{"assistant_id":{"type":"string"},"version":{"type":"integer"},"name":{"type":"string"},"source":{"type":"string","enum":["create","api_edit","publish","restore","bulk_update","seed"]},"created_by":{"type":["string","null"]},"note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"config":{"$ref":"#/components/schemas/AssistantConfig"}},"required":["assistant_id","version","source"]},"AuditEntry":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":["string","null"]},"actor_type":{"type":"string","enum":["user","api_key","system"]},"actor_id":{"type":"string"},"actor_label":{"type":["string","null"]},"action":{"type":"string"},"resource_type":{"type":"string"},"resource_id":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","org_id","project_id","actor_type","actor_id","actor_label","action","resource_type","resource_id","metadata","created_at"]},"AvailablePhoneNumber":{"type":"object","properties":{"phoneNumber":{"type":"string"},"locality":{"type":["string","null"]},"region":{"type":["string","null"]},"friendlyName":{"type":"string"},"countryCode":{"type":"string"},"capabilities":{"type":"object","additionalProperties":{"type":"boolean"}}},"required":["phoneNumber","locality","region"]},"Call":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"assistant_id":{"type":"string"},"call_type":{"type":"string","enum":["inbound","outbound","web"]},"status":{"type":"string","enum":["ringing","in_progress","completed","failed","no_answer","busy","cancelled"]},"mode":{"type":"string","enum":["live","test"],"description":"Set when the call is created and never changed. A sandbox call ran the assistant's draft with sandbox restrictions (read-only declared tools run server-side, no transfers), its webhooks carry livemode: false and reach sandbox subscriptions only, and it stays out of analytics and alerts."},"customer_number":{"type":["string","null"]},"agent_number":{"type":["string","null"]},"room_name":{"type":["string","null"],"description":"Admins, owners, API keys and staff only."},"ended_reason":{"type":["string","null"]},"ended_reason_canonical":{"type":["string","null"],"description":"Closed-enum normalization of ended_reason."},"started_at":{"type":["string","null"],"format":"date-time"},"connected_at":{"type":["string","null"],"format":"date-time"},"ended_at":{"type":["string","null"],"format":"date-time"},"duration_ms":{"type":["integer","null"]},"recording_url":{"type":["string","null"]},"transfer_outcome":{"type":["string","null"],"description":"Normalized warm-transfer outcome when the call involved a transfer."},"summary":{"type":["string","null"],"description":"List only: the post-call analysis summary, or null when none is recorded."},"lead":{"type":["object","null"],"description":"List and detail: the lead captured by this call or explicitly linked through a returning enquiry or web chat. Null when none is linked.","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"captured":{"type":"boolean","description":"True only when this call created the lead."}},"required":["id","name"]},"transcript":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CallTranscriptMessage"},"description":"Null until the call has ended. Members and viewers get user and assistant turns only, with tool calls reduced to id and name."},"agent_configuration":{"type":["object","null"],"additionalProperties":true,"description":"Prompt snapshot. Admins, owners, API keys and staff only."},"provider_metadata":{"type":["object","null"],"additionalProperties":true,"description":"Admins, owners, API keys and staff only."},"metadata":{"type":["object","null"],"additionalProperties":true,"description":"Admins, owners, API keys and staff only."},"variables":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Admins, owners, API keys and staff only."},"unresolved_variables":{"type":["array","null"],"items":{"type":"string"},"description":"Admins, owners, API keys and staff only."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","org_id","project_id","assistant_id","call_type","status","mode"]},"CallCost":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string"},"provider":{"type":["string","null"]},"model":{"type":["string","null"]},"unit":{"type":"string"},"quantity":{"type":"string"},"unit_price":{"type":["string","null"],"description":"Staff only."},"amount":{"type":["string","null"],"description":"Staff only."},"currency":{"type":"string","description":"Staff only."},"plan_tier":{"type":["string","null"],"enum":["build","ship","scale",null],"description":"Staff only."}},"required":["id","category","unit","quantity"]},"CallDetail":{"allOf":[{"$ref":"#/components/schemas/Call"},{"type":"object","properties":{"costs":{"type":"array","items":{"$ref":"#/components/schemas/CallCost"},"description":"Admins, owners, API keys and staff only; amounts and prices for staff only."},"recordings":{"type":"array","items":{"$ref":"#/components/schemas/CallRecording"}},"performance":{"oneOf":[{"$ref":"#/components/schemas/CallPerformance"},{"type":"null"}],"description":"Admins, owners, API keys and staff only."},"transcript":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CallTranscriptMessage"}},"analysis":{"type":["object","null"],"description":"Post-call analysis when the assistant has it enabled.","properties":{"summary":{"type":["string","null"]},"structured":{"type":["object","null"],"additionalProperties":true}}},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"},"maxItems":200,"description":"Admins, owners, API keys and staff only."},"events_truncated":{"type":"boolean","description":"True when more than 200 webhook events exist for this call. Admins, owners, API keys and staff only."}},"required":["lead","recordings","transcript"]}]},"CallHangupResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"hangup_requested":{"type":"boolean"}},"required":["id","hangup_requested"]}},"required":["data"]},"CallListenResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string"},"url":{"type":"string"},"room":{"type":"string"}},"required":["token","url","room"]}},"required":["data"]},"CallPerformance":{"type":"object","properties":{"id":{"type":"string"},"metrics":{"type":"object"},"e2e_p50_ms":{"type":["string","null"]},"e2e_p95_ms":{"type":["string","null"]},"e2e_max_ms":{"type":["string","null"]},"num_interruptions":{"type":["integer","null"]},"total_turns":{"type":["integer","null"]},"latency_summary":{"type":["object","null"],"additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"min":{"type":"number"},"mean":{"type":"number"},"p50":{"type":"number"},"p95":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["count","min","mean","p50","p95","p99","max"]}}},"required":["id","metrics"]},"CallRecording":{"type":"object","description":"Private S3 recording metadata. Storage coordinates and access URLs are not included.","properties":{"id":{"type":"string"},"leg_type":{"type":"string","enum":["main","consult","post_transfer"]},"attempt_id":{"type":["string","null"]},"status":{"type":"string","enum":["pending","recording","processing","ready","failed","deleted"]},"content_type":{"type":["string","null"]},"size_bytes":{"type":["integer","null"],"minimum":0},"duration_ms":{"type":["integer","null"],"minimum":0},"channels":{"type":["integer","null"],"minimum":1},"started_at":{"type":["string","null"],"format":"date-time","description":"Audio timeline origin for transcript alignment."},"ended_at":{"type":["string","null"],"format":"date-time"},"ready_at":{"type":["string","null"],"format":"date-time"},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","leg_type","attempt_id","status","content_type","size_bytes","duration_ms","channels","started_at","ended_at","ready_at","deleted_at","created_at","updated_at"]},"CallTranscriptMessage":{"type":"object","description":"One turn of a call transcript, the same shape as `messages` in the `call.ended` webhook.","properties":{"role":{"type":"string","enum":["user","assistant","tool"]},"content":{"type":"string"},"tool_call_id":{"type":"string","description":"Tool-result turns: the tool call this answers."},"tool_calls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"arguments":{"type":"object","additionalProperties":true}},"required":["id","name"]}},"occurred_at":{"type":"string","format":"date-time"},"seconds_from_start":{"type":["number","null"],"description":"Offset from the recording start (or from when the call connected), for lining the transcript up with audio."},"duration_ms":{"type":["number","null"],"description":"How long the turn was spoken, in milliseconds (can be fractional)."},"metadata":{"type":"object","additionalProperties":true}},"required":["role","content"],"additionalProperties":true},"ChatAttribution":{"type":"object","description":"Where a chat came from, stored as conversation metadata.attribution. Only chat_page is kept without analytics consent.","properties":{"chat_page":{"type":"string","description":"The path the visitor started chatting on."},"visit":{"$ref":"#/components/schemas/ChatAttributionTouch","description":"This visit's landing."},"first":{"allOf":[{"$ref":"#/components/schemas/ChatAttributionTouch"},{"type":"object","properties":{"at":{"type":"string","format":"date-time","description":"When the visitor first landed."}}}],"description":"The visitor's first-ever landing."},"latest_paid":{"allOf":[{"$ref":"#/components/schemas/ChatAttributionTouch"},{"type":"object","properties":{"at":{"type":"string","format":"date-time","description":"When the visitor landed from this ad click."}}}],"description":"The visitor's latest ad click within 90 days: a landing with a click id, or with `utm_medium` cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from `visit` and `first`."}}},"ChatAttributionTouch":{"type":"object","description":"One landing. Every field is optional; strings are trimmed and capped at 200 characters.","properties":{"landing_page":{"type":"string","description":"A path starting with /, without query or fragment."},"referrer_host":{"type":"string"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_term":{"type":"string"},"utm_content":{"type":"string"},"gclid":{"type":"string"},"gbraid":{"type":"string"},"wbraid":{"type":"string"},"fbclid":{"type":"string"},"msclkid":{"type":"string"},"oppref":{"type":"string"},"ctwa_clid":{"type":"string","description":"WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral."},"ad_id":{"type":"string","description":"WhatsApp only: the ad or post id (`source_id`) from Meta's referral."},"ad_source_type":{"type":"string","description":"WhatsApp only: `ad` or `post`."},"ad_source_url":{"type":"string","description":"WhatsApp only: the ad's URL, up to 512 characters."},"ad_headline":{"type":"string","description":"WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified)."},"whatsapp_link_id":{"type":"string","description":"WhatsApp only: the campaign link (`wal_...`) the chat started from."},"whatsapp_link_name":{"type":"string","description":"WhatsApp only: that campaign link's name."}}},"ChatEngagement":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"depth":{"type":"array","description":"Chats by visitor messages: buckets `1`, `2`, `3`, `4-6`, `7+`.","items":{"type":"object","properties":{"bucket":{"type":"string"},"conversations":{"type":"integer"},"leads":{"type":"integer"}},"required":["bucket","conversations","leads"]}},"open_to_first_message":{"type":"object","properties":{"samples":{"type":"integer"},"p50_s":{"type":["integer","null"]},"p90_s":{"type":["integer","null"]},"by_reason":{"type":"object","additionalProperties":{"type":"object","properties":{"samples":{"type":"integer"},"p50_s":{"type":["integer","null"]}}}}}},"time_to_lead":{"type":"object","properties":{"samples":{"type":"integer"},"p50_s":{"type":["integer","null"]},"p90_s":{"type":["integer","null"]},"p50_messages":{"type":["integer","null"]}}},"heatmap":{"type":"object","properties":{"tz":{"type":"string"},"cells":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","description":"1 (Monday) to 7."},"hour":{"type":"integer"},"conversations":{"type":"integer"},"leads":{"type":"integer"}},"required":["weekday","hour","conversations","leads"]}}}},"out_of_hours":{"type":"object","description":"`measured`: chats whose assistant sets working hours; `conversations`: of those, started while closed. The same for chats with a lead.","properties":{"measured":{"type":"integer"},"conversations":{"type":"integer"},"measured_leads":{"type":"integer"},"leads":{"type":"integer"}}}},"required":["depth","open_to_first_message","time_to_lead","heatmap","out_of_hours"]},"ChatFailure":{"type":"object","properties":{"id":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"route":{"type":"string","enum":["config","events","create","message"]},"outcome":{"type":"string"},"status_code":{"type":"integer"},"site":{"type":["string","null"]},"sampled":{"type":"boolean"},"request_id":{"type":["string","null"]},"conversation_id":{"type":["string","null"]},"client_message_id":{"type":["string","null"]},"device":{"type":["string","null"]},"browser":{"type":["string","null"]},"widget_version":{"type":["string","null"]},"assistant_id":{"type":["string","null"]}},"required":["id","occurred_at","route","outcome","status_code"]},"ChatFunnel":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"group_by":{"type":"string"},"compare":{"type":["string","null"],"enum":["previous","average_7",null],"description":"The comparison in `previous`, or null."},"tz":{"type":"string","description":"The time zone `hour_of_day` was counted in."},"signals":{"type":["object","null"],"description":"With group_by=none only, else null. Per page view, under the funnel's rules: the top countries and browser languages (stored only with analytics consent, from widgets that send them), page views from automated browsers (`navigator.webdriver`, still counted in the funnel), and from `page_exit` events: median visible seconds, deepest scroll by quarter, how often the visitor closed the chat that opened and after how long, and why the opener did not fire (`auto_open`).","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"page_views":{"type":"integer"}},"required":["country","page_views"]}},"located_page_views":{"type":"integer"},"languages":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"page_views":{"type":"integer"}},"required":["language","page_views"]}},"automated_page_views":{"type":"integer"},"exits":{"type":"object","properties":{"page_views":{"type":"integer"},"median_visible_s":{"type":["integer","null"]},"scroll":{"type":"object","additionalProperties":{"type":"integer"},"description":"Keys `0`, `25`, `50`, `75`, `100`."},"opened":{"type":"integer","description":"Page views where the panel opened; a card alone does not count."},"closed":{"type":"integer","description":"Of those, the visitor closed the panel. A card put away is not a close."},"median_closed_after_s":{"type":["integer","null"]}},"required":["page_views","median_visible_s","scroll","opened","closed","median_closed_after_s"]},"auto_open":{"type":"object","additionalProperties":{"type":"integer"},"description":"Page views by `page_exit` `auto_open` outcome, `consent_held` included."},"banner_page_views":{"type":"integer","description":"Page views where a cookie or consent banner was up (`page_exit` `banner`)."}},"required":["countries","located_page_views","languages","automated_page_views","exits","auto_open","banner_page_views"]},"visits_since":{"type":["string","null"],"format":"date-time","description":"When this scope's first page view tied to a visit arrived; visit counts start here. Null before any did."},"page_views_since":{"type":["string","null"],"format":"date-time","description":"When this scope's first page view the widget reported arrived; page-view stages start here. Null before any did."},"groups":{"type":"array","items":{"allOf":[{"type":"object","properties":{"page_views":{"type":"object","description":"Distinct page views per stage. Events without a page_view_id are excluded.","properties":{"loaded":{"type":"integer"},"shown":{"type":"integer"},"card":{"type":"integer","description":"A card (nudge, continue, link follow-up or teaser) showed: `card_shown`."},"opened":{"type":"integer"},"typed":{"type":"integer"},"sent":{"type":"integer"}},"required":["loaded","shown","card","opened","typed","sent"]},"visits":{"type":"object","description":"Distinct visits (a run of page views by one browser) per stage, with the same filters as page_views. Only events that carry a visit_id count: visits exist only with analytics consent and a current widget.","properties":{"loaded":{"type":"integer"},"shown":{"type":"integer"},"card":{"type":"integer","description":"A card (nudge, continue, link follow-up or teaser) showed: `card_shown`."},"opened":{"type":"integer"},"typed":{"type":"integer"},"sent":{"type":"integer"}},"required":["loaded","shown","card","opened","typed","sent"]},"opens":{"type":"object","description":"Distinct page views opened for each reason, counted separately: a page view the widget opened by itself (`proactive`) and the visitor later reopened (`visitor`) counts in both. `page_views.opened` mixes them.","properties":{"visitor":{"type":"integer"},"proactive":{"type":"integer"},"api":{"type":"integer"}},"required":["visitor","proactive","api"]},"cards":{"type":"object","description":"Distinct page views where each card showed (`card_shown`), counted separately.","properties":{"nudge":{"type":"integer"},"continue":{"type":"integer"},"follow_up":{"type":"integer"},"teaser":{"type":"integer"}},"required":["nudge","continue","follow_up","teaser"]},"opens_from":{"type":"object","description":"Distinct page views opened, by what opened them (`widget_opened` `from`): the launcher, the nudge (or the classic teaser), the continue card (or its start-fresh button), the link follow-up card, the host's API, or by itself (`auto`). Visitor opens from widgets that predate `from` count in none of these.","properties":{"launcher":{"type":"integer"},"nudge":{"type":"integer"},"continue":{"type":"integer"},"follow_up":{"type":"integer"},"api":{"type":"integer"},"auto":{"type":"integer"}},"required":["launcher","nudge","continue","follow_up","api","auto"]},"first_sends":{"type":"object","description":"Of `conversations`: by how the first message was sent (`message_send` `source`): typed, a reply chip, a starter, a nudge answer, a continue-card draft, or the contact card. Chats from widgets that predate `source` count in none.","properties":{"typed":{"type":"integer"},"reply":{"type":"integer"},"starter":{"type":"integer"},"nudge":{"type":"integer"},"continue":{"type":"integer"},"contact":{"type":"integer"}},"required":["typed","reply","starter","nudge","continue","contact"]},"crawlers":{"type":["object","null"],"description":"Page views from declared crawlers (device `bot`), which every other count leaves out, and how many the widget opened by itself. Only for group_by none, site, page, hour, hour_of_day and assistant; null otherwise.","properties":{"loaded":{"type":"integer"},"opened":{"type":"integer"}},"required":["loaded","opened"]},"visitors":{"type":"integer","description":"Distinct visitor ids among widget_loaded events."},"returning_visits":{"type":"integer","description":"Distinct visits among widget_loaded events whose visit_number is above 1."},"identified_page_views":{"type":"integer","description":"Distinct page views among widget_loaded events that carry a visit_id. Divide by tracked_page_views for coverage."},"tracked_page_views":{"type":"integer","description":"Distinct page views since visit tracking started for this scope (the response's visits_since); 0 before it started. The coverage denominator, so earlier, untracked weeks do not count as untracked traffic."},"sends":{"type":["object","null"],"properties":{"pressed":{"type":"integer"},"accepted":{"type":"integer"},"answered":{"type":"integer"},"failed":{"type":"integer"},"refused":{"type":"integer"}}},"conversations":{"type":["integer","null"],"description":"Chats with a visitor message started in the window, in every grouping: a chat takes the page, source and device of the page view its first message was sent from, or the group `untracked` when there is none. Sandbox chats and live chats our rules caught (test markers, preview hosts, internal lead emails) are left out (see excluded and excluded_traffic)."},"deep_conversations":{"type":"integer","description":"Of conversations: chats with three or more visitor messages."},"single_message_conversations":{"type":"integer","description":"Of conversations: chats where the visitor sent one message and stopped."},"leads":{"type":["integer","null"],"description":"Leads saved in the window, grouped as their chat is."},"valid_leads":{"type":"integer","description":"Leads with at least one email or phone that is not a placeholder or the business's own number."},"handoffs":{"type":["integer","null"],"description":"Handoffs requested in the window, grouped as their chat is."},"booked":{"type":["integer","null"]},"converted":{"type":"object","description":"The conversion cohort: page views loaded in the window from which a chat started, and those whose chat saved a lead or a valid lead in the window. Divide by page_views.loaded for conversion; unlike the activity counts above, it leaves out chats with no page view or from before page tracking.","properties":{"conversations":{"type":"integer"},"leads":{"type":"integer"},"valid_leads":{"type":"integer"}},"required":["conversations","leads","valid_leads"]}},"required":["page_views","visits","visitors","returning_visits","identified_page_views","sends","conversations","leads","handoffs","booked"]},{"type":"object","properties":{"key":{"type":["string","null"]},"previous":{"type":"object","properties":{"page_views":{"type":"object","description":"Distinct page views per stage. Events without a page_view_id are excluded.","properties":{"loaded":{"type":"integer"},"shown":{"type":"integer"},"card":{"type":"integer","description":"A card (nudge, continue, link follow-up or teaser) showed: `card_shown`."},"opened":{"type":"integer"},"typed":{"type":"integer"},"sent":{"type":"integer"}},"required":["loaded","shown","card","opened","typed","sent"]},"visits":{"type":"object","description":"Distinct visits (a run of page views by one browser) per stage, with the same filters as page_views. Only events that carry a visit_id count: visits exist only with analytics consent and a current widget.","properties":{"loaded":{"type":"integer"},"shown":{"type":"integer"},"card":{"type":"integer","description":"A card (nudge, continue, link follow-up or teaser) showed: `card_shown`."},"opened":{"type":"integer"},"typed":{"type":"integer"},"sent":{"type":"integer"}},"required":["loaded","shown","card","opened","typed","sent"]},"opens":{"type":"object","description":"Distinct page views opened for each reason, counted separately: a page view the widget opened by itself (`proactive`) and the visitor later reopened (`visitor`) counts in both. `page_views.opened` mixes them.","properties":{"visitor":{"type":"integer"},"proactive":{"type":"integer"},"api":{"type":"integer"}},"required":["visitor","proactive","api"]},"cards":{"type":"object","description":"Distinct page views where each card showed (`card_shown`), counted separately.","properties":{"nudge":{"type":"integer"},"continue":{"type":"integer"},"follow_up":{"type":"integer"},"teaser":{"type":"integer"}},"required":["nudge","continue","follow_up","teaser"]},"opens_from":{"type":"object","description":"Distinct page views opened, by what opened them (`widget_opened` `from`): the launcher, the nudge (or the classic teaser), the continue card (or its start-fresh button), the link follow-up card, the host's API, or by itself (`auto`). Visitor opens from widgets that predate `from` count in none of these.","properties":{"launcher":{"type":"integer"},"nudge":{"type":"integer"},"continue":{"type":"integer"},"follow_up":{"type":"integer"},"api":{"type":"integer"},"auto":{"type":"integer"}},"required":["launcher","nudge","continue","follow_up","api","auto"]},"first_sends":{"type":"object","description":"Of `conversations`: by how the first message was sent (`message_send` `source`): typed, a reply chip, a starter, a nudge answer, a continue-card draft, or the contact card. Chats from widgets that predate `source` count in none.","properties":{"typed":{"type":"integer"},"reply":{"type":"integer"},"starter":{"type":"integer"},"nudge":{"type":"integer"},"continue":{"type":"integer"},"contact":{"type":"integer"}},"required":["typed","reply","starter","nudge","continue","contact"]},"crawlers":{"type":["object","null"],"description":"Page views from declared crawlers (device `bot`), which every other count leaves out, and how many the widget opened by itself. Only for group_by none, site, page, hour, hour_of_day and assistant; null otherwise.","properties":{"loaded":{"type":"integer"},"opened":{"type":"integer"}},"required":["loaded","opened"]},"visitors":{"type":"integer","description":"Distinct visitor ids among widget_loaded events."},"returning_visits":{"type":"integer","description":"Distinct visits among widget_loaded events whose visit_number is above 1."},"identified_page_views":{"type":"integer","description":"Distinct page views among widget_loaded events that carry a visit_id. Divide by tracked_page_views for coverage."},"tracked_page_views":{"type":"integer","description":"Distinct page views since visit tracking started for this scope (the response's visits_since); 0 before it started. The coverage denominator, so earlier, untracked weeks do not count as untracked traffic."},"sends":{"type":["object","null"],"properties":{"pressed":{"type":"integer"},"accepted":{"type":"integer"},"answered":{"type":"integer"},"failed":{"type":"integer"},"refused":{"type":"integer"}}},"conversations":{"type":["integer","null"],"description":"Chats with a visitor message started in the window, in every grouping: a chat takes the page, source and device of the page view its first message was sent from, or the group `untracked` when there is none. Sandbox chats and live chats our rules caught (test markers, preview hosts, internal lead emails) are left out (see excluded and excluded_traffic)."},"deep_conversations":{"type":"integer","description":"Of conversations: chats with three or more visitor messages."},"single_message_conversations":{"type":"integer","description":"Of conversations: chats where the visitor sent one message and stopped."},"leads":{"type":["integer","null"],"description":"Leads saved in the window, grouped as their chat is."},"valid_leads":{"type":"integer","description":"Leads with at least one email or phone that is not a placeholder or the business's own number."},"handoffs":{"type":["integer","null"],"description":"Handoffs requested in the window, grouped as their chat is."},"booked":{"type":["integer","null"]},"converted":{"type":"object","description":"The conversion cohort: page views loaded in the window from which a chat started, and those whose chat saved a lead or a valid lead in the window. Divide by page_views.loaded for conversion; unlike the activity counts above, it leaves out chats with no page view or from before page tracking.","properties":{"conversations":{"type":"integer"},"leads":{"type":"integer"},"valid_leads":{"type":"integer"}},"required":["conversations","leads","valid_leads"]}},"required":["page_views","visits","visitors","returning_visits","identified_page_views","sends","conversations","leads","handoffs","booked"],"description":"The same counts for the comparison the request asked for. Under compare=average_7 they are means, to one decimal, so not whole numbers."}},"required":["key"]}]}},"groups_total":{"type":"integer","description":"Groups found; only the first 50 are returned (hours are never cut)."},"truncated":{"type":"boolean"},"coverage":{"type":"object","description":"Counted chats in the window, and those tied to a page view the widget reported.","properties":{"conversations":{"type":"integer"},"tracked":{"type":"integer"}},"required":["conversations","tracked"]},"excluded":{"type":"object","description":"Chats in the window left out of every number, each under the first reason that applies: a test marker or sandbox key, a preview or staging host, or an internal lead email.","properties":{"test":{"type":"integer"},"preview":{"type":"integer"},"internal":{"type":"integer"}},"required":["test","preview","internal"]},"excluded_traffic":{"type":"object","description":"The same left-out chats by traffic, each counted once: `sandbox` chats come from a non-live key (a sandbox key, the console's sandbox chat or a preview link); `test` chats are live chats our rules caught (a test marker, a staging or preview host, or a placeholder or own-domain lead email).","properties":{"sandbox":{"type":"integer"},"test":{"type":"integer"}},"required":["sandbox","test"]},"partial":{"type":"boolean","description":"True when not every send in the window could be read, so the counts are a lower bound. Retry, or narrow the range."}},"required":["from","to","group_by","groups","groups_total","truncated","coverage","excluded","excluded_traffic","partial"]},"ChatHealth":{"type":"object","properties":{"checker":{"type":"object","properties":{"swept_at":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"}},"required":["swept_at","stale"]},"partial":{"type":"boolean","description":"True when not every send in the window could be read, so the counts are a lower bound. Retry, or narrow the range."},"sites":{"type":"array","items":{"type":"object","properties":{"site":{"type":["string","null"]},"status":{"type":"string","enum":["ok","warning","critical","idle"]},"page_views":{"type":"integer"},"shown":{"type":"integer"},"opened":{"type":"integer"},"sends":{"type":"integer"},"accepted":{"type":"integer"},"failed":{"type":"integer"},"refused":{"type":"integer"},"failure_rate":{"type":["number","null"]},"reply_ms_p50":{"type":["integer","null"]},"reply_ms_p90":{"type":["integer","null"]},"last_success_at":{"type":["string","null"],"format":"date-time"},"open_incidents":{"type":"integer"}},"required":["site","status","page_views","sends","open_incidents"]}}},"required":["checker","sites","partial"]},"ChatImprovement":{"type":"object","description":"What visitors said about the chat, and where it could do better. Quoted text is one line, at most 200 characters, with emails and phone numbers masked, and names masked where they follow common patterns (an introduction such as \"my name is\" or a greeting such as \"Thanks Jane\"). Other personal details can remain.","properties":{"replies":{"type":"object","description":"Thumbs up and down on assistant replies.","properties":{"rated":{"type":"integer"},"up":{"type":"integer"},"down":{"type":"integer"},"reasons":{"type":"object","additionalProperties":{"type":"integer"},"description":"Thumbs-down count per reason."}},"required":["rated","up","down","reasons"]},"chats_rated":{"type":"object","properties":{"count":{"type":"integer"},"average":{"type":["number","null"]},"distribution":{"type":"array","items":{"type":"integer"},"description":"Count of 1 to 5 star ratings, in order."}},"required":["count","average","distribution"]},"containment":{"type":"object","properties":{"chats":{"type":"integer"},"without_person":{"type":"integer","description":"Never asked for a person."},"with_lead":{"type":"integer"},"asked_for_person":{"type":"integer"},"one_message":{"type":"integer","description":"Conversations, open or ended, with exactly one visitor message and no lead."}},"required":["chats","without_person","with_lead","asked_for_person","one_message"]},"knowledge_gaps":{"type":"object","description":"Replies whose knowledge searches all came back empty.","properties":{"total":{"type":"integer"},"recent":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"conversation_id":{"type":"string"},"at":{"type":"string","format":"date-time"}},"required":["question","conversation_id","at"]}},"top":{"type":"array","description":"The same gaps grouped by question, most asked first (at most 10), with the latest wording and its chat.","items":{"type":"object","properties":{"question":{"type":"string"},"count":{"type":"integer"},"conversation_id":{"type":"string"},"at":{"type":"string","format":"date-time"}},"required":["question","count","conversation_id","at"]}}},"required":["total","recent","top"]},"unhelpful":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string"},"reason":{"type":["string","null"]},"conversation_id":{"type":"string"},"at":{"type":"string","format":"date-time"}},"required":["answer","reason","conversation_id","at"]},"description":"Recent replies rated down."},"comments":{"type":"array","items":{"type":"object","properties":{"rating":{"type":"integer"},"comment":{"type":"string"},"conversation_id":{"type":"string"},"at":{"type":"string","format":"date-time"}},"required":["rating","comment","conversation_id","at"]},"description":"Recent conversation ratings that came with a comment."},"top_fixes":{"type":"array","description":"Changes the conversation analysis suggested, by kind, most common first, with up to 3 of the latest as examples.","items":{"type":"object","properties":{"kind":{"type":"string","enum":["knowledge","prompt","flow","settings","handoff"]},"count":{"type":"integer","description":"Chats with at least one fix of this kind."},"examples":{"type":"array","items":{"type":"object","properties":{"suggestion":{"type":"string"},"conversation_id":{"type":"string"},"seq":{"type":["integer","null"],"description":"The message that shows it."}},"required":["suggestion","conversation_id","seq"]}}},"required":["kind","count","examples"]}},"stop_points":{"type":"array","description":"Assistant messages visitors stopped replying after while something was left open (worked out in code, not by the model), grouped by structured-flow step (`step:<lead field>`) when the message offered a lead field's options, else by its normalised text (`text:<key>`), or `read_back` for a message that read the visitor's details back. Up to 10, most stops first.","items":{"type":"object","properties":{"key":{"type":"string"},"step":{"type":["string","null"]},"text":{"type":"string","description":"An example message, masked; empty when none may be shown, such as a read-back."},"label":{"type":["string","null"],"description":"What a step asked for (\"Asked for <field label>\"), or a read-back's description; null for a text group."},"reached":{"type":"integer","description":"Analysed chats with this message."},"stopped":{"type":"integer","description":"Of those, chats where the visitor never replied to it."},"conversation_id":{"type":"string","description":"The latest chat that stopped here."}},"required":["key","step","text","label","reached","stopped","conversation_id"]}},"assistant_flags":{"type":"object","description":"Problems the conversation analysis found in the assistant's own messages.","properties":{"total":{"type":"integer"},"kinds":{"type":"object","additionalProperties":{"type":"integer"},"description":"Count per kind: wrong, invented, off_policy, unhelpful, tone."},"recent":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["wrong","invented","off_policy","unhelpful","tone"]},"note":{"type":"string"},"seq":{"type":"integer"},"conversation_id":{"type":"string"},"at":{"type":"string","format":"date-time","description":"When the chat started."}},"required":["kind","note","seq","conversation_id","at"]}}},"required":["total","kinds","recent"]}},"required":["replies","chats_rated","containment","knowledge_gaps","unhelpful","comments","top_fixes","stop_points","assistant_flags"]},"ChatIncident":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"assistant_id":{"type":["string","null"]},"widget_key_id":{"type":["string","null"]},"site":{"type":["string","null"]},"rule":{"type":"string"},"severity":{"type":"string","enum":["info","warning","critical"]},"status":{"type":"string","enum":["open","resolved"]},"dedupe_key":{"type":"string"},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"occurrences":{"type":"integer"},"example_request_id":{"type":["string","null"]},"example_conversation_id":{"type":["string","null"]},"detail":{"type":["object","null"],"additionalProperties":true},"muted_until":{"type":["string","null"],"format":"date-time"},"muted_by":{"type":["string","null"]},"resolved_at":{"type":["string","null"],"format":"date-time"},"resolution":{"type":["string","null"],"enum":["recovered","quiet","manual",null]},"resolved_by":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","project_id","rule","severity","status"]},"ChatIncidentMute":{"type":"object","properties":{"minutes":{"type":"integer","minimum":15,"maximum":10080}},"required":["minutes"]},"ChatLeadSource":{"type":"object","properties":{"key":{"type":"string"},"leads":{"type":"integer"},"valid_leads":{"type":"integer"}},"required":["key","leads","valid_leads"]},"ChatLeadSources":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"leads":{"type":"integer"},"first_touch":{"type":"array","items":{"$ref":"#/components/schemas/ChatLeadSource"}},"latest_paid":{"type":"array","items":{"$ref":"#/components/schemas/ChatLeadSource"}}},"required":["leads","first_touch","latest_paid"]},"ChatNotificationChannel":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["webhook"]},"url":{"type":"string","format":"uri","pattern":"^https://"}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["email"]},"to":{"type":"string","format":"email","description":"The address the alerts or digest are emailed to."}},"required":["type","to"]}]},"ChatOutcomesBackfill":{"type":"object","properties":{"queued":{"type":"integer"},"candidates":{"type":"integer"},"remaining":{"type":"boolean","description":"More chats in the window still need a label: call again."}},"required":["queued","candidates","remaining"]},"ChatQuality":{"type":"object","properties":{"reply_ms":{"type":"object","properties":{"buckets":{"type":"array","items":{"type":"object","properties":{"le_ms":{"type":["integer","null"]},"count":{"type":"integer"}},"required":["le_ms","count"]}},"p50":{"type":["integer","null"]},"p90":{"type":["integer","null"]},"p95":{"type":["integer","null"]},"p99":{"type":["integer","null"]},"samples":{"type":"integer","description":"Replies measured."},"slow":{"type":"integer","description":"Replies slower than 15 seconds."}}},"first_token_ms":{"type":"object","properties":{"p50":{"type":["integer","null"]},"p90":{"type":["integer","null"]}}},"replies":{"type":"object","properties":{"answered":{"type":"integer"},"missing":{"type":"integer"},"rescued":{"type":"integer"}}},"sends":{"type":"object","properties":{"total":{"type":"integer"},"failed":{"type":"integer"},"quick_reply_share":{"type":["number","null"]}}},"handoff":{"type":"object","properties":{"requested":{"type":"integer"},"answered":{"type":"integer","description":"Taken over by an advisor."},"replied":{"type":"integer","description":"An advisor wrote after the request."},"median_answer_seconds":{"type":["integer","null"]}}},"leads":{"type":"object","properties":{"total":{"type":"integer"},"with_email":{"type":"integer"},"with_phone":{"type":"integer"},"with_name":{"type":"integer"},"valid":{"type":"integer","description":"With one email or phone that is not a placeholder or the business's own number."},"flags":{"type":"object","properties":{"placeholder_email":{"type":"integer"},"placeholder_phone":{"type":"integer"},"business_phone":{"type":"integer"}}},"required_complete":{"type":["integer","null"],"description":"Leads holding every required field; null when no assistant marks any."},"booked":{"type":"integer"},"lost":{"type":"integer"},"revenue":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}},"required":["currency","amount"]}}}},"cost":{"type":"object","properties":{"total":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}},"required":["currency","amount"]}},"per_lead":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}},"required":["currency","amount"]}},"per_valid_lead":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}},"required":["currency","amount"]},"description":"Chat cost over leads with a usable email or phone."}}},"ended_reasons":{"type":"object","additionalProperties":{"type":"integer"},"description":"Ended chats by how they ended (`visitor_ended`, `idle_timeout`, `max_messages`, `error`, `unknown`)."},"chips":{"type":"array","description":"Suggested replies visitors tapped in chats started in the window, most sent first (at most 10), masked.","items":{"type":"object","properties":{"text":{"type":"string"},"sends":{"type":"integer"},"conversations":{"type":"integer"},"leads":{"type":"integer","description":"Of `conversations`: chats that saved a lead."}},"required":["text","sends","conversations","leads"]}},"stop_points":{"type":"array","description":"Where ended chats stopped while the assistant waited on the visitor, by what it had asked (from the analysis labels).","items":{"type":"object","properties":{"key":{"type":"string"},"text":{"type":"string"},"conversations":{"type":"integer"}},"required":["key","text","conversations"]}},"outcomes":{"type":"object","description":"How ended chats ended, from the analysis labels. Counts by label; `labelled` of `ended` were labelled.","properties":{"ended":{"type":"integer"},"labelled":{"type":"integer"},"intents":{"type":"object","additionalProperties":{"type":"integer"}},"goal":{"type":"object","additionalProperties":{"type":"integer"}},"waiting_on":{"type":"object","additionalProperties":{"type":"integer"}},"contact_declined":{"type":"integer"},"friction":{"type":"object","additionalProperties":{"type":"integer"}}}},"tools":{"type":"array","description":"Tool calls in the window's chats. `expected` failures are the tool asking for what is missing; the rest are the platform failing.","items":{"type":"object","properties":{"name":{"type":"string"},"calls":{"type":"integer"},"failed":{"type":"integer"},"expected":{"type":"integer"},"errors":{"type":"object","additionalProperties":{"type":"integer"}}}}},"knowledge":{"type":"object","description":"Knowledge searches by result: unavailable is the search failing, empty is missing content.","properties":{"searches":{"type":"integer"},"ok":{"type":"integer"},"empty":{"type":"integer"},"unavailable":{"type":"integer"},"other":{"type":"integer"}}},"improvement":{"$ref":"#/components/schemas/ChatImprovement"},"partial":{"type":"boolean","description":"True when not every send in the window could be read, so the counts are a lower bound. Retry, or narrow the range."}},"required":["improvement","partial"]},"ChatSseEvent":{"description":"One server-sent event frame on the send-message stream: `event` is the SSE event name, `data` the parsed JSON of its data line.","oneOf":[{"type":"object","title":"message.accepted","properties":{"event":{"const":"message.accepted"},"data":{"type":"object"}},"required":["event","data"]},{"type":"object","title":"message.delta","properties":{"event":{"const":"message.delta"},"data":{"type":"object","properties":{"text":{"type":"string","description":"The next piece of the reply."}},"required":["text"]}},"required":["event","data"]},{"type":"object","title":"tool.status","properties":{"event":{"const":"tool.status"},"data":{"type":"object","properties":{"name":{"type":"string"},"state":{"type":"string","enum":["started","completed"]}},"required":["name","state"]}},"required":["event","data"]},{"type":"object","title":"message.completed","properties":{"event":{"const":"message.completed"},"data":{"type":"object","properties":{"message":{"anyOf":[{"$ref":"#/components/schemas/PublicMessage"},{"type":"null"}],"description":"The stored reply. Null while a person has taken over: their reply arrives through the updates route."},"conversation":{"type":"object","properties":{"status":{"type":"string","enum":["open","ended"]},"resumable":{"type":"boolean"},"handoff_requested_at":{"type":["string","null"],"format":"date-time"},"taken_over":{"type":"boolean"},"lead_id":{"type":["string","null"],"description":"Set once the assistant has captured a lead."},"callback_requested_at":{"type":["string","null"],"format":"date-time","description":"When the visitor's callback request was stored; null without one."},"lead":{"anyOf":[{"$ref":"#/components/schemas/PublicChatLead"},{"type":"null"}],"description":"As on the updates route: present only when the lead panel is on."},"phone_captured":{"type":"boolean","description":"As on the updates route: present only when consent capture is on."}}}},"required":["message","conversation"]}},"required":["event","data"]},{"type":"object","title":"error","properties":{"event":{"const":"error"},"data":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"]}},"required":["event","data"]},{"type":"object","title":"heartbeat","properties":{"event":{"const":"heartbeat"},"data":{"type":"object"}},"required":["event","data"]}]},"ChatSseEvents":{"type":"string","description":"text/event-stream frames, each `event: <name>`, `data: <JSON>` and a blank line; there is no `[DONE]` sentinel. Usually: `message.accepted` (data `{}`) once the visitor message is stored, then any number of `message.delta` (`{text}`, append in order) and `tool.status` (`{name,state}`, state `started` or `completed`). Always exactly one terminal frame, which may be the only frame (a replayed `client_message_id`, or a send while a person has taken over): `message.completed` (`{message,conversation}`, message is null while a person has taken over) or `error` (`{code}`: `llm_error`, `llm_not_configured`, `turn_timeout`, `turn_interrupted`, `message_already_accepted`, `attachment_already_sent`). `heartbeat` (`{}`) arrives every 15 seconds while the stream is open; ignore it. See ChatSseEvent for each frame's data."},"ChatSubscription":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"kind":{"type":"string","enum":["health","digest"]},"channel":{"$ref":"#/components/schemas/ChatNotificationChannel"},"enabled":{"type":"boolean"},"timezone":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","project_id","kind","channel","enabled","timezone"]},"ChatSubscriptionCreate":{"type":"object","properties":{"project_id":{"type":"string"},"kind":{"type":"string","enum":["health","digest"]},"channel":{"$ref":"#/components/schemas/ChatNotificationChannel"},"timezone":{"type":"string","description":"IANA zone; default UTC."}},"required":["kind","channel"]},"ChatSubscriptionPatch":{"type":"object","minProperties":1,"properties":{"enabled":{"type":"boolean"},"channel":{"$ref":"#/components/schemas/ChatNotificationChannel"},"timezone":{"type":"string"}}},"ChatTrend":{"type":"object","properties":{"interval":{"type":"string","enum":["day","week"]},"points":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"YYYY-MM-DD; a Monday for weekly points."},"page_views":{"type":"integer"},"shown":{"type":"integer"},"opened":{"type":"integer"},"sends":{"type":"integer"},"accepted":{"type":"integer"},"failed":{"type":"integer"},"conversations":{"type":"integer"},"leads":{"type":"integer"},"handoffs":{"type":"integer"}},"required":["period"]}}},"required":["interval","points"]},"ContactHours":{"type":"object","description":"Weekly windows in the project's timezone (in the person's own zone when the project has none). Holidays block marketing contact for the whole day.","properties":{"weekly":{"type":"array","maxItems":28,"items":{"type":"object","properties":{"day":{"type":"integer","minimum":0,"maximum":6,"description":"0 is Sunday."},"open":{"type":"string","pattern":"^([01]\\d|2[0-4]):[0-5]\\d$","description":"HH:MM"},"close":{"type":"string","pattern":"^([01]\\d|2[0-4]):[0-5]\\d$","description":"HH:MM, after open; 24:00 is midnight."}},"required":["day","open","close"]}},"holidays":{"type":"array","maxItems":366,"items":{"type":"string","format":"date"}}},"required":["weekly"]},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string","description":"Alias used by the public resume surface."},"org_id":{"type":"string"},"project_id":{"type":"string"},"assistant_id":{"type":"string"},"widget_key_id":{"type":["string","null"]},"channel":{"type":"string","enum":["web_chat","whatsapp"]},"mode":{"type":"string","enum":["live","test","preview"],"description":"Set by the server from the key the chat came in on: sandbox chats run the draft, preview chats send nothing out."},"traffic":{"type":"string","enum":["real","sandbox","test"],"description":"Operator list and detail only. Which traffic this belongs to: `sandbox` (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), `test` (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or `real`. Sandbox wins over test. Sandbox and test are both left out of real numbers."},"status":{"type":"string","enum":["open","ended"]},"ended_reason":{"type":["string","null"],"enum":["visitor_ended","idle_timeout","max_messages","error",null]},"resumable":{"type":"boolean","description":"Public resume surface: ended only because the visitor went quiet, so the next message reopens it."},"handoff_requested_at":{"type":["string","null"],"format":"date-time"},"taken_over_at":{"type":["string","null"],"format":"date-time"},"taken_over_heartbeat_at":{"type":["string","null"],"format":"date-time"},"taken_over_by":{"type":["string","null"]},"taken_over_by_name":{"type":["string","null"]},"taken_over":{"type":"boolean"},"first_taken_over_at":{"type":["string","null"],"format":"date-time","description":"First time a human took over; unlike taken_over_at, never cleared."},"handoff_answered_at":{"type":["string","null"],"format":"date-time","description":"First takeover at or after handoff_requested_at."},"handoff_in_hours":{"type":["boolean","null"],"description":"Whether the bot told the visitor advisors were available when they first asked for a person, by the assistant's working hours (none configured counts as available). Null when unknown, as on requests from before 7 October 2026 without a stored answer."},"handoff_status":{"type":"string","enum":["none","pending","answered","missed","abandoned"],"description":"missed: the chat ended before anyone took over. abandoned: a human took over and then left the visitor waiting; it takes precedence over the others."},"handoff_answer_seconds":{"type":["integer","null"]},"human_outcome":{"type":["string","null"],"enum":["handled","abandoned",null],"description":"Null when no human took part. handled: every visitor message to the human got a human reply. abandoned: at least one did not, before the bot replied, the chat ended, or (chat still open) 5 minutes passed. Recomputed when a seat is released, when the chat ends, and on each analysis run."},"human_metrics":{"anyOf":[{"$ref":"#/components/schemas/HumanMetrics"},{"type":"null"}]},"needs_review":{"type":"boolean","description":"Operator list only: the analysis flagged the human advisor's replies with severity 2 or more."},"missed_lead":{"type":"boolean","description":"Operator list and detail only. A live web chat that ended without a lead: the visitor gave no email or phone, but gave a name or company and at least one other detail. Chats the analysis labelled job_or_vendor, spam_or_test or existing_customer are left out."},"visitor_id":{"type":["string","null"]},"parent_origin":{"type":["string","null"]},"last_message_at":{"type":["string","null"],"format":"date-time"},"message_count":{"type":"integer"},"lead_id":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":true},"callback":{"anyOf":[{"type":"object","properties":{"phone":{"type":"string"},"slot_start":{"type":"string","format":"date-time"},"note":{"type":"string"},"requested_at":{"type":"string","format":"date-time"},"done_at":{"type":"string","format":"date-time","description":"When staff marked the callback made; absent while it is open. A new request from the visitor replaces the callback, open again."},"done_by":{"type":"string","description":"Who marked it: a user id, or the `agent.id` an API key named."},"done_by_name":{"type":"string"}},"required":["phone","requested_at"]},{"type":"null"}]},"ended_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"}},"costs":{"type":"array","items":{"type":"object","additionalProperties":true}},"lead":{"anyOf":[{"$ref":"#/components/schemas/Lead"},{"type":"null"}]},"handoff_summary":{"anyOf":[{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"wants":{"type":"string","maxLength":1200},"done_by_assistant":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":600}},"needs_you":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":600}}},"required":["wants","done_by_assistant","needs_you"],"additionalProperties":false},{"type":"null"}],"description":"Operator list only. The structured handoff from the latest analysis."},"summary":{"type":["string","null"],"description":"Operator list only: the latest background summary, when analysis is on."},"intent":{"type":["string","null"],"enum":["new_enquiry","information","existing_customer","human_request","job_or_vendor","spam_or_test","other","unknown",null],"description":"Operator list only: the latest analysis intent, or null when none is recorded."},"last_visitor_message":{"type":["string","null"],"maxLength":200,"description":"Operator list only: the newest user message by sequence, trimmed and limited to 200 characters. Null when none exists."},"analysis":{"anyOf":[{"$ref":"#/components/schemas/ConversationAnalysis"},{"type":"null"}],"description":"Operator detail only: the latest background summary and extracted facts."},"live_handoff":{"type":"boolean","description":"Operator detail only: whether the org takes web chats over live. When false, takeover is refused with 409 live_handoff_disabled."}},"required":["status"]},"ConversationAnalysis":{"type":"object","description":"Written after the conversation has been quiet for 60 seconds, and again when it ends, unless `channels.web_chat.analysis.enabled` is false (on by default).","properties":{"handoff_summary":{"anyOf":[{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"wants":{"type":"string","maxLength":1200},"done_by_assistant":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":600}},"needs_you":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":600}}},"required":["wants","done_by_assistant","needs_you"],"additionalProperties":false},{"type":"null"}],"description":"Wants, completed assistant actions, and unresolved human tasks. Null for older or unvalidated analyses. Shares through_seq with the analysis."},"summary":{"type":["string","null"]},"structured":{"type":"object","additionalProperties":true,"description":"The configured `channels.web_chat.analysis.fields` the chat stated, keyed by field key."},"through_seq":{"type":"integer","description":"The last message seq the run read."},"human_review":{"anyOf":[{"$ref":"#/components/schemas/HumanReview"},{"type":"null"}],"description":"Null when no human took part."},"needs_review":{"type":"boolean","description":"human_review has a flag of severity 2 or more."},"updated_at":{"type":"string","format":"date-time"}},"required":["summary","structured","through_seq","updated_at"]},"ConversationAttachment":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document"]},"size":{"type":"integer","description":"Bytes."},"url":{"type":"string","format":"uri","description":"Signed download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks)."}},"required":["id","name","content_type","size","url"]},"ConversationCallbackRequest":{"type":"object","properties":{"done":{"type":"boolean","description":"True marks the callback made; false reopens it."},"agent":{"$ref":"#/components/schemas/AgentIdentityInput"}},"required":["done"]},"ConversationCallbackState":{"type":"object","properties":{"id":{"type":"string"},"callback":{"type":"object","properties":{"phone":{"type":"string"},"slot_start":{"type":"string","format":"date-time"},"note":{"type":"string"},"requested_at":{"type":"string","format":"date-time"},"done_at":{"type":"string","format":"date-time"},"done_by":{"type":"string"},"done_by_name":{"type":"string"}},"required":["phone","requested_at"]}},"required":["id","callback"]},"ConversationHandoffCounts":{"type":"object","properties":{"assistant_id":{"type":"string"},"conversations":{"type":"integer"},"requested":{"type":"integer"},"pending":{"type":"integer"},"answered":{"type":"integer"},"missed":{"type":"integer"},"requested_in_hours":{"type":"integer"},"requested_out_of_hours":{"type":"integer"},"missed_in_hours":{"type":"integer"},"missed_out_of_hours":{"type":"integer"},"callbacks":{"type":"integer"}},"required":["assistant_id","conversations","requested","pending","answered","missed","requested_in_hours","requested_out_of_hours","missed_in_hours","missed_out_of_hours","callbacks"]},"ConversationHandoffSummary":{"type":"object","properties":{"conversations":{"type":"integer"},"requested":{"type":"integer"},"pending":{"type":"integer"},"answered":{"type":"integer"},"missed":{"type":"integer"},"requested_in_hours":{"type":"integer","description":"Requests made while advisors were said to be available."},"requested_out_of_hours":{"type":"integer","description":"Requests made outside working hours, when the bot offers a callback instead."},"missed_in_hours":{"type":"integer"},"missed_out_of_hours":{"type":"integer"},"taken_over":{"type":"integer","description":"Conversations a human took over, requested or not."},"abandoned":{"type":"integer","description":"Conversations a human took over and then left the visitor waiting."},"handled":{"type":"integer","description":"Conversations a human took part in where every visitor message to them got a human reply."},"unanswered_messages":{"type":"integer","description":"Visitor messages to a human that no human answered, summed."},"callbacks":{"type":"integer","description":"Conversations where the visitor left a callback request."},"live_handoff":{"type":"boolean","description":"Whether the org takes web chats over live. When false, requests for a person are callback requests only."},"answer_seconds":{"$ref":"#/components/schemas/SecondsPercentiles"},"first_response_seconds":{"$ref":"#/components/schemas/SecondsPercentiles","description":"From the first takeover to the first human message."},"longest_wait_seconds":{"$ref":"#/components/schemas/SecondsPercentiles","description":"Each conversation's longest wait for the human, answered or not."}},"required":["conversations","requested","pending","answered","missed","requested_in_hours","requested_out_of_hours","missed_in_hours","missed_out_of_hours","taken_over","abandoned","handled","unanswered_messages","callbacks","live_handoff","answer_seconds","first_response_seconds","longest_wait_seconds"]},"ConversationHandoffsByAssistant":{"type":"object","description":"`group_by=assistant`: one row per assistant with conversations in the range.","properties":{"by_assistant":{"type":"array","items":{"$ref":"#/components/schemas/ConversationHandoffCounts"}}},"required":["by_assistant"]},"ConversationMessage":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"role":{"type":"string","enum":["user","assistant","agent","tool","system"]},"content":{"type":"string"},"rich":{"$ref":"#/components/schemas/RichContent"},"tool_calls":{"type":["array","null"],"items":{"type":"object","additionalProperties":true}},"tool_call_id":{"type":["string","null"]},"seq":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","role","content","created_at"]},"ConversationTakeover":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["open","ended"]},"taken_over_at":{"type":["string","null"],"format":"date-time"},"taken_over_heartbeat_at":{"type":["string","null"],"format":"date-time"},"taken_over_by":{"type":["string","null"]}},"required":["id","status","taken_over_at","taken_over_heartbeat_at","taken_over_by"]},"ConversationTakeoverHeartbeat":{"type":"object","properties":{"taken_over_heartbeat_at":{"type":"string","format":"date-time"}},"required":["taken_over_heartbeat_at"]},"ConversationTakeoverRequest":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/AgentIdentityInput"}}},"DeleteResult":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}},"required":["id","deleted"]},"Error":{"type":"object","description":"Every error body carries a string code in `error` (`{\"error\":\"not_found\"}`), often a `message`, and sometimes fields that belong to the code beside them. Branch on the code and the HTTP status, never on `message`.","properties":{"error":{"type":"string","description":"Machine-readable code, for example `invalid_request`, `unauthorized`, `not_found`, `read_only_key`, `insufficient_role`, `rate_limited`, `internal_error`, or a route-specific one such as `number_attached`."},"required":{"type":"string","description":"`insufficient_role` only: the role the route needs."},"actual":{"type":"string","description":"`insufficient_role` only: the caller's role."},"message":{"type":"string","description":"Human-readable detail. The wording can change; do not parse it."},"issues":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Optional. On `invalid_request`: the validation issues, each with the failing `path` and a `message`."},"request_id":{"type":"string","description":"`internal_error` only: the request id (also sent as the `x-request-id` header) to quote when reporting the failure."}},"required":["error"],"additionalProperties":true},"Form":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string","maxLength":200},"status":{"type":"string","enum":["active","paused"],"description":"A paused form refuses posts."},"kind":{"type":"string","enum":["enquiry","callback","support","newsletter","careers","other"],"description":"What the form is for. Default `enquiry`. `newsletter` and `careers` submissions never make leads."},"unknown_fields":{"type":"string","enum":["keep","reject"],"description":"`keep` (default) keeps submitted fields the definition does not name; `reject` refuses the post (`unknown`). Controls are never fields, and an empty definition never refuses."},"approved_sites":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Hosts a live key accepts posts from (the request's Origin, else its Referer), such as `www.example.com`; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403 `site_not_approved`) until a site is added. Test keys skip the check."},"redirect_url":{"type":["string","null"],"format":"uri","description":"Where a browser goes after a post, unless the post names an approved `_redirect`. Null: the hosted thank-you page."},"thank_you":{"type":["object","null"],"properties":{"title":{"type":"string","maxLength":200},"body":{"type":"string","maxLength":2000}},"description":"The hosted thank-you page's text."},"honeypot_field":{"type":"string","description":"A hidden field only bots fill (default `botcheck`): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (`_redirect`, `_page`, `_referrer`, `access_key`, `cf-turnstile-response`, any `utm_*`, a click id), a defined field's key or a name the field map reads."},"hold_unsure":{"type":"boolean","description":"Hold submissions the spam check is unsure about for review."},"fields":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/FormField"},"description":"The fields the form defines, checked in order: a blank required field is `missing`, then the type (`invalid`), length, range and `pattern`. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see `unknown_fields`). Empty: any fields are accepted."},"field_map":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}},"description":"Which submitted fields hold the person's name, email and phone. Defaults: `name`, `email`, `phone`."},"retention_days":{"type":"integer","minimum":1,"maximum":3650,"description":"Days a submission is kept. Default 365."},"turnstile":{"type":"string","enum":["off","on"]},"turnstile_site_key":{"type":["string","null"]},"turnstile_available":{"type":"boolean","description":"Whether this deployment can turn Turnstile on (it has Cloudflare credentials)."},"channel":{"type":"string","enum":["website","google_lead_form"],"description":"`website`, or `google_lead_form` for a Google lead form connection. Set on create, never changed."},"keys":{"type":"array","items":{"$ref":"#/components/schemas/FormKey"}},"archived_at":{"type":["string","null"],"format":"date-time","description":"When the form was archived; null when it is live."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"health":{"type":"string","enum":["ok","warning","critical"],"description":"The worst open health incident (`GET /v1/forms/health`), or `ok`."},"google":{"type":["object","null"],"description":"A Google lead form's ownership and arrivals, never its key; null for a website form.","properties":{"lead_export":{"type":"string","enum":["brightshoal","other_tool"]},"outcome_uploads":{"type":"string","enum":["none","brightshoal","client_crm"]},"last_test_at":{"type":["string","null"],"format":"date-time"},"last_lead_at":{"type":["string","null"],"format":"date-time"}}},"stats":{"type":"object","description":"`GET /v1/forms/{id}` only: live posts by outcome, from hourly counts.","properties":{"last_24h":{"type":"object","properties":{"accepted":{"type":"integer"},"held":{"type":"integer"},"refused":{"type":"integer","description":"Every refusal reason, the hourly limit included."},"failed":{"type":"integer"}},"required":["accepted","held","refused","failed"]},"last_7d":{"type":"object","properties":{"accepted":{"type":"integer"},"held":{"type":"integer"},"refused":{"type":"integer","description":"Every refusal reason, the hourly limit included."},"failed":{"type":"integer"}},"required":["accepted","held","refused","failed"]}}}},"required":["id","org_id","project_id","name","status","channel","fields","keys","health"]},"FormCreate":{"type":"object","properties":{"project_id":{"type":"string"},"channel":{"type":"string","enum":["website","google_lead_form"],"description":"Default `website`. `google_lead_form` also makes its Google key. On a Google lead form, `approved_sites`, `redirect_url`, `thank_you`, `turnstile`, `honeypot_field`, `hold_unsure`, `fields`, `unknown_fields` and `field_map` do not apply: setting one is 400 `not_for_google_forms`."},"name":{"type":"string","maxLength":200},"status":{"type":"string","enum":["active","paused"],"description":"A paused form refuses posts."},"kind":{"type":"string","enum":["enquiry","callback","support","newsletter","careers","other"],"description":"What the form is for. Default `enquiry`. `newsletter` and `careers` submissions never make leads."},"unknown_fields":{"type":"string","enum":["keep","reject"],"description":"`keep` (default) keeps submitted fields the definition does not name; `reject` refuses the post (`unknown`). Controls are never fields, and an empty definition never refuses."},"approved_sites":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Hosts a live key accepts posts from (the request's Origin, else its Referer), such as `www.example.com`; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403 `site_not_approved`) until a site is added. Test keys skip the check."},"redirect_url":{"type":["string","null"],"format":"uri","description":"Where a browser goes after a post, unless the post names an approved `_redirect`. Null: the hosted thank-you page."},"thank_you":{"type":["object","null"],"properties":{"title":{"type":"string","maxLength":200},"body":{"type":"string","maxLength":2000}},"description":"The hosted thank-you page's text."},"honeypot_field":{"type":"string","description":"A hidden field only bots fill (default `botcheck`): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (`_redirect`, `_page`, `_referrer`, `access_key`, `cf-turnstile-response`, any `utm_*`, a click id), a defined field's key or a name the field map reads."},"hold_unsure":{"type":"boolean","description":"Hold submissions the spam check is unsure about for review."},"fields":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/FormField"},"description":"The fields the form defines, checked in order: a blank required field is `missing`, then the type (`invalid`), length, range and `pattern`. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see `unknown_fields`). Empty: any fields are accepted."},"field_map":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}},"description":"Which submitted fields hold the person's name, email and phone. Defaults: `name`, `email`, `phone`."},"retention_days":{"type":"integer","minimum":1,"maximum":3650,"description":"Days a submission is kept. Default 365."}},"required":["name"],"additionalProperties":false},"FormField":{"type":"object","properties":{"key":{"type":"string","maxLength":64,"description":"The field's name in the post."},"label":{"type":"string","maxLength":200},"type":{"type":"string","enum":["text","email","phone","textarea","url","number","date","time","datetime","select","multiselect","checkbox","consent","file"]},"required":{"type":"boolean","default":false},"options":{"type":"array","items":{"type":"string"},"description":"The values a post may send: required for `select` and `multiselect`, optional for `checkbox` (a group)."},"help":{"type":"string","maxLength":500},"placeholder":{"type":"string","maxLength":200},"validation":{"type":"object","properties":{"min_length":{"type":"integer","minimum":0,"maximum":5000,"description":"text, textarea, email, phone, url."},"max_length":{"type":"integer","minimum":1,"maximum":5000,"description":"text, textarea, email, phone, url."},"min":{"type":["number","string"],"description":"number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices."},"max":{"type":["number","string"],"description":"As `min`."},"integer":{"type":"boolean","description":"number only."},"pattern":{"type":"string","maxLength":500,"description":"RE2 syntax, matched against the whole value (text, textarea, email, phone, url). `(?i)` for any case. A pattern that does not compile is refused."},"message":{"type":"string","maxLength":200,"description":"Replaces the default error message."}},"additionalProperties":false},"file":{"type":"object","description":"A `file` field's limits.","properties":{"accept":{"type":"array","maxItems":30,"items":{"type":"string"}},"max_size_mb":{"type":"integer","minimum":1,"maximum":10},"max_files":{"type":"integer","minimum":1,"maximum":5}},"additionalProperties":false},"consent":{"type":"object","description":"A `consent` field only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox named `key` whose value is the wording version. A ticked box on a post with a phone records a `form` grant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (`on`, `true`, `yes` or `1`) is stored as `yes`, and it may be required.","properties":{"channel":{"type":"string","enum":["whatsapp","sms","voice_human"]},"purpose":{"type":"string","enum":["service","marketing"]}},"required":["channel","purpose"]}},"required":["key","type"]},"FormGooglePatch":{"type":"object","properties":{"column_map":{"type":"object","maxProperties":100,"propertyNames":{"pattern":"^[A-Za-z0-9_]{1,64}$"},"additionalProperties":{"type":"string","maxLength":64},"description":"Replaces the overrides: Google question id to field key."},"lead_export":{"type":"string","enum":["brightshoal","other_tool"],"description":"Who exports these leads."},"outcome_uploads":{"type":"string","enum":["none","brightshoal","client_crm"],"description":"Who uploads later outcomes to Google. Brightshoal uploads nothing yet."}},"additionalProperties":false},"FormGoogleSetup":{"type":"object","properties":{"webhook_url":{"type":["string","null"],"description":"The live key's URL, for the Google Ads lead form; null with no live key or no public origin configured."},"test_webhook_url":{"type":["string","null"],"description":"The test key's URL: every lead it gets is a test lead."},"google_key":{"type":"string","description":"`gk_...`: the key Google Ads sends with each lead. A secret."},"previous_key_expires_at":{"type":["string","null"],"format":"date-time","description":"After a rotation: when the old key stops working."},"column_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Google question id to field key, overrides only."},"lead_export":{"type":"string","enum":["brightshoal","other_tool"]},"outcome_uploads":{"type":"string","enum":["none","brightshoal","client_crm"]},"google_form_ids":{"type":"array","items":{"type":"string"},"description":"Google lead form ids seen on live leads, at most 50."},"last_test_at":{"type":["string","null"],"format":"date-time"},"last_lead_at":{"type":["string","null"],"format":"date-time"}},"required":["webhook_url","test_webhook_url","google_key","column_map","lead_export","outcome_uploads"]},"FormHealthIncident":{"type":"object","properties":{"id":{"type":"string"},"form_id":{"type":"string"},"form_name":{"type":"string"},"rule":{"type":"string","enum":["form_quiet","form_refusing","form_failing","form_undelivered"]},"severity":{"type":"string","enum":["warning","critical"]},"status":{"type":"string","enum":["open","resolved"]},"reason":{"type":["string","null"],"description":"`form_refusing`: the refusal (`refused_site`, `refused_fields`, `refused_google_key`, ...); else null."},"detail":{"type":"object","description":"The rule's numbers. `form_quiet`: `last_24h`, `one_week_ago`, `two_weeks_ago`. `form_refusing`: `refused`, `posts`, `reason`. `form_failing`: `failed`. `form_undelivered`: `undelivered`, `gave_up`, `subscription_id`, `last_status`."},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"opened_at":{"type":"string","format":"date-time"},"resolved_at":{"type":["string","null"],"format":"date-time"},"resolution":{"type":["string","null"],"enum":["recovered","quiet","manual","form_archived",null]},"title":{"type":"string","description":"What the console and Slack show."}},"required":["id","form_id","rule","severity","status","detail","opened_at"]},"FormKey":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"`fkey_live_...` or `fkey_test_...`: what the site posts to. Public, like the form's URL."},"mode":{"type":"string","enum":["live","test"]},"expires_at":{"type":["string","null"],"format":"date-time","description":"Set on a rotated key: when it stops working."},"created_at":{"type":"string","format":"date-time"}},"required":["id","key","mode"]},"FormPatch":{"type":"object","description":"`channel` cannot change (400 `channel_immutable`); on a Google lead form only `name`, `status`, `kind` and `retention_days` apply.","properties":{"name":{"type":"string","maxLength":200},"status":{"type":"string","enum":["active","paused"],"description":"A paused form refuses posts."},"kind":{"type":"string","enum":["enquiry","callback","support","newsletter","careers","other"],"description":"What the form is for. Default `enquiry`. `newsletter` and `careers` submissions never make leads."},"unknown_fields":{"type":"string","enum":["keep","reject"],"description":"`keep` (default) keeps submitted fields the definition does not name; `reject` refuses the post (`unknown`). Controls are never fields, and an empty definition never refuses."},"approved_sites":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Hosts a live key accepts posts from (the request's Origin, else its Referer), such as `www.example.com`; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403 `site_not_approved`) until a site is added. Test keys skip the check."},"redirect_url":{"type":["string","null"],"format":"uri","description":"Where a browser goes after a post, unless the post names an approved `_redirect`. Null: the hosted thank-you page."},"thank_you":{"type":["object","null"],"properties":{"title":{"type":"string","maxLength":200},"body":{"type":"string","maxLength":2000}},"description":"The hosted thank-you page's text."},"honeypot_field":{"type":"string","description":"A hidden field only bots fill (default `botcheck`): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (`_redirect`, `_page`, `_referrer`, `access_key`, `cf-turnstile-response`, any `utm_*`, a click id), a defined field's key or a name the field map reads."},"hold_unsure":{"type":"boolean","description":"Hold submissions the spam check is unsure about for review."},"fields":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/FormField"},"description":"The fields the form defines, checked in order: a blank required field is `missing`, then the type (`invalid`), length, range and `pattern`. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see `unknown_fields`). Empty: any fields are accepted."},"field_map":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}},"description":"Which submitted fields hold the person's name, email and phone. Defaults: `name`, `email`, `phone`."},"retention_days":{"type":"integer","minimum":1,"maximum":3650,"description":"Days a submission is kept. Default 365."},"turnstile":{"type":"string","enum":["off","on"]}},"additionalProperties":false},"FormReceipt":{"type":"object","properties":{"success":{"const":true},"submission_id":{"type":"string"},"lead_id":{"type":["string","null"],"description":"The lead it made. Null when held, when the form's kind makes no leads, or when there was nothing to make one from. Final: the lead is written with the submission."},"status":{"type":"string","enum":["accepted","held","released"]}},"required":["success","submission_id","lead_id","status"]},"FormRefusal":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"},"message":{"type":"string","description":"Worded for the person who sent the form."},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"problem":{"type":"string","enum":["missing","invalid","too_short","too_long","too_small","too_large","pattern","unknown","file_type","file_too_large","too_many_files"]},"message":{"type":"string","description":"The field's own `validation.message`, else a default naming the label and the limit."}}}}},"required":["success","error","message"]},"FormServerSubmission":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"description":"Name to value; a number or boolean is kept as text, a list joined with \", \", a null left out."},"mode":{"type":"string","enum":["live","test"],"default":"live"},"page_url":{"type":"string","maxLength":2000},"referrer":{"type":"string","maxLength":2000},"utm":{"type":"object","additionalProperties":{"type":"string"}},"click_ids":{"type":"object","additionalProperties":{"type":"string"}},"context":{"type":"object","description":"The `_mlf` object from `forms.js`, if the server has it."}},"required":["fields"],"additionalProperties":false},"FormSubmission":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"form_id":{"type":"string"},"key_id":{"type":["string","null"]},"mode":{"type":"string","enum":["live","test"]},"status":{"type":"string","enum":["accepted","held","released","discarded"]},"spam_reason":{"type":["string","null"],"description":"Why the spam check was unsure, comma-separated: `links`, `disposable_email`, `markup`, `not_text`, `no_origin`. Null when it found nothing."},"fields":{"type":"object","additionalProperties":{"type":"string"}},"page_url":{"type":["string","null"]},"referrer":{"type":["string","null"]},"utm":{"type":["object","null"],"additionalProperties":{"type":"string"}},"click_ids":{"type":["object","null"],"additionalProperties":{"type":"string"}},"origin":{"type":["string","null"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2, from the edge."},"dropped_fields":{"type":"array","items":{"type":"string"},"description":"Keys not stored: they named or held a password, card number or national id, or carried a file the form does not define."},"consents":{"type":["array","null"],"items":{"type":"object","properties":{"key":{"type":"string"},"wording":{"type":"string"},"at":{"type":"string","format":"date-time"}}},"description":"Consent fields ticked, with the wording (the field's label) agreed to."},"context":{"type":["object","null"],"description":"The page context `forms.js` sent (`_mlf`), or a server's `context`."},"lead_id":{"type":["string","null"],"description":"The lead it made, if any."},"files":{"type":"array","description":"Its files; download one with `GET /v1/forms/{id}/submissions/{sid}/files/{fileId}`.","items":{"type":"object","properties":{"id":{"type":"string"},"field_key":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string","description":"The type its bytes were sniffed as."},"size_bytes":{"type":"integer"},"scan_status":{"type":"string","enum":["pending","clean","infected","unscannable","not_scanned"],"description":"Its malware scan: `pending` (downloads answer 409 until it is done, usually seconds), `clean`, `infected` (deleted; downloads answer 410), `unscannable` (the scanner could not read it: served, unscanned) or `not_scanned` (stored while scanning was off)."}},"required":["id","field_key","filename","content_type","size_bytes","scan_status"]}},"archived_at":{"type":["string","null"],"format":"date-time","description":"When the submission was archived; null when it is live."},"external_id":{"type":["string","null"],"description":"Google's `lead_id` for a Google lead form's lead; null for a website post."},"ad":{"type":["object","null"],"description":"The ids Google sent with a Google lead form's lead (`platform`, `lead_id`, `form_id`, `campaign_id`, `adgroup_id`, `creative_id`, `asset_group_id`, `gcl_id`, `lead_source`, `lead_stage`, `submitted_at`), with `capture_conversion: false`: Google already counted it. Null for a website post."},"received_at":{"type":"string","format":"date-time"}},"required":["id","form_id","mode","status","fields","received_at"]},"Ga4Settings":{"type":"object","properties":{"assistant":{"type":"object","description":"The assistant-wide property (`integrations.google_analytics`), shared by every channel.","properties":{"measurement_id":{"type":["string","null"]},"api_secret_set":{"type":"boolean"}},"required":["measurement_id","api_secret_set"]},"web_chat":{"type":"object","description":"Web chat's own property (`channels.web_chat.analytics.ga4`) and its options, defaults filled in.","properties":{"measurement_id":{"type":["string","null"]},"api_secret_set":{"type":"boolean"},"data_layer":{"type":"boolean","description":"Push the funnel to the host page's dataLayer."},"gtag":{"type":"boolean","description":"Call the host page's gtag()."},"event_prefix":{"type":"string","description":"Prepended to every event name. Default `chat_`."},"require_consent":{"type":"boolean"},"page_paths":{"type":"string","enum":["section","full"]}},"required":["measurement_id","api_secret_set","data_layer","gtag","event_prefix","require_consent","page_paths"]},"effective":{"type":"object","description":"The property server-side events go to now.","properties":{"source":{"type":["string","null"],"enum":["web_chat","assistant",null]},"measurement_id":{"type":["string","null"]}},"required":["source","measurement_id"]},"status":{"type":["object","null"],"description":"The latest server-side hit; null before the first.","properties":{"last_event":{"type":"string"},"last_status":{"type":"string","enum":["delivered","rejected","unreachable","not_configured","no_identity"]},"last_success_at":{"type":["string","null"],"format":"date-time"},"last_failure_at":{"type":["string","null"],"format":"date-time"},"last_failure_reason":{"type":["string","null"]}},"required":["last_event","last_status","last_success_at","last_failure_at","last_failure_reason"]}},"required":["assistant","web_chat","effective","status"]},"Ga4SettingsUpdate":{"type":"object","additionalProperties":false,"properties":{"assistant":{"type":["object","null"],"additionalProperties":false,"properties":{"measurement_id":{"type":"string","pattern":"^G-[A-Z0-9]{4,20}$"},"api_secret":{"type":"string","minLength":1,"maxLength":128,"writeOnly":true}},"required":["measurement_id"]},"web_chat":{"type":"object","additionalProperties":false,"properties":{"measurement_id":{"type":["string","null"],"pattern":"^G-[A-Z0-9]{4,20}$"},"api_secret":{"type":"string","minLength":1,"maxLength":128,"writeOnly":true},"data_layer":{"type":"boolean"},"gtag":{"type":"boolean"},"event_prefix":{"type":"string","pattern":"^([A-Za-z][A-Za-z0-9_]{0,17})?$","description":"Not `ga_`, `google_` or `firebase_`, which GA4 reserves."},"require_consent":{"type":"boolean"},"page_paths":{"type":"string","enum":["section","full"]}}}}},"HumanMetrics":{"type":"object","description":"What the human advisor's part of a conversation came to.","properties":{"first_response_seconds":{"type":["integer","null"],"description":"From the first takeover to the first human message."},"longest_wait_seconds":{"type":["integer","null"],"description":"The longest a visitor waited on the human, answered or not."},"unanswered_count":{"type":"integer","description":"Visitor messages to the human that no human answered."},"agent_message_count":{"type":"integer"}},"required":["first_response_seconds","longest_wait_seconds","unanswered_count","agent_message_count"]},"HumanReview":{"type":"object","description":"The post-chat review of the human advisor's replies. left_mid_chat and slow_reply come from the transcript's timing; the other codes from the analysis model, which reads only the advisor's messages.","properties":{"flags":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["unanswered_question","spelling_grammar","unprofessional_tone","broken_promise","wrong_fact","other","left_mid_chat","slow_reply"]},"severity":{"type":"integer","minimum":1,"maximum":3},"evidence":{"type":"string","maxLength":200,"description":"A paraphrase; never contact details."}},"required":["code","severity","evidence"]}},"reviewed_through_seq":{"type":"integer","description":"The last message seq the model review read."}},"required":["flags","reviewed_through_seq"]},"Integration":{"type":"object","description":"A configured provider credential. Metadata only: the secret is encrypted at rest and never returned.","properties":{"provider":{"type":"string","description":"Provider slug, e.g. openai, perplexity, deepgram, elevenlabs, twilio."},"key_version":{"type":"integer","description":"Master-key version the secret is sealed under."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"health":{"$ref":"#/components/schemas/IntegrationHealth"}},"required":["provider","key_version","created_at","updated_at","health"]},"IntegrationCreate":{"type":"object","properties":{"project_id":{"type":"string","description":"Required only for an org-wide key."},"secret":{"type":"string","minLength":1,"maxLength":8192,"writeOnly":true,"description":"The raw provider secret (API key, or a JSON blob for multi-field providers). Encrypted at rest; never returned."}},"required":["secret"]},"IntegrationDeleteResult":{"type":"object","properties":{"provider":{"type":"string"},"deleted":{"type":"boolean"}},"required":["provider","deleted"]},"IntegrationHealth":{"type":"object","description":"How the key fared on the latest model calls made with it. Saving a new key starts it again at `unknown`. Health reflects calls made by Search only for now, so a key used only by chat reads `unknown`.","properties":{"status":{"type":"string","enum":["ok","failing","degraded","unknown"],"description":"`ok`: the latest call worked. `failing`: the latest call was refused because the key was rejected or the account is out of credit, and nothing has worked since. `degraded`: the latest call failed for a passing reason (rate limit, provider down, or unclassified). `unknown`: no model call recorded yet."},"last_success_at":{"type":["string","null"],"format":"date-time"},"last_failure_at":{"type":["string","null"],"format":"date-time"},"last_failure_kind":{"type":["string","null"],"enum":["invalid_key","out_of_credit","rate_limited","provider_unavailable","unknown",null],"description":"Why the latest failure happened. Kept after a later success, so read it with `status`."}},"required":["status","last_success_at","last_failure_at","last_failure_kind"]},"IntegrationStatus":{"type":"object","properties":{"provider":{"type":"string"},"project_id":{"type":"string"},"configured":{"type":"boolean"},"verified":{"type":"boolean","description":"True when the provider accepted the key on save. False when it could not be checked (no check for this provider, a scoped key, or the provider was unreachable); the key is stored either way."}},"required":["provider","configured","verified"]},"KnowledgeBase":{"type":"object","properties":{"id":{"type":"string","description":"`kb_...`"},"org_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"active_publication_id":{"type":["string","null"],"description":"The live publication, or null before the first publish."},"version":{"type":"integer","description":"The content counter: bumped when sources change and when `name`, `description` or `enabled` is updated. Approvals, publishing, test picks and `retrieval_mode` leave it as it is."},"retrieval_mode":{"type":"string","enum":["vector_store","hybrid"]},"state":{"type":"string","enum":["empty","updating","live","problem"],"description":"Included on detail and list reads. Updating takes priority while an import or build is running; otherwise failures are problem, an active publication is live, and the remainder is empty."},"source_count":{"type":"integer","description":"List reads: non-revoked sources."},"page_count":{"type":"integer","description":"List reads: non-revoked URL sources."},"reread_weekly":{"type":"boolean"},"last_reread_at":{"type":["string","null"],"format":"date-time"},"next_reread_at":{"type":["string","null"],"format":"date-time"},"test_publication_id":{"type":["string","null"],"description":"The publication sandbox chats search instead of the live one, or null."},"test_base_publication_id":{"type":["string","null"],"description":"The live publication when the sandbox one was picked; promoting is refused once live has moved on."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","org_id","name","description","enabled","active_publication_id","version","retrieval_mode"]},"KnowledgeBaseDetail":{"allOf":[{"$ref":"#/components/schemas/KnowledgeBase"},{"type":"object","properties":{"can_edit":{"type":"boolean","description":"Whether the caller may change this base: admins and above, and admin keys."},"import":{"$ref":"#/components/schemas/KnowledgePageImport"},"configured":{"type":"boolean","description":"Whether this deployment can index and search knowledge."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSource"}},"publications":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgePublication"}},"attachments":{"type":"array","items":{"type":"object","properties":{"assistant_id":{"type":"string"},"name":{"type":"string"},"chat":{"type":"boolean"},"voice":{"type":"boolean"},"priority":{"type":"integer"}},"required":["assistant_id","name","chat","voice","priority"]}},"pending":{"type":"array","description":"What publishing each open assistant draft would change for this base.","items":{"type":"object","properties":{"assistant_id":{"type":"string"},"name":{"type":"string"},"change":{"type":"string","enum":["attach","update","detach"]},"chat":{"type":"boolean"},"voice":{"type":"boolean"},"priority":{"type":"integer"}},"required":["assistant_id","name","change","chat","voice","priority"]}}},"required":["can_edit","sources","publications","attachments","pending"]}]},"KnowledgePageImport":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["running","done","failed"]},"total":{"type":"integer"},"done":{"type":"integer"},"failed":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"},"resource":{"type":"string"},"limit":{"type":"integer"},"used":{"type":"integer"}},"required":["url","error"]}},"started_at":{"type":"string","format":"date-time"}},"required":["status","total","done","failed","started_at"]},"KnowledgePageImportAccepted":{"type":"object","properties":{"total":{"type":"integer"},"import_id":{"type":"string"}},"required":["total","import_id"]},"KnowledgePublication":{"type":"object","properties":{"id":{"type":"string","description":"`kpub_...`"},"status":{"type":"string","enum":["queued","indexing","ready","failed"]},"error":{"type":["string","null"]},"hybrid_error":{"type":["string","null"]},"hybrid_error_details":{"type":["object","null"],"additionalProperties":true},"error_details":{"type":["object","null"],"additionalProperties":true,"description":"Billing refusal body, including message and resource or feature."},"retrying":{"type":"boolean","description":"True while a `failed` publication will be retried automatically: a provider indexing failure (`indexing_failed`, `indexing_timeout` or `provider_file_missing`), fewer than five attempts so far, and no source change since it was built. Keep polling while it is true; otherwise retry it yourself, or build again after a change."},"hybrid_status":{"type":["string","null"],"enum":["queued","indexing","ready","failed",null],"description":"The hybrid search index for this publication, or null when it has none."},"base_version":{"type":"integer","description":"The base version it was built from."},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"}},"required":["id","status","base_version","created_at"]},"KnowledgeRevisionPreview":{"type":"object","properties":{"revision_id":{"type":"string"},"title":{"type":"string"},"text":{"type":"string"},"url":{"type":["string","null"]}},"required":["revision_id","title","text"]},"KnowledgeSearchResult":{"type":"object","properties":{"status":{"type":"string","enum":["unattached","skipped","ok","empty","unavailable"],"description":"`empty`: nothing matched or nothing is published. `unavailable`: search failed this time."},"evidence":{"type":"array","items":{"type":"object","properties":{"knowledge_base_id":{"type":"string"},"publication_id":{"type":"string"},"source_id":{"type":"string"},"revision_id":{"type":"string"},"title":{"type":"string"},"url":{"type":["string","null"]},"text":{"type":"string"},"score":{"type":"number","description":"Similarity, for ordering only; not a confidence."}},"required":["knowledge_base_id","publication_id","source_id","revision_id","title","url","text","score"]}},"elapsed_ms":{"type":"integer"}},"required":["status","evidence","elapsed_ms"]},"KnowledgeSource":{"type":"object","properties":{"id":{"type":"string","description":"`ksrc_...`"},"title":{"type":"string"},"kind":{"type":"string","enum":["text","url","file"]},"url":{"type":["string","null"]},"audience":{"type":"string","enum":["public","private"]},"read_at":{"type":["string","null"],"format":"date-time"},"read_error":{"type":["string","null"],"description":"Last failed read's short code, such as not_found, unreachable, blocked or too_large; cleared after a successful read."},"revoked_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"revision":{"type":["object","null"],"description":"The latest revision.","properties":{"id":{"type":"string","description":"`krev_...`"},"approved":{"type":"boolean"},"characters":{"type":"integer"},"content_hash":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","approved","characters","content_hash","created_at"]}},"required":["id","title","kind","audience","revision"],"additionalProperties":true},"Lead":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"assistant_id":{"type":["string","null"],"description":"The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand)."},"conversation_id":{"type":["string","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"phone":{"type":["string","null"]},"fact_provenance":{"type":"object","description":"Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.","additionalProperties":{"type":"object","required":["source","channel","conversation_id","call_id","form_submission_id","captured_at","captured_at_estimated","edited_at","edited_by"],"properties":{"source":{"type":"string","enum":["conversation","channel","form","manual"]},"channel":{"type":"string","enum":["web_chat","web_call","phone_call","sms","whatsapp","form","ad_form","scheduling","other"]},"conversation_id":{"type":["string","null"]},"call_id":{"type":["string","null"]},"form_submission_id":{"type":["string","null"]},"captured_at":{"type":"string","format":"date-time"},"captured_at_estimated":{"type":"boolean"},"edited_at":{"type":["string","null"],"format":"date-time"},"edited_by":{"type":["string","null"]}}}},"fields":{"type":["object","null"],"additionalProperties":{"type":"string"}},"source":{"type":"string","enum":["web_chat","web_call","phone_call","sms","whatsapp","form","ad_form","scheduling","other"],"description":"Where the lead came from: `web_chat`, `web_call` (a call from a browser), `phone_call`, `sms`, `whatsapp`, `form`, `ad_form` (an ad platform's own lead form, such as a Google lead form), `scheduling` (a booking) or `other` (such as a lead added by hand)."},"mode":{"type":"string","enum":["live","test","preview"],"description":"Capture provenance: the chat mode, independent of email classification."},"test":{"type":"boolean","description":"Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See `traffic` to tell them apart."},"traffic":{"type":"string","enum":["real","sandbox","test"],"description":"Which traffic this belongs to: `sandbox` (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), `test` (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or `real`. Sandbox wins over test. Sandbox and test are both left out of real numbers."},"test_reason":{"type":["string","null"],"enum":["reserved_domain","business_domain","staging_site",null],"description":"Automatic classification, recomputed when saved: `reserved_domain` (placeholder email), `business_domain` (your own email domain) or `staging_site` (a live chat on a staging or preview page). An email reason wins over staging_site."},"test_override":{"type":["boolean","null"],"description":"Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox."},"outcome":{"type":["string","null"],"enum":["open","booked","lost",null],"description":"What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome)."},"outcome_value":{"type":["string","null"],"description":"Booking value as a decimal string."},"outcome_currency":{"type":["string","null"]},"outcome_at":{"type":["string","null"],"format":"date-time"},"outcome_ref":{"type":["string","null"],"description":"The CRM's own id for the booking."},"customer_id":{"type":["string","null"],"description":"The customer's own id for this person, set with PUT /v1/leads/{id}/outcome."},"status":{"type":"string","enum":["new","contacted","qualified","won","lost"],"description":"The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts `new`. `new`, `contacted` and `qualified` are open; `won` and `lost` close it. Separate from `outcome`, which your CRM reports."},"status_changed_at":{"type":["string","null"],"format":"date-time"},"status_changed_by":{"type":["string","null"],"description":"A user id, or the `agent.id` an API key named."},"status_changed_by_name":{"type":["string","null"]},"attribution":{"anyOf":[{"$ref":"#/components/schemas/ChatAttribution"},{"type":"null"}],"description":"Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"capture_method":{"type":"string","enum":["tool","analysis","form","manual","scheduling"],"description":"How the lead was first saved: `tool` (the assistant saved it during the conversation), `analysis` (read from the conversation afterwards), `form` (a form submission) `manual` (added by hand) or `scheduling` (a direct booking). Later updates never change it."},"call_id":{"type":["string","null"],"description":"The call the lead came from, when it came from one."},"form_submission_id":{"type":["string","null"],"description":"The form submission the lead came from, when it came from one."},"phone_e164":{"type":["string","null"],"description":"`phone` in E.164 form when it could be read as a number; `phone` stays as given."},"phone_source":{"type":["string","null"],"enum":["given","caller_id",null],"description":"`caller_id` when a call lead's `phone` is the number the call came from, because the caller never said one. Null means the person gave it."},"first_contacted_at":{"type":["string","null"],"format":"date-time","description":"The first contact: the earliest logged contact, or the first status change out of `new` by a person or key. Null until contacted."},"last_contacted_at":{"type":["string","null"],"format":"date-time","description":"The latest contact."},"next_follow_up_at":{"type":["string","null"],"format":"date-time","description":"When to contact the lead again. Cleared when the lead is won or lost."},"time_to_first_contact_seconds":{"type":["integer","null"],"description":"Wall clock from `created_at` to `first_contacted_at`, in seconds. Null until contacted."},"uncontacted_nudged_at":{"type":["string","null"],"format":"date-time","description":"When `lead.uncontacted` was recorded for the lead; null when it never was."},"merged_into_id":{"type":["string","null"],"description":"The kept lead's id when this lead was merged. Merged leads remain readable by id."}},"required":["id","org_id","project_id","source"]},"LeadAttention":{"type":"object","properties":{"uncontacted":{"type":"integer"},"overdue":{"type":"integer"},"due_today":{"type":"integer"},"late":{"type":"integer","description":"Leads uncontacted or overdue, each counted once: the nav count."},"total":{"type":"integer","description":"Leads in any bucket, each counted once."}},"required":["uncontacted","overdue","due_today","late","total"]},"LeadContact":{"type":"object","properties":{"id":{"type":"string","description":"`lcon_...`."},"channel":{"type":"string","enum":["phone","whatsapp","email","sms","in_person","other"]},"via":{"type":"string","enum":["button","manual","api"],"description":"A console contact button, Log contact, or the API."},"contacted_at":{"type":"string","format":"date-time"},"by":{"type":"string","description":"A user id, or the `agent.id` an API key named."},"by_name":{"type":["string","null"]},"status_moved":{"type":"boolean","description":"Whether this contact moved the lead from `new` to `contacted`."},"logged_at":{"type":"string","format":"date-time","description":"When the contact was logged: the time of the status change it made. Undo is open for a day after."}},"required":["id","channel","via","contacted_at","by","by_name","status_moved","logged_at"]},"LeadCreate":{"type":"object","additionalProperties":false,"properties":{"project_id":{"type":"string","description":"The project the lead belongs to. Required with an org-wide key; a project key uses its own."},"call_id":{"type":"string","minLength":1,"description":"Save an unknown caller as a lead. Must belong to this org and project; 404 otherwise, 409 already_has_lead if already linked. Mutually exclusive with conversation_id. Origin mode and test rules are retained."},"conversation_id":{"type":"string","minLength":1,"description":"Save a conversation as a lead, with the same scope and duplicate checks as call_id. Mutually exclusive with call_id."},"name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","maxLength":320},"phone":{"type":"string","maxLength":64,"description":"As given; include the country code for `phone_e164`."},"fields":{"type":"object","maxProperties":50,"additionalProperties":{"type":"string","maxLength":500},"description":"Any other details, keyed by field key."},"source":{"type":"string","enum":["web_chat","web_call","phone_call","sms","whatsapp","form","ad_form","scheduling","other"],"description":"Defaults to the linked origin channel, or other when unlinked. These are capture channels; search acquisition is not a recorded source value."},"test":{"type":"boolean","description":"Mark it as test (or not) by hand; absent follows the automatic rules."}},"anyOf":[{"required":["email"]},{"required":["phone"]}],"not":{"required":["call_id","conversation_id"]}},"LeadDetail":{"allOf":[{"$ref":"#/components/schemas/Lead"},{"type":"object","properties":{"possible_repeat_of":{"type":"array","items":{"type":"string"},"description":"Detail read only. For a call lead whose caller's number matched earlier open enquiries but who did not say whether this call was about one of them: those leads' ids. Empty otherwise. This historical hint does not perform a merge."},"possible_duplicates":{"type":"array","maxItems":5,"description":"Other unmerged leads in this org and project matching a non-null phone_e164, a non-blank trimmed case-insensitive email, or possible_repeat_of. Dismissals on either side are excluded. Newest first, unique by id; phone wins over email, then repeat_caller. Empty when this lead is merged.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"source":{"type":"string","enum":["web_chat","web_call","phone_call","sms","whatsapp","form","ad_form","scheduling","other"]},"created_at":{"type":"string","format":"date-time"},"reason":{"type":"string","enum":["phone","email","repeat_caller"]}},"required":["id","name","email","phone","source","created_at","reason"]}},"merged_from":{"type":"array","description":"Leads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"source":{"type":"string","enum":["web_chat","web_call","phone_call","sms","whatsapp","form","ad_form","scheduling","other"]},"conversation_id":{"type":["string","null"]},"call_id":{"type":["string","null"]},"form_submission_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","source","conversation_id","call_id","form_submission_id","created_at"]}},"status_history":{"type":"array","description":"Every status change, oldest first.","items":{"type":"object","properties":{"from":{"type":"string","enum":["new","contacted","qualified","won","lost"]},"to":{"type":"string","enum":["new","contacted","qualified","won","lost"]},"at":{"type":"string","format":"date-time"},"by":{"type":"string"},"by_name":{"type":["string","null"]}},"required":["from","to","at","by","by_name"]}},"contacts":{"type":"array","description":"Detail read only. Live logged contacts, newest first; voided ones are left out.","items":{"$ref":"#/components/schemas/LeadContact"}},"form_origin":{"type":["object","null"],"description":"Detail read only. The form a form or `ad_form` lead came from; null for other leads. `ad` holds the ad platform's ids for an `ad_form` lead (`attribution.ad_form` in `lead.captured`), null for a website form.","properties":{"form_id":{"type":"string"},"form_name":{"type":"string"},"channel":{"type":"string","enum":["website","google_lead_form"]},"ad":{"type":["object","null"],"additionalProperties":true}}},"bookings":{"type":"array","description":"Scheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.","items":{"type":"object","required":["id","uid","event_name","status","mode","start_at","end_at","timezone","rescheduled_to_id"],"properties":{"id":{"type":"string"},"uid":{"type":"string"},"event_name":{"type":"string"},"status":{"type":"string","enum":["pending","processing","confirmed","completed","rejected","expired","cancelled","rescheduled"]},"mode":{"type":"string","enum":["live","test"]},"start_at":{"type":"string","format":"date-time"},"end_at":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"rescheduled_to_id":{"type":["string","null"]}}}},"callback":{"type":["object","null"],"description":"The callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.","properties":{"phone":{"type":"string"},"slot_start":{"type":"string","format":"date-time"},"note":{"type":"string"},"requested_at":{"type":"string","format":"date-time"},"done_at":{"type":"string","format":"date-time"},"done_by":{"type":"string"},"done_by_name":{"type":"string"}}}}}]},"LeadOutcomeInput":{"type":"object","properties":{"outcome":{"type":"string","enum":["open","booked","lost"]},"value":{"type":"number","minimum":0,"description":"Booking value, stored to two decimal places."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 code in capitals, for example `GBP`. Required when value is given."},"at":{"type":"string","format":"date-time","description":"When it happened, ISO 8601 with an offset. Default: now."},"ref":{"type":"string","maxLength":128,"description":"Your CRM's id for the booking."},"customer_id":{"type":"string","minLength":1,"maxLength":128,"description":"The customer's own id for this person in their CRM (trimmed). Stored on the lead and used to link this person's chats across devices. Left unchanged when omitted."}},"required":["outcome"],"dependentRequired":{"value":["currency"]}},"LeadSpeed":{"type":"object","properties":{"leads":{"type":"integer","description":"Counted leads: live, not test, not added by hand, created in the window."},"contacted":{"type":"integer"},"uncontacted":{"type":"integer","description":"Counted leads never contacted. Read it beside the median."},"median_seconds":{"type":["integer","null"],"description":"Median time to first contact, contacted leads only."},"p90_seconds":{"type":["integer","null"]},"within_5m":{"type":"integer"},"within_1h":{"type":"integer"},"within_24h":{"type":"integer"},"excluded_manual":{"type":"integer","description":"Leads added by hand in the window (live, not test): left out of every count above."},"by_channel":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["web_chat","web_call","phone_call","sms","whatsapp","form","ad_form","scheduling","other"]},"leads":{"type":"integer"},"contacted":{"type":"integer"},"median_seconds":{"type":["integer","null"]}},"required":["channel","leads","contacted","median_seconds"]}}},"required":["leads","contacted","uncontacted","median_seconds","p90_seconds","within_5m","within_1h","within_24h","excluded_manual","by_channel"]},"LeadsSettings":{"type":"object","properties":{"project_id":{"type":"string"},"uncontacted_after_minutes":{"type":["integer","null"],"minimum":15,"maximum":1440,"description":"Minutes a new lead may wait before `lead.uncontacted`; null turns the nudge off. Default 60."},"counts_contact_hours":{"type":"boolean","readOnly":true,"description":"True when the project has contact hours and a timezone: the wait counts only those hours."}},"required":["project_id","uncontacted_after_minutes","counts_contact_hours"]},"LibraryVoice":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"public_owner_id":{"type":"string"},"gender":{"type":"string"},"accent":{"type":"string"},"language":{"type":"string"},"preview_url":{"type":"string","format":"uri"},"category":{"type":"string"}},"required":["id","name","public_owner_id"]},"OrgMember":{"type":"object","properties":{"user_id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"role":{"$ref":"#/components/schemas/Role"},"created_at":{"type":"string","format":"date-time"}},"required":["user_id","email","name","phone","role","created_at"]},"OutboundCallCreate":{"type":"object","properties":{"assistant_id":{"type":"string","minLength":1},"recipient_timezone":{"type":"string","minLength":1,"maxLength":100,"description":"Recipient's actual IANA timezone when known, for example America/Los_Angeles. Otherwise all candidate zones of the number must be inside the applicable regional calling window. An invalid zone blocks the call. State restrictions still follow the area code. Metadata fields do not override this check."},"to":{"type":"string","minLength":1,"description":"E.164 number to dial, for example `+14155550123`."},"from":{"type":"string","minLength":1,"description":"Optional E.164 caller ID, registered and active in the assistant's organization and project. The call dials from it."},"metadata":{"type":"object","additionalProperties":true,"description":"Your own context, stored on the call and sent in its webhooks."},"variables":{"type":"object","propertyNames":{"pattern":"^[A-Za-z_][A-Za-z0-9_.-]*$","maxLength":64},"additionalProperties":{"type":"string","maxLength":2000},"maxProperties":50,"description":"Per-call values; win over assistant defaults; unresolved keys render as empty strings."},"mode":{"type":"string","enum":["live","test"],"default":"live","description":"test runs the saved draft (live config when there is none) with sandbox restrictions: only declared tools marked read-only that the platform runs server-side (none with their own endpoint), no transfers, DTMF or provider tools, voicemail hangs up. Its webhooks carry livemode: false and reach sandbox subscriptions only."}},"required":["assistant_id","to"]},"OutboundCallCreated":{"type":"object","properties":{"call_id":{"type":"string"},"room":{"type":"string"},"status":{"type":"string","enum":["ringing"]},"unresolved_variables":{"type":"array","items":{"type":"string"},"description":"Present only when a referenced {{key}} had neither a per-call value nor a default."}},"required":["call_id","room","status"]},"PhoneNumber":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":["string","null"]},"project_id":{"type":["string","null"]},"e164":{"type":"string"},"provider":{"type":["string","null"],"description":"Null for a customer-owned forwarding number."},"forward_to":{"type":["string","null"],"description":"The platform E.164 line the customer forwards calls to; null for carrier-managed numbers."},"provider_number_id":{"type":["string","null"],"description":"The provider's own identifier for the number: Twilio's `PN…` SID."},"status":{"type":"string","enum":["active","inactive","released"]},"capabilities":{"type":["object","null"],"additionalProperties":true,"description":"What the provider says the number can do: `{ voice, sms, mms }`."},"routing_mode":{"type":"string","enum":["trunk","pv_webhook"]},"mode":{"type":"string","enum":["live","test"],"description":"Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls."},"assistant_id":{"type":["string","null"]},"provider_metadata":{"type":["object","null"],"additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","e164","provider","status","routing_mode","mode"]},"PhoneNumberAttach":{"type":"object","properties":{"assistant_id":{"type":"string","minLength":1},"routing_mode":{"type":"string","enum":["trunk","pv_webhook"]}},"required":["assistant_id","routing_mode"]},"PhoneNumberImport":{"type":"object","properties":{"project_id":{"type":"string","description":"Required only for an org-wide key."},"e164":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"The number in E.164 format, e.g. +14155550123."},"provider":{"type":["string","null"],"minLength":1,"description":"Carrier slug for a managed number. Null or omitted for a customer-owned forwarding number."},"forward_to":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Required for customer-owned numbers. An active platform number in the same project."},"provider_metadata":{"type":"object","additionalProperties":true,"description":"Carrier identifiers, for example `{\"twilioNumberSid\":\"PN...\"}` for a Twilio number."}},"required":["e164"]},"PhoneNumberMode":{"type":"object","properties":{"routing_mode":{"type":"string","enum":["trunk","pv_webhook"]}},"required":["routing_mode"]},"PhoneNumberPurchase":{"type":"object","properties":{"number":{"type":"string","minLength":1,"description":"The number to purchase in E.164 format, as the search returned it."},"project_id":{"type":"string","description":"Required only for an org-wide key or session."}},"required":["number"]},"PhoneNumberRelease":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"},"released":{"type":"boolean","description":"Whether the carrier released the number. False when it was not carrier-managed or the deployment has no carrier connection; the registry row is deleted either way."}},"required":["id","deleted","released"]},"PhoneNumberUpdate":{"type":"object","properties":{"mode":{"type":"string","enum":["live","test"]}},"required":["mode"],"additionalProperties":false},"PreviewLink":{"type":"object","properties":{"id":{"type":"string","description":"Also the page address: /preview/{id} on the console."},"assistant_id":{"type":"string"},"project_id":{"type":"string"},"key":{"type":"string","description":"The preview key the page loads the widget with."},"access":{"type":"string","enum":["public","team"]},"expires_at":{"type":["string","null"],"format":"date-time"},"expired":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","assistant_id","project_id","key","access","expires_at","expired","created_at"]},"PreviewPage":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"access":{"type":"string","enum":["public","team"]},"key":{"type":"string","description":"Absent for a team-only link read by a non-member."},"assistant_id":{"type":"string"},"name":{"type":"string","description":"The widget's display name."},"subtitle":{"type":["string","null"]},"expires_at":{"type":["string","null"],"format":"date-time"},"org_id":{"type":"string","description":"Present only when the key is withheld."}},"required":["id","access"]}}},"Project":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"default_phone_country":{"type":["string","null"],"pattern":"^[A-Z]{2}$","description":"ISO 3166 alpha-2 country for phones typed without a country code; null when not set."},"timezone":{"type":["string","null"],"description":"IANA time zone the contact hours are read in, such as `Asia/Kolkata`; null when not set."},"contact_hours":{"oneOf":[{"$ref":"#/components/schemas/ContactHours"},{"type":"null"}],"description":"When outreach may contact people; null: only the country rules apply."},"is_default":{"type":"boolean","description":"The organization's default project. Exactly one active project per organization is the default."},"archived_at":{"type":["string","null"],"format":"date-time","description":"When the project was archived, which pauses everything it runs; null while active."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","org_id","name","is_default","archived_at"]},"ProjectCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"]},"ProjectPatch":{"type":"object","properties":{"name":{"type":"string","minLength":1},"default_phone_country":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"timezone":{"type":["string","null"],"description":"An IANA time zone, such as `Asia/Kolkata`."},"contact_hours":{"oneOf":[{"$ref":"#/components/schemas/ContactHours"},{"type":"null"}]}},"minProperties":1,"description":"Other keys (the rest of a project read back) are ignored."},"ProviderLibraryResponse":{"type":"object","properties":{"provider":{"type":"string"},"source":{"type":"string","enum":["live","unavailable"]},"voices":{"type":"array","items":{"$ref":"#/components/schemas/LibraryVoice"}},"next_page":{"type":"integer","minimum":0},"live_error":{"type":"string"}},"required":["provider","source","voices"]},"ProviderModel":{"type":"object","properties":{"provider":{"type":"string","minLength":1},"model":{"type":"string","minLength":1}},"required":["provider","model"],"additionalProperties":true},"ProviderModelsResponse":{"type":"object","properties":{"provider":{"type":"string"},"source":{"type":"string","enum":["live","unavailable"]},"models":{"type":"array","items":{"$ref":"#/components/schemas/TtsProviderModel"}},"live_error":{"type":"string"}},"required":["provider","source","models"]},"ProviderRegistry":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/RegistryMeta"},"capabilities":{"$ref":"#/components/schemas/RegistryCapabilities"}},"required":["meta","capabilities"]},"ProviderVoice":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"gender":{"type":"string"},"accent":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}},"models":{"type":"array","items":{"type":"string"}},"preview_url":{"type":"string","format":"uri"}},"required":["id","name"]},"ProviderVoicesResponse":{"type":"object","properties":{"provider":{"type":"string"},"source":{"type":"string","enum":["live","unavailable"]},"voices":{"type":"array","items":{"$ref":"#/components/schemas/ProviderVoice"}},"live_error":{"type":"string"}},"required":["provider","source","voices"]},"PublicChatLead":{"type":"object","description":"What this visitor has given in this conversation: contact details and the fields the assistant asks for, nothing from other chats or a CRM.","properties":{"fields":{"type":"object","additionalProperties":{"type":"string"}},"complete":{"type":"boolean","description":"An email or phone and every required field are in."}},"required":["fields","complete"]},"PublicConversation":{"type":"object","properties":{"conversation_id":{"type":"string"},"status":{"type":"string","enum":["open","ended"]},"ended_reason":{"type":["string","null"],"enum":["visitor_ended","idle_timeout","max_messages","error",null],"description":"Why it ended. Null while it is open."},"resumable":{"type":"boolean","description":"Ended only because the visitor went quiet and still inside the resume window: the next message reopens it."},"resume_allowed":{"type":"boolean","description":"False once the chat is past the assistant's `resume_days` window (counted from its last message), or can no longer be carried on. A chat still open but past the window is expired too. Sends and uploads to it answer 409 conversation_ended; the widget starts a fresh chat."},"handoff_requested_at":{"type":["string","null"],"format":"date-time"},"taken_over":{"type":"boolean","description":"A person holds the conversation now."},"lead_name":{"type":"string","description":"First name of the captured lead. Present only when there is one."},"lead":{"anyOf":[{"$ref":"#/components/schemas/PublicChatLead"},{"type":"null"}],"description":"Present only when the assistant's web chat `dynamic_ui.lead_panel` or `dynamic_ui.guided` is on: what this visitor has given so far (before the lead is saved too), or null before they have given anything."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/PublicMessage"}}},"required":["conversation_id","status","ended_reason","resumable","resume_allowed","handoff_requested_at","taken_over","messages"]},"PublicLeadSchema":{"type":"object","description":"The lead details a chat asks for, as the visitor's page may show them.","properties":{"require_complete":{"type":"boolean","description":"No lead is saved until every required field and an email or phone are in."},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string","description":"The field's short name for people to read."},"type":{"type":"string","enum":["string","email","phone","number"]},"required":{"type":"boolean"}},"required":["key","label","type","required"]}}},"required":["require_complete","fields"]},"PublicMessage":{"type":"object","description":"A message as the visitor sees it. `agent` is a person who took over the chat.","properties":{"id":{"type":"string","description":"`msg_...`"},"role":{"type":"string","enum":["user","assistant","agent"]},"content":{"type":"string"},"rich":{"$ref":"#/components/schemas/RichContent"},"seq":{"type":"integer","description":"Position in the conversation; pass the highest you have as `after_seq` when polling."},"created_at":{"type":"string","format":"date-time"}},"required":["id","role","content","rich","seq","created_at"]},"PublicWidgetConfig":{"type":"object","description":"The assistant's public web chat settings, as GET /public/v1/config (the widget's GET /public/chat/widget-config) and conversation start return them. Never includes instructions, model settings or secrets.","properties":{"name":{"type":"string","description":"Display name: `appearance.display_name`, or the assistant's name."},"greeting":{"type":"string"},"quick_replies":{"type":"array","items":{"type":"string"}},"hero_topics":{"type":"array","items":{"type":"string"},"description":"Topic buttons shown before the first message."},"appearance":{"type":"object","additionalProperties":true,"description":"Colours, position, display name and avatar."},"proactive":{"type":"object","additionalProperties":true,"description":"When and where to open a teaser on its own."},"strings":{"type":"object","additionalProperties":{"type":"string"},"description":"Interface text overrides."},"call":{"type":["object","null"],"additionalProperties":true,"description":"A phone number to offer in the header, when set."},"whatsapp":{"type":"object","properties":{"number":{"type":"string","description":"The business's WhatsApp number, E.164."},"label":{"type":"string","maxLength":40},"prefill":{"type":"string","maxLength":200,"description":"The message WhatsApp opens with."}},"required":["number"],"description":"Present when the assistant offers \"Continue on WhatsApp\". Get the link to open from POST /public/chat/conversations/{id}/whatsapp-ref; before there is a conversation, open `https://wa.me/<digits>?text=<prefill>`."},"contact_consent":{"type":"object","description":"Present only when the assistant offers consent to be contacted. Once the conversation reports `phone_captured`, show one unticked box per option with its `text` exactly, and send the ticked ones to POST /public/chat/conversations/{id}/contact-consent with their `version`.","properties":{"options":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["whatsapp","sms","voice_human"]},"purpose":{"type":"string","enum":["service","marketing"]},"version":{"type":"integer","description":"The wording version, sent back with a tick."},"text":{"type":"string","description":"The wording to show beside the box, unchanged."}},"required":["channel","purpose","version","text"]}}},"required":["options"]},"handoff_message":{"type":["string","null"],"description":"What to show when the visitor asks for a person."},"powered_by":{"additionalProperties":true},"feedback":{"type":"object","additionalProperties":true,"description":"Whether to ask for reply feedback and a conversation rating."},"attachments":{"type":"object","description":"Present only when the assistant takes files and this deployment can store them.","properties":{"enabled":{"type":"boolean","enum":[true]},"max_bytes":{"type":"integer"},"max_files":{"type":"integer","description":"Per message."},"accept":{"type":"array","items":{"type":"string"},"description":"Accepted content types."}}},"analytics":{"type":"object","properties":{"data_layer":{"type":"boolean"},"gtag":{"type":"boolean"},"event_prefix":{"type":"string"},"require_consent":{"type":"boolean"}},"description":"Off for sandbox and preview chats, so they never reach your analytics."},"identity_scope":{"type":"string","description":"An opaque id for the project, the same for every key in it. Use it to name where you keep a visitor id, so a rotated or second key keeps the same visitors."},"mode":{"type":"string","enum":["test","preview"],"description":"Present only for a sandbox key or a preview link; a live key's config has no `mode`."},"ui":{"type":"object","properties":{"style":{"type":"string","enum":["quiet"]}},"description":"Present only when the assistant uses the quiet chat style."},"dynamic_ui":{"type":"object","properties":{"contact_links":{"type":"boolean","enum":[true]}},"description":"Present only when the assistant shows contact details as links."},"lead_capture":{"$ref":"#/components/schemas/PublicLeadSchema","description":"The lead details the chat asks for, so your page can show what it has captured. Present only when lead capture and `dynamic_ui.lead_panel` are both on."},"voice":{"type":"object","properties":{"enabled":{"type":"boolean","enum":[true]},"max_seconds":{"type":"integer","description":"Each voice session's length cap."}},"required":["enabled","max_seconds"],"description":"Present only when the assistant takes voice in the browser and voice calls can be placed: offer a microphone button (POST /public/v1/conversations/{id}/voice)."}},"required":["name","identity_scope"]},"RateLimitedError":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","const":"rate_limited"},"message":{"type":"string","const":"Too many requests. Try again in a moment."}}},"RecordingAccess":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}},"required":["url","expires_at"]},"RegistryCapabilities":{"type":"object","properties":{"llm":{"$ref":"#/components/schemas/RegistryCapability"},"stt":{"$ref":"#/components/schemas/RegistryCapability"},"tts":{"$ref":"#/components/schemas/RegistryCapability"},"realtime":{"$ref":"#/components/schemas/RegistryCapability"}},"required":["llm","stt","tts","realtime"]},"RegistryCapability":{"type":"object","properties":{"providers":{"type":"array","items":{"$ref":"#/components/schemas/RegistryProvider"}}},"required":["providers"]},"RegistryMeta":{"type":"object","properties":{"sdk_pin":{"type":"string","const":"livekit-agents==1.8.6"},"engine_default":{"type":"string","const":"livekit"},"generated_from":{"type":"string","const":"conversational-voice-runtimes@931b1f8 (LiveKit, 2026-10-23)"}},"required":["sdk_pin","engine_default","generated_from"]},"RegistryModel":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"tier":{"type":"string","enum":["recommended","standard","legacy","deprecated","eol"]},"eol_date":{"type":"string","format":"date"},"notes":{"type":"string"},"unsupported_params":{"type":"array","items":{"type":"string"}},"param_overrides":{"type":"object","description":"Per-model refinement of provider params, keyed by param key. An entry also opts the model into a param gated by applies_to_models.","additionalProperties":{"$ref":"#/components/schemas/RegistryParamOverride"}},"doc_url":{"type":"string","format":"uri"},"verified_at":{"type":"string","format":"date"}},"required":["id","tier"]},"RegistryParam":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string","enum":["number","string","text","boolean","enum","string_list","number_list","object","object_list","key_value"]},"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"},"integer":{"type":"boolean"},"enum_values":{"type":"array","items":{"type":"string"}},"enum_labels":{"type":"object","additionalProperties":{"type":"string"}},"allow_custom":{"type":"boolean"},"advanced":{"type":"boolean"},"default":{},"applies_to_models":{"type":"array","items":{"type":"string"}},"label":{"type":"string"},"help":{"type":"string"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/RegistryParam"}},"item_min":{"type":"number"},"item_max":{"type":"number"}},"required":["key","type"]},"RegistryParamOverride":{"type":"object","properties":{"enum_values":{"type":"array","items":{"type":"string"}},"default":{},"min":{"type":"number"},"max":{"type":"number"}}},"RegistryProvider":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"byok_required":{"type":"boolean"},"inference_served":{"type":"boolean"},"engines":{"type":"array","items":{"type":"string","enum":["livekit","pipecat"]}},"models":{"type":"array","items":{"$ref":"#/components/schemas/RegistryModel"}},"params":{"type":"array","items":{"$ref":"#/components/schemas/RegistryParam"}},"custom_models_allowed":{"type":"boolean"},"requires_voice_id":{"type":"boolean"},"voices":{"type":"array","items":{"$ref":"#/components/schemas/RegistryVoice"}}},"required":["id","label","byok_required","inference_served","engines","models","params","custom_models_allowed"]},"RegistryVoice":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name"]},"RichContent":{"type":["object","null"],"properties":{"quick_replies":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"]}},"buttons":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["link","upload"]},"label":{"type":"string"},"url":{"type":"string","format":"uri","description":"Link buttons only. An upload button opens the file picker."}},"required":["type","label"]}},"metadata":{"type":"object","additionalProperties":true,"properties":{"billing":{"type":"object","description":"AI billing refusal on sandbox assistant messages only (test or preview mode), including the message.completed event. Absent for live visitors.","properties":{"code":{"type":"string","enum":["ai_balance_exhausted","model_price_unavailable","free_request_too_large","plan_limit_reached","feature_not_in_plan"]},"message":{"type":"string"}},"required":["code","message"]},"page":{"type":"object","properties":{"path":{"type":"string"},"title":{"type":"string"}},"required":["path","title"],"description":"Visitor messages from the web widget: the page they sent the message from."},"channel":{"type":"string","enum":["voice"],"description":"A turn spoken in a voice session of this conversation rather than typed."},"voice_session_id":{"type":"string","description":"The voice session the turn was spoken in."}}},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/ConversationAttachment"},"description":"Files sent with the message. Each `url` is a signed link that works without credentials."}}},"Role":{"type":"string","enum":["viewer","member","admin","owner"]},"SecondsPercentiles":{"type":"object","properties":{"median":{"type":["integer","null"]},"p90":{"type":["integer","null"]}},"required":["median","p90"]},"StaffingInsightsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["from","to","timezone","lead_arrivals","lead_arrivals_by_channel","handling_by_channel"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"lead_arrivals":{"type":"array","items":{"type":"object","required":["weekday","hour","count"],"properties":{"weekday":{"type":"integer","minimum":0,"maximum":6},"hour":{"type":"integer","minimum":0,"maximum":23},"count":{"type":"integer"}}}},"lead_arrivals_by_channel":{"type":"array","items":{"type":"object","required":["channel","weekday","hour","count"],"properties":{"channel":{"type":"string"},"weekday":{"type":"integer"},"hour":{"type":"integer"},"count":{"type":"integer"}}}},"handling_by_channel":{"type":"array","items":{"type":"object","required":["channel","handled_by_assistant","handed_to_person"],"properties":{"channel":{"type":"string"},"handled_by_assistant":{"type":"integer"},"handed_to_person":{"type":"integer"}}}}}}}},"TtsProviderModel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"provider_id":{"type":"string","description":"Underlying model company identifier for multi-provider catalogs."},"provider_name":{"type":"string","description":"Underlying model company display name."},"description":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}}},"required":["id"]},"VisitorJourney":{"type":"object","properties":{"visitor_id":{"type":["string","null"]},"visitors":{"type":"array","description":"The visitor ids whose visits are listed: this conversation's own, plus those of conversations in the same organization whose lead shares an email, phone number or customer id. At most 10.","items":{"type":"object","properties":{"visitor_id":{"type":"string"},"linked_by":{"type":"string","enum":["this_chat","email","phone","customer_id"]},"conversation_ids":{"type":"array","items":{"type":"string"}}},"required":["visitor_id","linked_by","conversation_ids"]}},"visits":{"type":"array","items":{"type":"object","properties":{"visit_id":{"type":"string"},"visitor_id":{"type":"string"},"site":{"type":["string","null"],"description":"The site of the visit's earliest event."},"visit_number":{"type":["integer","null"]},"started_at":{"type":"string","format":"date-time"},"last_at":{"type":"string","format":"date-time"},"landing_page":{"type":["string","null"]},"source":{"type":"string","description":"utm_source, else the referrer host, else direct."},"page_views":{"type":"integer"},"pages":{"type":"array","items":{"type":"string"},"description":"The first 10 distinct pages, in the order visited."},"opened_reason":{"type":["string","null"],"enum":["proactive","visitor","api",null]},"sent":{"type":"boolean"},"conversation_ids":{"type":"array","items":{"type":"string"}},"is_this_conversation":{"type":"boolean"}},"required":["visit_id","visitor_id","site","visit_number","started_at","last_at","landing_page","source","page_views","pages","opened_reason","sent","conversation_ids","is_this_conversation"]}},"truncated":{"type":"boolean","description":"True when the visitor has more than 20 visits."}},"required":["visitor_id","visitors","visits","truncated"]},"WebCallCreate":{"type":"object","properties":{"assistant_id":{"type":"string","minLength":1},"metadata":{"type":"object","additionalProperties":true,"description":"Your own context, stored on the call and sent in its webhooks."},"variables":{"type":"object","propertyNames":{"pattern":"^[A-Za-z_][A-Za-z0-9_.-]*$","maxLength":64},"additionalProperties":{"type":"string","maxLength":2000},"maxProperties":50,"description":"Per-call values; win over assistant defaults; unresolved keys render as empty strings."},"mode":{"type":"string","enum":["live","test"],"default":"live","description":"test runs the saved draft (live config when there is none) with sandbox restrictions: only declared tools marked read-only that the platform runs server-side (none with their own endpoint), no transfers, DTMF or provider tools, voicemail hangs up. Its webhooks carry livemode: false and reach sandbox subscriptions only."}},"required":["assistant_id"]},"WebCallCreated":{"type":"object","properties":{"call_id":{"type":"string"},"room":{"type":"string"},"token":{"type":"string","description":"LiveKit join token for the browser, valid for 15 minutes."},"url":{"type":"string","description":"LiveKit server URL to connect to."},"unresolved_variables":{"type":"array","items":{"type":"string"},"description":"Present only when a referenced {{key}} had neither a per-call value nor a default."}},"required":["call_id","room","token","url"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"subscription_id":{"type":"string"},"project_id":{"type":"string"},"event":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"last_status":{"type":["integer","null"],"description":"HTTP status of the latest attempt."},"last_error":{"type":["string","null"]},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","event_id","subscription_id","event","status","attempts","created_at"]},"WebhookEvent":{"type":"object","properties":{"event_id":{"type":"string"},"call_id":{"type":"string"},"event":{"type":"string"},"org_id":{"type":["string","null"]},"project_id":{"type":["string","null"]},"payload":{"type":"object","additionalProperties":true},"received_at":{"type":"string","format":"date-time"}},"required":["event_id","call_id","event","payload","received_at"]},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"url":{"type":"string","format":"uri","description":"Public HTTPS destination. Private addresses and redirects are refused at delivery."},"events":{"type":"array","items":{"type":"string"},"description":"Subscribed event types; empty = all."},"mode":{"type":"string","enum":["live","test"],"description":"live hears about live chats and calls; test (shown as Sandbox in the console) only about sandbox chats (sandbox keys and the console's sandbox chat) and sandbox calls (mode test, sandbox numbers, the console's sandbox call), whose events carry livemode: false. Fixed at creation."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"Set while the subscription is turned off."},"archived_at":{"type":["string","null"],"format":"date-time","description":"When the subscription was archived; null when it is live. An archived subscription gets no deliveries."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","org_id","project_id","url","events"]},"WebhookSubscriptionCreate":{"type":"object","properties":{"project_id":{"type":"string","description":"Required only for an org-wide key."},"url":{"type":"string","format":"uri","pattern":"^https://","description":"Public HTTPS destination. Private addresses and redirects are refused at delivery."},"events":{"type":"array","items":{"type":"string","enum":["call.started","call.connected","call.ended","conversation.started","conversation.message.created","conversation.handoff_requested","conversation.callback_requested","conversation.takeover.started","conversation.takeover.released","conversation.analyzed","conversation.ended","lead.captured","search_reporting.report_ready","search_reporting.alert_raised","search_reporting.alert_resolved","scheduling.routing_matched","scheduling.routing_fallback","booking.created","booking.processing","booking.confirmed","booking.requested","booking.rejected","booking.expired","booking.completed","booking.attendance_updated","booking.guests_updated","booking.reassigned","booking.rescheduled","booking.cancelled","form.submitted","lead.status_changed","lead.uncontacted","lead.follow_up_due","form.health.opened","form.health.resolved","outreach.enrollment.started","outreach.enrollment.stopped","outreach.enrollment.completed","outreach.step.completed"]},"description":"Event types to deliver; empty or omitted means all. An unknown name is refused with 400."},"mode":{"type":"string","enum":["live","test"],"default":"live","description":"Which chats it hears about. It cannot be changed later: create a new subscription instead."},"secret":{"type":"string","minLength":1,"description":"Optional; a whsec_… secret is minted when omitted."},"enabled":{"type":"boolean","description":"False creates the subscription turned off. Default true."}},"required":["url"]},"WebhookSubscriptionCreated":{"description":"A new subscription, with its signing secret. This is the only response that shows the secret.","allOf":[{"$ref":"#/components/schemas/WebhookSubscription"},{"type":"object","properties":{"secret":{"type":"string","description":"HMAC-SHA256 signing key (`whsec_` and 48 hex characters when minted). Verify each delivery by computing the HMAC of the raw body with this whole string as the key."}},"required":["secret"]}]},"WebhookSubscriptionPatch":{"type":"object","minProperties":1,"properties":{"url":{"type":"string","format":"uri","pattern":"^https://","description":"Public HTTPS destination. Private addresses and redirects are refused at delivery."},"events":{"type":"array","items":{"type":"string","enum":["call.started","call.connected","call.ended","conversation.started","conversation.message.created","conversation.handoff_requested","conversation.callback_requested","conversation.takeover.started","conversation.takeover.released","conversation.analyzed","conversation.ended","lead.captured","search_reporting.report_ready","search_reporting.alert_raised","search_reporting.alert_resolved","scheduling.routing_matched","scheduling.routing_fallback","booking.created","booking.processing","booking.confirmed","booking.requested","booking.rejected","booking.expired","booking.completed","booking.attendance_updated","booking.guests_updated","booking.reassigned","booking.rescheduled","booking.cancelled","form.submitted","lead.status_changed","lead.uncontacted","lead.follow_up_due","form.health.opened","form.health.resolved","outreach.enrollment.started","outreach.enrollment.stopped","outreach.enrollment.completed","outreach.step.completed"]},"description":"Replaces the event list; empty means all. An unknown name is refused with 400."},"secret":{"type":"string","minLength":1,"description":"A new signing secret. Write-only."},"enabled":{"type":"boolean","description":"False turns deliveries off; true turns them back on."},"mode":{"type":"string","enum":["live","test"],"description":"Accepted only when it is the subscription's current mode, so a read can be sent back; a change is refused."}}},"WebsiteAssistantDraft":{"type":"object","properties":{"assistant":{"$ref":"#/components/schemas/Assistant"},"draft":{"type":"object","properties":{"generated_by":{"type":"string","enum":["model","template"]},"website":{"type":["string","null"]},"knowledge_base_id":{"type":["string","null"]},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]},"used_for":{"type":"array","items":{"type":"string"}}},"required":["url","title","used_for"]}},"section_facts":{"type":"array","items":{"type":"object","required":["section","field","value","sources"],"properties":{"section":{"type":"string"},"field":{"type":"string"},"value":{},"sources":{"type":"array","items":{"type":"object","required":["url","snippet"],"properties":{"url":{"type":"string"},"snippet":{"type":"string"}}}}}}},"facts":{"type":"object","properties":{"business_name":{"type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"hours":{"type":["string","null"]},"phone":{"type":["string","null"]},"colours":{"type":"array","items":{"type":"string"}},"logo":{"type":["string","null"]},"time_zone":{"type":["string","null"]}},"required":["business_name","services","hours","phone","colours","logo","time_zone"]},"missing":{"type":"array","items":{"type":"string","enum":["hours","phone","services","colours","logo"]}}},"required":["generated_by","website","knowledge_base_id","pages","facts","missing"]}},"required":["assistant","draft"]},"WhatsAppConnection":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"waba_id":{"type":"string","description":"The WhatsApp Business Account id."},"api_version":{"type":"string"},"configured":{"type":"boolean","description":"Credentials are stored. False after a disconnect."},"enabled":{"type":"boolean","description":"False while paused: messages are not answered."},"webhook_path":{"type":"string","description":"The path of the callback URL to give Meta (on the API origin)."},"connected_via":{"type":"string","enum":["manual","embedded"]},"embedded_signup":{"type":["object","null"],"description":"Embedded Signup only: the steps still to run after the connection was created, and why the last try stopped.","properties":{"callback_origin":{"type":"string"},"phone_number_id":{"type":["string","null"]},"coexistence":{"type":"boolean","description":"True when the number stays on the WhatsApp Business app; registration is skipped, including on retries. Optional on older connections."},"pending":{"type":"array","items":{"type":"string","enum":["subscribe","register","sync"]},"description":"Not run yet, or failed and to be retried. A step in neither `pending` nor `skipped` is done."},"skipped":{"type":"array","items":{"type":"string","enum":["register"]},"description":"Registration is skipped when no `phone_number_id` was given or coexistence is true."},"failed_step":{"type":["string","null"],"enum":["subscribe","register","sync",null]},"error":{"type":["string","null"],"description":"Meta's error code (`meta_<code>`), never its message."}}},"account_status":{"type":["object","null"],"description":"The latest `account_update` event from Meta (DISABLED_UPDATE, ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION...).","properties":{"event":{"type":"string"},"detail":{"type":"object","additionalProperties":{"type":"string"}},"at":{"type":"string","format":"date-time"}}},"review_status":{"type":["string","null"],"description":"The latest account review decision: APPROVED, REJECTED, PENDING."},"health_updated_at":{"type":["string","null"],"format":"date-time"},"templates_synced_at":{"type":["string","null"],"format":"date-time","description":"The last template sync attempt."},"templates_synced_ok_at":{"type":["string","null"],"format":"date-time","description":"The last successful template sync."},"templates_sync_error":{"type":["string","null"],"description":"Why the last template sync failed; null after a success."},"numbers":{"type":"array","items":{"$ref":"#/components/schemas/WhatsAppNumber"}}}},"WhatsAppContact":{"type":"object","properties":{"id":{"type":"string"},"number_id":{"type":"string"},"wa_id":{"type":"string","description":"The sender's WhatsApp number."},"profile_name":{"type":["string","null"],"description":"Sender-set, never verified."},"first_inbound_at":{"type":"string","format":"date-time"},"last_inbound_at":{"type":"string","format":"date-time"},"opted_out_at":{"type":["string","null"],"format":"date-time","description":"Set by STOP; cleared by START."},"opted_out_source":{"type":["string","null"]},"marketing_opt_in_at":{"type":["string","null"],"format":"date-time"},"marketing_opt_in_source":{"type":["string","null"]},"marketing_opt_in_by":{"type":["string","null"],"description":"The user or API key that recorded it."},"marketing_opt_in_by_name":{"type":["string","null"],"description":"The recording user's name (or email); null when an API key recorded it."}}},"WhatsAppLink":{"type":"object","properties":{"id":{"type":"string"},"number_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","description":"8 characters starting with C."},"prefill":{"type":["string","null"]},"utm_source":{"type":["string","null"]},"utm_medium":{"type":["string","null"]},"utm_campaign":{"type":["string","null"]},"url":{"type":"string","format":"uri","description":"The wa.me link to share or print as a QR code."},"created_by":{"type":["string","null"],"description":"The user or API key that created it."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"},"conversations":{"type":"integer","description":"List only: WhatsApp conversations this link started."}}},"WhatsAppLinkInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"prefill":{"type":["string","null"],"maxLength":200,"description":"The message WhatsApp opens with."},"utm_source":{"type":["string","null"],"maxLength":100},"utm_medium":{"type":["string","null"],"maxLength":100},"utm_campaign":{"type":["string","null"],"maxLength":100}}},"WhatsAppNumber":{"type":"object","properties":{"id":{"type":"string"},"connection_id":{"type":"string"},"phone_number_id":{"type":"string"},"display_phone_number":{"type":"string"},"verified_name":{"type":["string","null"]},"assistant_id":{"type":["string","null"]},"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["live","test"]},"ad_instructions":{"type":["string","null"],"description":"Instructions for people arriving from an ad."},"failed_replies":{"type":"integer","description":"List only: replies that could not be sent."},"failed_turns":{"type":"integer","description":"List only: incoming messages the assistant failed to answer."},"quality_rating":{"type":["string","null"],"description":"As Meta reports it: GREEN, YELLOW, RED, FLAGGED, UNKNOWN."},"messaging_limit_tier":{"type":["string","null"],"description":"TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED..."},"status":{"type":["string","null"],"description":"CONNECTED, PENDING, FLAGGED, RESTRICTED, BANNED..."},"name_status":{"type":["string","null"],"description":"Display name review: APPROVED, PENDING_REVIEW, DECLINED..."},"health_updated_at":{"type":["string","null"],"format":"date-time"},"next_step":{"type":"string","enum":["resolve_restriction","register_number","verify_display_name","display_name_in_review","raise_quality","none"],"description":"List only: the one thing to do next for this number, most blocking first."}}},"WhatsAppNumberTemplates":{"type":"object","required":["id","connection_id","display_phone_number","verified_name","assistant_id","templates"],"properties":{"id":{"type":"string"},"connection_id":{"type":"string"},"display_phone_number":{"type":"string"},"verified_name":{"type":["string","null"]},"assistant_id":{"type":"string"},"templates":{"type":"array","items":{"type":"object","required":["id","name","language","category","body_preview","variables","parameters","supported"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"body_preview":{"type":"string","description":"Body text with placeholders intact."},"variables":{"type":"object","required":["header","body","buttons"],"properties":{"header":{"type":"array","items":{"type":"string"}},"body":{"type":"array","items":{"type":"string"}},"buttons":{"type":"array","items":{"type":"array","items":{"type":"string"}}}},"description":"Placeholder names in parameter order, per component; buttons are indexed by button position."},"parameters":{"type":"object","required":["header","body","buttons"],"properties":{"header":{"type":"integer"},"body":{"type":"integer"},"buttons":{"type":"array","items":{"type":"integer"}}}},"supported":{"type":"boolean"}}}}}},"WhatsAppOperatorAlerts":{"type":"object","properties":{"connection_id":{"type":"string"},"enabled":{"type":"boolean"},"number_id":{"type":["string","null"],"description":"The account's number that sends the alerts."},"template_name":{"type":["string","null"]},"template_language":{"type":["string","null"]},"staff_numbers":{"type":"array","items":{"type":"string"},"description":"E.164."},"updated_at":{"type":["string","null"],"format":"date-time"},"updated_by":{"type":["string","null"],"description":"The user or API key that saved them."}}},"WhatsAppTemplate":{"type":"object","properties":{"id":{"type":"string"},"connection_id":{"type":"string"},"meta_template_id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string","description":"MARKETING, UTILITY or AUTHENTICATION."},"status":{"type":"string","description":"As Meta reports it: APPROVED, PENDING, REJECTED, PAUSED, DISABLED..."},"components":{"type":"array","items":{"type":"object"},"description":"Meta's template components, as given."},"rejected_reason":{"type":["string","null"]},"quality_score":{"type":["string","null"]},"synced_at":{"type":"string","format":"date-time"},"parameters":{"type":"object","description":"How many values each part takes ({{1}} or named placeholders).","properties":{"header":{"type":"integer"},"body":{"type":"integer"},"buttons":{"type":"array","items":{"type":"integer"}}}},"supported":{"type":"boolean","description":"False for templates with a media header or other parts this API cannot send."}}},"WidgetKey":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"project_id":{"type":"string"},"assistant_id":{"type":["string","null"],"description":"The assistant a pinned key is bound to; null for a project-scoped key."},"key":{"type":"string","description":"Public, revocable widget key, `pk_live_...`."},"kind":{"type":"string","enum":["site","test"],"description":"site keys go on the live website; sandbox keys on a staging site or localhost."},"allowed_origins":{"type":"array","items":{"type":"string"},"description":"Sandbox keys: where the key loads. Site keys use the assistant's allowed_origins."},"revoked_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","org_id","project_id","assistant_id","key"]}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Secret API key from the console (Settings > API keys): `Authorization: Bearer vak_...`"},"conversationToken":{"type":"http","scheme":"bearer","description":"Conversation token (`ct_...`) returned when a public chat conversation starts."}}}}