{"openapi":"3.1.0","info":{"title":"Zentiq API","version":"1.0.0","description":"Real-time conversational AI avatars. Create a persona (face + voice + prompt), mint a session token, and connect over WebRTC. This is the FINALIZED v1 contract (pre-release cleanup, 2026-07-08). Success responses use the { data, error: null, requestId } envelope; errors are exactly { error: { code, message } } with the request id in the X-Request-Id header. Authenticate with an organization API key: `Authorization: Bearer zq_live_…`. IDs are prefixed and opaque (pa_… personas, av_… avatars, vo_… voices, sess_… sessions, key_… keys, wh_… webhooks, kb_… knowledge bases, doc_… documents); endpoints also accept un-prefixed ids on input. Voices: two engines selected with settings.engine — \"premier\" (default; realtime speech-to-speech; 36 languages from any single voice; voice cloning) and \"global\" (70+ languages, prebuilt voices via settings.globalVoice). The avatar understands the user's speech natively in any language — there is no recognition language to configure.","contact":{"name":"Zentiq Support","url":"https://zentiqai.com/support"}},"servers":[{"url":"https://app.zentiqai.com/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Identity"},{"name":"Avatars"},{"name":"Voices"},{"name":"Personas"},{"name":"Sessions"},{"name":"Knowledge"},{"name":"Webhooks"},{"name":"Keys"},{"name":"Usage"}],"paths":{"/health":{"get":{"tags":["Identity"],"summary":"Liveness probe","security":[],"operationId":"health","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Health"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/me":{"get":{"tags":["Identity"],"summary":"Identify the calling API key","operationId":"getMe","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Me"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/languages":{"get":{"tags":["Voices"],"summary":"Supported languages (any voice speaks all of them) + accent keys","operationId":"listLanguages","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/Language"},"description":"The primary languages (first-class ISO codes). Premier voices speak 36 languages in total."},"engines":{"type":"object","description":"The two voice engines selected with settings.engine: premier (default; 36 languages from any voice; cloning) and global (70+ languages, prebuilt voices via settings.globalVoice).","properties":{"premier":{"$ref":"#/components/schemas/VoiceEngine"},"global":{"$ref":"#/components/schemas/VoiceEngine"}}},"accents":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}}},"description":"settings.accent values — English-with-a-foreign-accent."}}},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/usage":{"get":{"tags":["Usage"],"summary":"Usage & billing for the current period","operationId":"getUsage","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Usage"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/avatars":{"get":{"tags":["Avatars"],"summary":"List avatars (built-in + custom)","operationId":"listAvatars","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size. Invalid values return 400."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"A nextCursor from a previous page. Invalid values return 400."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Avatar"}},"error":{"type":"null"},"requestId":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Pass as ?cursor to fetch the next page; null on the last page."}}}}}}}}},"/avatars/{id}":{"get":{"tags":["Avatars"],"summary":"Get an avatar","operationId":"getAvatar","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Avatar"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"}}},"delete":{"tags":["Avatars"],"summary":"Delete a custom avatar (soft)","operationId":"deleteAvatar","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Deleted"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/avatars/{id}/preview":{"get":{"tags":["Avatars"],"summary":"Avatar preview image","operationId":"avatarPreview","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"Image bytes","content":{"image/*":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/voices":{"get":{"tags":["Voices"],"summary":"List voices (built-in + cloned)","operationId":"listVoices","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size. Invalid values return 400."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"A nextCursor from a previous page. Invalid values return 400."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}},"error":{"type":"null"},"requestId":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Pass as ?cursor to fetch the next page; null on the last page."}}}}}}}},"post":{"tags":["Voices"],"summary":"Clone a voice","operationId":"createVoice","description":"Send base64/data-URI audio (10–60s clean speech) as JSON, or use multipart/form-data with a `file`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceCloneInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Voice"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/voices/{id}":{"get":{"tags":["Voices"],"summary":"Get a voice","operationId":"getVoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Voice"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"}}},"delete":{"tags":["Voices"],"summary":"Delete a cloned voice (soft)","operationId":"deleteVoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Deleted"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/personas":{"get":{"tags":["Personas"],"summary":"List personas","operationId":"listPersonas","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size. Invalid values return 400."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"A nextCursor from a previous page. Invalid values return 400."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}},"error":{"type":"null"},"requestId":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Pass as ?cursor to fetch the next page; null on the last page."}}}}}}}},"post":{"tags":["Personas"],"summary":"Create a persona","operationId":"createPersona","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional; safe retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Persona"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"413":{"$ref":"#/components/responses/BadRequest"}}}},"/personas/{id}":{"get":{"tags":["Personas"],"summary":"Get a persona","operationId":"getPersona","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Persona"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"}}},"patch":{"tags":["Personas"],"summary":"Update a persona","operationId":"updatePersona","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Persona"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/BadRequest"}}},"delete":{"tags":["Personas"],"summary":"Delete a persona (soft)","operationId":"deletePersona","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Deleted"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sessions":{"get":{"tags":["Sessions"],"summary":"List sessions","operationId":"listSessions","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size. Invalid values return 400."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"A nextCursor from a previous page. Invalid values return 400."},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","ENDED"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"error":{"type":"null"},"requestId":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Pass as ?cursor to fetch the next page; null on the last page."}}}}}}}}},"/sessions/tokens":{"post":{"tags":["Sessions"],"summary":"Start a live session (mint a client token)","operationId":"createSessionToken","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionTokenInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SessionToken"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"402":{"$ref":"#/components/responses/InsufficientMinutes"},"429":{"$ref":"#/components/responses/ConcurrencyLimit"},"503":{"$ref":"#/components/responses/Capacity"}}}},"/sessions/end-idle":{"post":{"tags":["Sessions"],"summary":"Reclaim this org's dead/idle sessions","operationId":"endIdleSessions","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"reaped":{"type":"integer"}}},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/sessions/{id}":{"get":{"tags":["Sessions"],"summary":"Get a session","operationId":"getSession","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Session"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Sessions"],"summary":"Steer a live session","operationId":"steerSession","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"description":"Swap the system prompt / language / variables for subsequent turns without restarting.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SteerInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Session"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SessionEnded"}}},"delete":{"tags":["Sessions"],"summary":"End a session (alias of /end)","operationId":"deleteSession","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Session"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sessions/{id}/end":{"post":{"tags":["Sessions"],"summary":"End a session (stops billing)","operationId":"endSession","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Session"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sessions/{id}/say":{"post":{"tags":["Sessions"],"summary":"Make the avatar speak exact text now","operationId":"sessionSay","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SayInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"}}},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SessionEnded"}}}},"/sessions/{id}/transcript":{"get":{"tags":["Sessions"],"summary":"Turn-by-turn transcript","operationId":"sessionTranscript","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Transcript"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","operationId":"listWebhooks","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/WebhookList"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook","operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}}},"responses":{"200":{"description":"Created (secret returned once)","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/WebhookWithSecret"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Deleted"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/webhooks/deliveries":{"get":{"tags":["Webhooks"],"summary":"Recent delivery attempts","operationId":"webhookDeliveries","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size. Invalid values return 400."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"A nextCursor from a previous page. Invalid values return 400."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/DeliveryList"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/keys":{"get":{"tags":["Keys"],"summary":"List API keys","operationId":"listKeys","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KeyList"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}},"post":{"tags":["Keys"],"summary":"Mint a scoped API key","operationId":"createKey","description":"Full-access keys only. Returns the secret ONCE.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyInput"}}}},"responses":{"200":{"description":"Created (key returned once)","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KeyWithSecret"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/keys/{id}":{"delete":{"tags":["Keys"],"summary":"Revoke an API key (effective immediately)","operationId":"revokeKey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Deleted"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/knowledge/bases":{"get":{"tags":["Knowledge"],"summary":"List knowledge bases","operationId":"listKnowledgeBases","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size. Invalid values return 400."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"A nextCursor from a previous page. Invalid values return 400."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBase"}},"error":{"type":"null"},"requestId":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Pass as ?cursor to fetch the next page; null on the last page."}}}}}}}},"post":{"tags":["Knowledge"],"summary":"Create a knowledge base","operationId":"createKnowledgeBase","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KnowledgeBase"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}}}}},"/knowledge/bases/{id}":{"get":{"tags":["Knowledge"],"summary":"Get a knowledge base","operationId":"getKnowledgeBase","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KnowledgeBase"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"}}},"patch":{"tags":["Knowledge"],"summary":"Rename a knowledge base","operationId":"updateKnowledgeBase","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KnowledgeBase"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"}}},"delete":{"tags":["Knowledge"],"summary":"Delete a knowledge base (soft; drops its chunks)","operationId":"deleteKnowledgeBase","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Deleted"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/knowledge/bases/{id}/documents":{"get":{"tags":["Knowledge"],"summary":"List documents in a base","operationId":"listDocuments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size. Invalid values return 400."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"A nextCursor from a previous page. Invalid values return 400."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"error":{"type":"null"},"requestId":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Pass as ?cursor to fetch the next page; null on the last page."}}}}}}}},"post":{"tags":["Knowledge"],"summary":"Add a document (file / url / text — async)","operationId":"createDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"description":"Three modes: multipart `file`; or JSON `{ url }`; or JSON `{ text }`. Returns the Document immediately with status \"processing\"; poll GET /knowledge/documents/{id} or subscribe to the knowledge.document.* webhooks.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/DocumentUpload"}},"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"}}}},"responses":{"202":{"description":"Accepted (processing)","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Document"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/UnsupportedMedia"}}}},"/knowledge/bases/{id}/search":{"post":{"tags":["Knowledge"],"summary":"Semantic search within a base","operationId":"searchKnowledge","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SearchResult"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"}}}},"/knowledge/documents/{id}":{"get":{"tags":["Knowledge"],"summary":"Get a document (poll ingestion status)","operationId":"getDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Document"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"}}},"delete":{"tags":["Knowledge"],"summary":"Delete a document (drops chunks + raw file)","operationId":"deleteDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Deleted"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/knowledge/documents/{id}/download":{"get":{"tags":["Knowledge"],"summary":"Short-TTL signed URL for the original file","operationId":"downloadDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Prefixed opaque id from a prior response (e.g. pa_… / sess_… / av_… / vo_…). Un-prefixed ids are also accepted."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/DownloadUrl"},"error":{"type":"null"},"requestId":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"zq_live_…","description":"Organization API key."}},"responses":{"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]}}}}}]}}}},"Gone":{"description":"The resource was deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["gone"]}}}}}]}}}},"BadRequest":{"description":"Validation error / oversize field","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request"]}}}}}]}}}},"SessionEnded":{"description":"Session has ended / is not live","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["session_ended"]}}}}}]}}}},"InsufficientMinutes":{"description":"Monthly minute cap reached","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["insufficient_minutes"]}}}}}]}}}},"ConcurrencyLimit":{"description":"Too many live sessions","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["concurrency_limit"]}}}}}]}}}},"Capacity":{"description":"All avatar slots busy","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["capacity"]}}}}}]}}}},"UnsupportedMedia":{"description":"Unsupported file type","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unsupported_media_type"]}}}}}]}}}}},"schemas":{"Error":{"type":"object","required":["error"],"description":"Uniform error body. The per-request id for support is in the X-Request-Id response header.","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","forbidden","invalid_request","unsupported_media_type","not_found","gone","session_ended","idempotency_conflict","insufficient_minutes","rate_limited","concurrency_limit","capacity","upstream_error","server_error"]},"message":{"type":"string"}}}}},"Health":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}},"Me":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"plan":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"plan":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"includedMinutes":{"type":["number","null"]}}},"limits":{"type":"object","properties":{"maxConcurrentSessions":{"type":"integer"},"activeSessions":{"type":"integer"},"minutesRemaining":{"type":["number","null"]}}},"apiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":["string","null"]}}}}},"Usage":{"type":"object","description":"Plan allowance, minutes used/remaining, breakdown by day / persona / source."},"Avatar":{"type":"object","properties":{"id":{"type":"string","example":"av_…"},"name":{"type":"string"},"kind":{"type":"string","enum":["builtin","custom"]},"previewUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"Voice":{"type":"object","description":"Voices are cross-lingual: one voice speaks EVERY language in `languages` in its own timbre. Choose a voice for timbre; set the spoken language on the persona (settings.language) or per session — not by picking a different voice.","properties":{"id":{"type":"string","example":"vo_…"},"name":{"type":"string"},"language":{"type":["string","null"],"description":"Default language (ISO 639-1).","example":"en"},"languages":{"type":"array","items":{"type":"string"},"description":"The primary languages with first-class ISO codes. Premier voices speak 36 languages in total — set settings.language to any language name."},"kind":{"type":"string","enum":["builtin","custom"]},"createdAt":{"type":"string","format":"date-time"}}},"Language":{"type":"object","properties":{"code":{"type":"string","example":"es"},"name":{"type":"string","example":"Spanish"}}},"VoiceEngine":{"type":"object","description":"A voice engine tier. premier (default) = realtime speech-to-speech, 36 languages from any single voice, voice cloning. global = 70+ languages, prebuilt voices only — select with settings.engine = \"global\" + settings.globalVoice.","properties":{"name":{"type":"string","example":"Multilingual Premier"},"languageCount":{"type":"integer","example":36},"voiceCloning":{"type":"boolean"},"default":{"type":"boolean"},"note":{"type":"string"}}},"PersonaSettings":{"type":"object","description":"Behaviour toggles. `language` is ISO 639-1 (accepts full names on input). Language switching is automatic — the avatar understands the user natively in any language; there is no recognition language to configure.","properties":{"engine":{"type":"string","enum":["premier","global"],"default":"premier","description":"Voice engine. \"premier\" (default): realtime speech-to-speech, 36 languages from any single voice, voice cloning. \"global\": 70+ languages with prebuilt voices — set `globalVoice` too. Omit on update to keep the current engine."},"globalVoice":{"type":"string","example":"Aoede","description":"Global-tier prebuilt voice name. Only meaningful when engine = \"global\". Unknown names normalize to \"\" (the engine default)."},"language":{"type":"string","example":"en","description":"Spoken language (any voice speaks any language; premier voices speak 36). ISO 639-1 or full name."},"skipGreeting":{"type":"boolean"},"interruptible":{"type":"boolean","description":"Allow barge-in (default true)."},"accent":{"type":"string","enum":["","french","german","spanish","italian","portuguese","japanese","korean","russian","chinese"],"description":"Speak ENGLISH content with a native-<language> accent (e.g. \"spanish\" = Spanish-accented English). \"\" = natural. Only applies when language is English. Unknown values normalize to \"\"."},"voice_accent":{"type":"string","enum":["neutral","amgen","valley","south","rp","brixton","transat","aussie"],"description":"English regional accent variant of the voice (default \"neutral\" = American)."},"cc":{"type":"boolean","description":"Show live captions by default (transcript always streams regardless)."},"company":{"type":"string"},"greet_mode":{"type":"string","enum":["single","rotate","ai"]},"greetings":{"type":"array","items":{"type":"string"}}}},"Persona":{"type":"object","properties":{"id":{"type":"string","example":"pa_…"},"name":{"type":"string"},"systemPrompt":{"type":"string"},"greeting":{"type":["string","null"]},"avatarId":{"type":["string","null"]},"voiceId":{"type":["string","null"]},"settings":{"$ref":"#/components/schemas/PersonaSettings"},"knowledge":{"anyOf":[{"$ref":"#/components/schemas/PersonaKnowledge"},{"type":"null"}]},"avatar":{"anyOf":[{"$ref":"#/components/schemas/Avatar"},{"type":"null"}]},"voice":{"anyOf":[{"$ref":"#/components/schemas/Voice"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"PersonaInput":{"type":"object","required":["name","systemPrompt"],"properties":{"name":{"type":"string","maxLength":200},"systemPrompt":{"type":"string","maxLength":16000},"greeting":{"type":"string","maxLength":2000},"avatarId":{"type":"string"},"voiceId":{"type":"string"},"settings":{"$ref":"#/components/schemas/PersonaSettings"},"knowledge":{"anyOf":[{"$ref":"#/components/schemas/PersonaKnowledge"},{"type":"null"}],"description":"Attach/replace knowledge bases; null clears."}}},"VoiceCloneInput":{"type":"object","required":["audioBase64"],"properties":{"name":{"type":"string"},"audioBase64":{"type":"string"},"format":{"type":"string","example":"wav"}}},"Session":{"type":"object","properties":{"id":{"type":"string","example":"sess_…"},"personaId":{"type":["string","null"]},"status":{"type":"string","enum":["ACTIVE","ENDED"]},"source":{"type":"string"},"room":{"type":["string","null"]},"minutesBilled":{"type":["number","null"]},"startedAt":{"type":["string","null"]},"endedAt":{"type":["string","null"]},"duration":{"type":["number","null"]},"createdAt":{"type":"string","format":"date-time"}}},"SessionTokenInput":{"type":"object","required":["personaId"],"properties":{"personaId":{"type":"string","example":"pa_…"},"identity":{"type":"string","description":"Your end-user id (optional)."},"language":{"type":"string","description":"Per-session spoken-language override (ISO or full name)."},"overrides":{"type":"object","properties":{"systemPrompt":{"type":"string","maxLength":16000},"greeting":{"type":"string","maxLength":2000},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Fills {{var}} placeholders in the prompt/greeting."}}}}},"SessionToken":{"type":"object","properties":{"sessionId":{"type":"string"},"sessionToken":{"type":"string","description":"Short-lived LiveKit client token."},"url":{"type":"string","description":"WebRTC transport URL."},"room":{"type":"string"},"persona":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"cc":{"type":"boolean","description":"Persona caption preference. The transcript always streams on data topic \"chat\"; cc is a render hint."}}},"SteerInput":{"type":"object","properties":{"systemPrompt":{"type":"string","maxLength":8000},"language":{"type":"string"},"variables":{"type":"object","additionalProperties":{"type":"string"}}}},"SayInput":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":2000},"interrupt":{"type":"boolean","default":true},"language":{"type":"string"}}},"Transcript":{"type":"object","properties":{"sessionId":{"type":"string"},"turns":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["assistant","user"]},"text":{"type":"string"},"at":{"type":"string","format":"date-time"}}}}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","example":"wh_…"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"WebhookWithSecret":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"Signing secret — returned once."}}}]},"WebhookInput":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["session.started","session.ended","transcript.final","voice.clone.completed","usage.threshold","knowledge.document.processed","knowledge.document.failed","*"]}}}},"WebhookList":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"DeliveryList":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"status":{"type":"integer"},"attempts":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string","example":"key_…"},"name":{"type":["string","null"]},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":["string","null"]},"revokedAt":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"KeyWithSecret":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"key":{"type":"string","description":"Full secret — returned once."}}}]},"KeyInput":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["sessions:read","sessions:write","personas:read","personas:write","voices:read","voices:write","avatars:read","avatars:write","knowledge:read","knowledge:write","usage:read","webhooks:manage"]}}}},"KeyList":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"Deleted":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}},"KnowledgeBase":{"type":"object","properties":{"id":{"type":"string","example":"kb_…"},"name":{"type":"string"},"documentCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"KnowledgeBaseInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200}}},"Document":{"type":"object","properties":{"id":{"type":"string","example":"doc_…"},"knowledgeBaseId":{"type":"string","example":"kb_…"},"name":{"type":"string"},"type":{"type":["string","null"],"enum":["pdf","txt","md","docx","csv","url","text",null]},"bytes":{"type":["integer","null"]},"status":{"type":"string","enum":["processing","ready","failed"]},"chunkCount":{"type":["integer","null"],"description":"Populated when status = ready."},"error":{"type":["string","null"],"description":"Populated when status = failed."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"DocumentInput":{"type":"object","description":"URL mode (`{ url }`) or inline-text mode (`{ text }`). Exactly one.","properties":{"url":{"type":"string","format":"uri","description":"Public http(s) document URL to fetch + ingest."},"text":{"type":"string","maxLength":1048576,"description":"Raw text to ingest (≤ 1 MB)."},"name":{"type":"string","maxLength":200}}},"DocumentUpload":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"pdf/txt/md/docx/csv, ≤ 25 MB."},"name":{"type":"string"}}},"SearchInput":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":4096},"topK":{"type":"integer","minimum":1,"maximum":50,"default":5},"minScore":{"type":"number","minimum":0,"maximum":1,"default":0}}},"SearchResult":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"documentId":{"type":"string","example":"doc_…"},"text":{"type":"string"},"score":{"type":"number","description":"0–1 similarity (higher = closer)."},"metadata":{"type":"object","properties":{"page":{"type":["integer","null"]}}}}}}}},"DownloadUrl":{"type":"object","properties":{"url":{"type":"string","description":"Short-TTL signed URL."},"expiresAt":{"type":"string","format":"date-time"}}},"PersonaKnowledge":{"type":"object","required":["baseIds"],"description":"Attach knowledge bases to a persona. When set, the avatar grounds each turn on retrieved chunks.","properties":{"baseIds":{"type":"array","items":{"type":"string","example":"kb_…"},"minItems":1,"maxItems":20},"topK":{"type":"integer","minimum":1,"maximum":50,"default":5},"minScore":{"type":"number","minimum":0,"maximum":1,"default":0},"maxChars":{"type":"integer","description":"Cap on retrieved context per turn."}}}}}}