{"openapi":"3.1.0","info":{"title":"Zentiq API","version":"2026-10-01","description":"Real-time conversational avatars, and the portals, people, results and leads around them, for your own systems.\n\n**Auth.** An organisation API key: `Authorization: Bearer zq_live_…`. A key acts as an admin of its organisation, limited by its scopes.\n\n**Envelope.** A success is `{ data, error: null, requestId }` (lists add `nextCursor`). An error is `{ error: { code, message, param?, details? } }`, with the request id in the `X-Request-Id` header.\n\n**Ids** are prefixed and opaque (`pa_…`, `sess_…`, `portal_…`); an id without its prefix is accepted on input, an id of another kind is not found.\n\n**Contracts.** A key is pinned to the contract current when it was made; `Zentiq-Version` selects that contract or a newer one, and every answer says which it is in. New fields, endpoints, events and enum values can appear at any time: ignore what you don't know.\n\n**Limits and retries.** Rate limits are per key and per organisation (`RateLimit-*` headers; a 429 has `Retry-After`). Creating calls honour `Idempotency-Key`.","contact":{"name":"Zentiq","url":"https://app.zentiqai.com/apidocs"}},"servers":[{"url":"https://app.zentiqai.com/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Identity","description":"The calling key, the organisation and the API's health."},{"name":"Keys","description":"API keys and their scopes."},{"name":"Usage","description":"Minutes and usage."},{"name":"Languages","description":"The languages avatars speak."},{"name":"Avatars","description":"Faces: the library and your own."},{"name":"Voices","description":"Voices: the library and your clones."},{"name":"Personas","description":"Personas: a face, a voice and what they know and say."},{"name":"Duos","description":"Two-person avatars."},{"name":"Widget","description":"A persona on your website."},{"name":"Knowledge","description":"Knowledge packs and their documents."},{"name":"Sessions","description":"Live conversations."},{"name":"Portals","description":"Portals built from templates, and their doors."},{"name":"Connections","description":"Your own systems (a calendar, a CRM, a shop, an MCP server) that the avatar uses through actions."},{"name":"Subjects","description":"A portal's subjects and their content."},{"name":"Setup","description":"Building portals from a sentence."},{"name":"Jobs","description":"Long-running work."},{"name":"Results","description":"Results, reports, certificates and completion records."},{"name":"Assignments","description":"Assigned work."},{"name":"People","description":"Units, members, learners and guardian consent."},{"name":"Settings","description":"Switches."},{"name":"Hiring","description":"Candidate screening: roles, invites, candidates and decisions."},{"name":"Inbox","description":"Website leads, bookings and hand-offs."},{"name":"Webhooks","description":"Webhooks and their deliveries."},{"name":"Events","description":"The event log."},{"name":"Agents","description":"For AI assistants: ask a business's public website assistant a question (no key)."},{"name":"Dashboards"}],"paths":{"/health":{"get":{"operationId":"health","summary":"Liveness probe","description":"Public and unauthenticated. Answers in the usual envelope.","tags":["Identity"],"security":[],"responses":{"200":{"description":"The API is up.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Health"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-rate-class":"none","x-zentiq-errors":["server_error"],"x-zentiq-since":"2026-07-08"}},"/me":{"get":{"operationId":"getMe","summary":"Identify the calling API key","description":"The key, its organisation, plan and limits. Any valid key may call it: a quick check that a key works.\n\nAny valid key.","tags":["Identity"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The calling key and its organisation.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Me"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/languages":{"get":{"operationId":"listLanguages","summary":"The languages avatars speak, the voice engines and the accent keys","description":"Every language from the catalogue with its code, names and whether a duo speaks it. Any voice speaks any language its `languages` lists: set the language on the persona (`settings.language`) or per session, by code or name. Any valid key may call it.\n\nAny valid key.","tags":["Languages"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The catalogue.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Languages"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/usage":{"get":{"operationId":"getUsage","summary":"Usage & billing for the current period","description":"Session time for the current calendar month (UTC) or the `from`/`to` range, with the plan and the minutes the account holds. An unlimited account has no minute counts (null).\n\nScopes: `usage:read`.","tags":["Usage"],"parameters":[{"name":"from","in":"query","required":false,"description":"Start of the period (ISO date or date-time). Default: the start of this calendar month (UTC).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"End of the period (exclusive). Default: the start of next month (UTC).","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Usage for the period.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Usage"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["usage:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/avatars":{"get":{"operationId":"listAvatars","summary":"List avatars (the library and your own)","description":"The library's faces first, then your organisation's own, oldest first.\n\nScopes: `avatars:read`.","tags":["Avatars"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"kind","in":"query","required":false,"description":"builtin: the library only; custom: your own only.","schema":{"type":"string","enum":["builtin","custom"]}},{"name":"gender","in":"query","required":false,"schema":{"type":"string","enum":["female","male"]}},{"name":"ageBand","in":"query","required":false,"schema":{"type":"string","enum":["20s","30s","40s","50s","60s"]}},{"name":"heritage","in":"query","required":false,"schema":{"type":"string","enum":["white","black","indian","chinese","korean","japanese","thai","hispanic","middleeastern","mixed"]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of avatars.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Avatar"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["avatars:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"post":{"operationId":"createAvatar","summary":"Bring your own avatar picture","description":"A close head-and-shoulders portrait, inline as a data:image URI or fetched from a public https address (6 MB at most); a plain green background gives the cleanest live cut-out. It counts against the plan's custom avatars (403 upgrade_required when there is no room). `consent` is required (400 consent_required before the picture is fetched): it is kept as a consent record the organisation's owners can export and withdraw, and withdrawing it stops the avatar starting new sessions.\n\nScopes: `avatars:write`.","tags":["Avatars"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarInput"}}}},"responses":{"201":{"description":"The new avatar.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Avatar"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`, `consent_required`, `consent_invalid`, `consent_outdated`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"409":{"description":"`idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["avatars:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","consent_required","consent_invalid","consent_outdated","unauthorized","forbidden","upgrade_required","idempotency_conflict","idempotency_in_progress","too_large","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/avatars/{id}":{"get":{"operationId":"getAvatar","summary":"Get an avatar","description":"Scopes: `avatars:read`.","tags":["Avatars"],"parameters":[{"name":"id","in":"path","required":true,"description":"Avatar id (`av_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The avatar.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Avatar"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["avatars:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"delete":{"operationId":"deleteAvatar","summary":"Delete one of your avatars","description":"Refused (409) while a persona still wears it: give that persona another face, or delete it, first. Library faces can't be deleted.\n\nScopes: `avatars:write`.","tags":["Avatars"],"parameters":[{"name":"id","in":"path","required":true,"description":"Avatar id (`av_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","minLength":1,"pattern":"^av_.*","description":"Avatar id (`av_…`).","examples":["av_cmfq2b7x10000abcd1234"]}},"required":["deleted","id"]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["avatars:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/avatars/{id}/preview":{"get":{"operationId":"avatarPreview","summary":"An avatar's picture","description":"A library face is public: link it from an <img> with no header. Your organisation's own pictures (uploaded or generated) are shown only to your organisation: send an API key holding `avatars:read` in the Authorization header; anyone else gets 404, never a hint that the id exists.","tags":["Avatars"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Avatar id (`av_…`); the id without its prefix is accepted too.","schema":{"type":"string"}}],"responses":{"200":{"description":"The picture (PNG, JPEG or WebP).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"image/*":{"schema":{"type":"string"}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-rate-class":"none","x-zentiq-errors":["invalid_request","not_found","server_error"],"x-zentiq-since":"2026-07-08"}},"/voices":{"get":{"operationId":"listVoices","summary":"List voices (the studio voices and your clones)","description":"The studio voices first, then your organisation's clones, oldest first.\n\nScopes: `voices:read`.","tags":["Voices"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"kind","in":"query","required":false,"description":"builtin: the studio voices only; custom: your clones only.","schema":{"type":"string","enum":["builtin","custom"]}},{"name":"gender","in":"query","required":false,"schema":{"type":"string","enum":["female","male"]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of voices.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["voices:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"post":{"operationId":"createVoice","summary":"Clone a voice","description":"Send 10 to 60 seconds of clean speech as JSON (`audioBase64`), or as a multipart `sample` file. `consent` is required: whose voice it is and that they agreed (in multipart, a JSON string field). Without it the request is refused with 400 consent_required before anything is uploaded. The consent is kept as a consent record the organisation's owners can export and withdraw; withdrawing it retires the voice from new sessions. Cloning is a plan feature (403 upgrade_required).\n\nScopes: `voices:write`.","tags":["Voices"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string"},"sample":{"type":"string","format":"binary","description":"The audio file: 10 to 60 seconds of clean speech, 25 MB at most."},"consent":{"type":"string","description":"The Consent object as a JSON string."}},"required":["sample","consent"],"description":"Clone a voice from an uploaded file."}},"application/json":{"schema":{"$ref":"#/components/schemas/VoiceCloneInput"}}}},"responses":{"201":{"description":"The new voice.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Voice"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`, `consent_required`, `consent_invalid`, `consent_outdated`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"409":{"description":"`idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`upstream_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["voices:write"],"x-zentiq-rate-class":"heavy","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","consent_required","consent_invalid","consent_outdated","unauthorized","forbidden","upgrade_required","idempotency_conflict","idempotency_in_progress","too_large","rate_limited","server_error","upstream_error"],"x-zentiq-events":["voice.clone.completed"],"x-zentiq-since":"2026-07-08"}},"/voices/{id}":{"get":{"operationId":"getVoice","summary":"Get a voice","description":"Scopes: `voices:read`.","tags":["Voices"],"parameters":[{"name":"id","in":"path","required":true,"description":"Voice id (`vo_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The voice.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Voice"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["voices:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"delete":{"operationId":"deleteVoice","summary":"Delete a cloned voice","description":"The voice stops being offered at once. Personas that speak with it keep it until they are given another voice; its recording is removed once no persona uses it. Studio voices can't be deleted.\n\nScopes: `voices:write`.","tags":["Voices"],"parameters":[{"name":"id","in":"path","required":true,"description":"Voice id (`vo_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","minLength":1,"pattern":"^vo_.*","description":"Voice id (`vo_…`).","examples":["vo_cmfq2b7x10000abcd1234"]}},"required":["deleted","id"]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["voices:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/personas":{"get":{"operationId":"listPersonas","summary":"List personas","description":"The organisation's own personas, newest first. A portal's persona is not listed here: read and change it with GET and PUT /portals/{id}/persona.\n\nScopes: `personas:read`.","tags":["Personas"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"kind","in":"query","required":false,"description":"single: one person; duo: two people in one conversation.","schema":{"type":"string","enum":["single","duo"]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of personas.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["personas:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"post":{"operationId":"createPersona","summary":"Create a persona","description":"A persona made here is one person: an \"&\" in its name doesn't make a duo (the avatar hears \"and\"), and a duo's two-person picture can't be its face (409). Duos are made from /duos. What the plan decides (a cloned voice) answers 403 upgrade_required.\n\nScopes: `personas:write`.","tags":["Personas"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaInput"}}}},"responses":{"201":{"description":"The new persona.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Persona"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["personas:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","conflict","idempotency_conflict","idempotency_in_progress","too_large","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/personas/{id}":{"get":{"operationId":"getPersona","summary":"Get a persona","description":"One of the organisation's own personas. A portal's persona is 404 here (as for PATCH and DELETE): use /portals/{id}/persona.\n\nScopes: `personas:read`.","tags":["Personas"],"parameters":[{"name":"id","in":"path","required":true,"description":"Persona id (`pa_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The persona.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Persona"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["personas:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"patch":{"operationId":"updatePersona","summary":"Update a persona","description":"Only what is sent changes. A duo made from /duos changes only there (409); a duo's picture and voices only change together; a single persona never takes a duo's picture. What the plan decides answers 403 upgrade_required.\n\nScopes: `personas:write`.","tags":["Personas"],"parameters":[{"name":"id","in":"path","required":true,"description":"Persona id (`pa_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaPatch"}}}},"responses":{"200":{"description":"The persona.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Persona"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["personas:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","gone","too_large","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"delete":{"operationId":"deletePersona","summary":"Delete a persona","description":"Its own picture goes too when no other persona wears it. A duo is refused (409) while a portal uses it.\n\nScopes: `personas:write`.","tags":["Personas"],"parameters":[{"name":"id","in":"path","required":true,"description":"Persona id (`pa_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]}},"required":["deleted","id"]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["personas:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/sessions":{"get":{"operationId":"listSessions","summary":"List sessions","description":"Newest first by start. Every session of the organisation by default; `source=api` lists only the ones started through the API. A candidate's interview and a child's session are never listed, so a page can hold fewer than `limit` items and still have a `nextCursor`.\n\nScopes: `sessions:read`.","tags":["Sessions"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"status","in":"query","required":false,"description":"Only sessions in this status.","schema":{"type":"string","enum":["ACTIVE","COMPLETED","ABANDONED"]}},{"name":"source","in":"query","required":false,"description":"Which sessions: every one (`all`, the default), those your API keys started (`api`), or one kind. A job interview (a candidate's, or a member's mock interview), a child's session and a builder's preview are never listed.","schema":{"type":"string","enum":["api","portal","visitor","playground","demo","guide","all"]}},{"name":"personaId","in":"query","required":false,"description":"Only this persona's sessions (`pa_…`).","schema":{"type":"string"}},{"name":"subjectId","in":"query","required":false,"description":"Only sessions in this subject (`sub_…`).","schema":{"type":"string"}},{"name":"portalId","in":"query","required":false,"description":"Only sessions in this portal's subjects (`portal_…`).","schema":{"type":"string"}},{"name":"personId","in":"query","required":false,"description":"Only this member's sessions (`usr_…`).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Started at or after this moment (ISO 8601).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Started before this moment (ISO 8601).","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of sessions.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/sessions/tokens":{"post":{"operationId":"createSessionToken","summary":"Start a live session (mint a client token)","description":"Starts the session exactly as the console does (the same avatar, voice, engine, look, framing, accent and language), with this session's own prompt, greeting and {{variables}} on top. The response's `disclosure` is the AI disclosure (EU AI Act Article 50), and showing it is required: keep `disclosure.label` visible on or right next to the avatar's video for the whole session and show `disclosure.text` when it starts (`required` is always true; the browser and React SDKs draw the label for you). The avatar also says it's an AI in its opening line. What was sent is recorded against the session and returned by GET /sessions/{id}/analytics. Minutes are checked before the session starts and charged on Zentiq's clock until it ends. When the consent record for the persona's own face or voice can't be checked just now, nothing starts (`503 consent_unverified`): try again shortly. A persona whose face is new or was just changed answers `409 face_not_ready` for about a minute while the live engine prepares it (a session started before then drifts at the opening): retry after `Retry-After`.\n\nScopes: `sessions:write`.","tags":["Sessions"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionTokenInput"}}}},"responses":{"200":{"description":"The session and the token your app joins it with.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SessionToken"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_minutes`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required`, `feature_not_in_plan`, `account_paused` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`duo_not_live`, `face_not_ready`, `consent_withdrawn`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, `concurrency_limit`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`upstream_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`capacity`, `consent_unverified`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`upstream_timeout`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:write"],"x-zentiq-rate-class":"live","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","insufficient_minutes","forbidden","upgrade_required","feature_not_in_plan","account_paused","not_found","duo_not_live","face_not_ready","consent_withdrawn","idempotency_conflict","idempotency_in_progress","rate_limited","concurrency_limit","server_error","upstream_error","capacity","consent_unverified","upstream_timeout"],"x-zentiq-events":["session.started"],"x-zentiq-since":"2026-07-08"}},"/sessions/end-idle":{"post":{"operationId":"endIdleSessions","summary":"Reclaim this org's dead/idle sessions","description":"Closes this organisation's sessions whose room is gone or that ran past the longest session allowed, freeing their places at once.\n\nScopes: `sessions:write`.","tags":["Sessions"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"How many were closed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"reaped":{"type":"integer","description":"How many sessions were closed."}},"required":["reaped"]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-events":["session.ended"],"x-zentiq-since":"2026-07-08"}},"/sessions/{id}":{"get":{"operationId":"getSession","summary":"Get a session","description":"The session with its short analytics: duration, billed minutes and rate, turns, talk share, and the report's summary and score when it has one. The full breakdown is GET /sessions/{id}/analytics. A session GET /sessions never lists (a job interview, a builder's preview, a child's session) is `404` here too: a candidate's interview is read only through the hiring operations (GET /candidates/{id}/interview, with a key an owner or admin gave interview content), never as a session.\n\nScopes: `sessions:read`.","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Session id (`sess_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SessionDetail"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"patch":{"operationId":"steerSession","summary":"Steer a live session","description":"Swap the system prompt, language or variables for the turns that follow, without restarting. Only a session started through the API: any other session of the organisation is `404 not_found`.\n\nScopes: `sessions:write`.","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Session id (`sess_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SteerInput"}}}},"responses":{"200":{"description":"The session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Session"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`session_ended`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`upstream_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","session_ended","rate_limited","server_error","upstream_error"],"x-zentiq-since":"2026-07-08"},"delete":{"operationId":"deleteSession","summary":"End a session (alias of /end)","description":"Only a session started through the API: any other session of the organisation is `404 not_found`.\n\nScopes: `sessions:write`.","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Session id (`sess_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The ended session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Session"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-events":["session.ended"],"x-zentiq-since":"2026-07-08"}},"/sessions/{id}/end":{"post":{"operationId":"endSession","summary":"End a session (stops billing)","description":"Ends the session now: billing stops on Zentiq's clock and the avatar's place is freed. Ending twice is harmless. Only a session started through the API: any other session of the organisation is `404 not_found`.\n\nScopes: `sessions:write`.","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Session id (`sess_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The ended session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Session"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-events":["session.ended"],"x-zentiq-since":"2026-07-08"}},"/sessions/{id}/say":{"post":{"operationId":"sessionSay","summary":"Make the avatar speak exact text now","description":"Scripted lines, \"repeat after me\", announcements, or your system driving every turn (external turn mode). In external turn mode, and for a duo, the line is spoken as sent (`interrupt`, default true, first cuts off speech in progress). A single avatar answering on its own speaks it as its next turn once it is idle: it may paraphrase slightly, and `interrupt`, `endSession`, `turnId` and `eventId` don't apply (end such a session with POST /sessions/{id}/end). Only a session started through the API: any other session of the organisation is `404 not_found`.\n\nScopes: `sessions:write`.","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Session id (`sess_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SayInput"}}}},"responses":{"200":{"description":"The line was handed to the live session.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`session_ended`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`upstream_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","session_ended","rate_limited","server_error","upstream_error"],"x-zentiq-since":"2026-07-08"}},"/sessions/{id}/transcript":{"get":{"operationId":"sessionTranscript","summary":"Turn-by-turn transcript","description":"The conversation as recorded (also live over the realtime data channel). The console's rules apply: a candidate's interview, a young learner's conversation and a website visitor who said they are under 18 are never given out here (403; a hiring system reads a candidate's interview through GET /candidates/{id}/interview), and a session whose subject keeps nothing, a builder's preview, or any session of an organisation with zero data retention on (while it runs too), has no turns (`kept: false`).\n\nScopes: `transcripts:read`.","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Session id (`sess_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The transcript.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Transcript"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required`, `candidate_interview`, `learner_conversation` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["transcripts:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","candidate_interview","learner_conversation","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/sessions/{id}/analytics":{"get":{"operationId":"sessionAnalytics","summary":"Session analytics","description":"Duration, billed minutes and rate (from the minutes ledger), turn counts, talk share (user vs avatar), per-turn timing, the report's summary and score when the session has one, and the AI disclosure sent. A session GET /sessions never lists (a job interview, a builder's preview, a child's session) is `404`.\n\nScopes: `sessions:read`.","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Session id (`sess_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The session's analytics.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SessionAnalytics"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhooks","description":"Newest first. The signing secret is never returned after creation.\n\nScopes: `webhooks:manage`.","tags":["Webhooks"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of webhooks.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["webhooks:manage"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"post":{"operationId":"createWebhook","summary":"Create a webhook","description":"Registers a signed webhook for sendable event types (GET /v1/event-types) or \"*\". The address must be a public https one; it is checked again before every delivery, and redirects are never followed. Deliveries are written in the contract this request runs in. The signing secret is returned once. `includeConversation: true` needs a key holding `transcripts:read`; transcript.final needs it and must be named. While the organisation has zero data retention on, `includeConversation: true` is refused (409 `conflict`, `details.reason` `zero_retention`).\n\nScopes: `webhooks:manage`.","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}}},"responses":{"201":{"description":"Created; the secret is shown once.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/WebhookWithSecret"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["webhooks:manage"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/webhooks/{id}":{"get":{"operationId":"getWebhook","summary":"Get a webhook","description":"Scopes: `webhooks:manage`.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`wh_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The webhook.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Webhook"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["webhooks:manage"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"patch":{"operationId":"updateWebhook","summary":"Change a webhook","description":"Change its address, events, description, contract or conversation option; `active: true` resumes a webhook paused after three days of failed deliveries, `false` switches it off. Turning `includeConversation` on needs `transcripts:read`, and so does changing the address, events or contract of a webhook that receives conversation words, or switching it back on (switching the words off never does); every change of the option is recorded in the organisation's activity log. While the organisation has zero data retention on, any change that leaves `includeConversation` on is refused (409 `conflict`, `details.reason` `zero_retention`); switching it off always works.\n\nScopes: `webhooks:manage`.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`wh_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPatch"}}}},"responses":{"200":{"description":"The webhook as changed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Webhook"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["webhooks:manage"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook","description":"Deletes the webhook and its delivery log.\n\nScopes: `webhooks:manage`.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`wh_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/WebhookDeleted"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["webhooks:manage"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/webhooks/deliveries":{"get":{"operationId":"webhookDeliveries","summary":"The delivery log","description":"Each event's delivery to each webhook, newest first, with its last attempt and, while it is retried, the next one (1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h after the first). Filter by webhook, event, state, success and time.\n\nScopes: `webhooks:manage`.","tags":["Webhooks"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"webhookId","in":"query","required":false,"description":"Webhook id (`wh_…`).","schema":{"type":"string"}},{"name":"eventId","in":"query","required":false,"description":"Event id (`evt_…`).","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"One or more of pending, retrying, delivered, failed, comma-separated.","schema":{"type":"string"}},{"name":"ok","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"from","in":"query","required":false,"description":"Deliveries created at or after this moment.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Deliveries created before this moment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of deliveries.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["webhooks:manage"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/keys":{"get":{"operationId":"listKeys","summary":"List API keys","description":"The organisation's keys, newest first, revoked ones included. Never the secret.\n\nNeeds a full-access key.","tags":["Keys"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of keys.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-full-access":true,"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"post":{"operationId":"createKey","summary":"Mint an API key","description":"Returns the secret once. Rotation: create a new key, move to it, then revoke the old one. A key can only give scopes it holds itself; the new key speaks this request's contract unless `apiVersion` says otherwise.\n\nNeeds a full-access key.","tags":["Keys"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyInput"}}}},"responses":{"201":{"description":"The new key, with its secret (shown once).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KeyWithSecret"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"409":{"description":"`idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-full-access":true,"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/keys/{id}":{"delete":{"operationId":"revokeKey","summary":"Revoke an API key (effective immediately)","description":"The key stops working on its next request. A key can revoke itself.\n\nNeeds a full-access key.","tags":["Keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"API key id (`key_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Revoked.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KeyRevoked"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-full-access":true,"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/knowledge/bases":{"get":{"operationId":"listKnowledgeBases","summary":"List knowledge packs","description":"Newest first, with how many documents each holds.\n\nScopes: `knowledge:read`.","tags":["Knowledge"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of knowledge packs.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBase"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"post":{"operationId":"createKnowledgeBase","summary":"Create a knowledge pack","description":"Scopes: `knowledge:write`.","tags":["Knowledge"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseInput"}}}},"responses":{"201":{"description":"The new knowledge pack.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KnowledgeBase"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"409":{"description":"`idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","idempotency_conflict","idempotency_in_progress","too_large","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/knowledge/bases/{id}":{"get":{"operationId":"getKnowledgeBase","summary":"Get a knowledge pack","description":"Scopes: `knowledge:read`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Knowledge base id (`kb_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The knowledge pack.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KnowledgeBase"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"patch":{"operationId":"updateKnowledgeBase","summary":"Rename a knowledge pack","description":"Scopes: `knowledge:write`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Knowledge base id (`kb_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseInput"}}}},"responses":{"200":{"description":"The knowledge pack.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/KnowledgeBase"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","too_large","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"delete":{"operationId":"deleteKnowledgeBase","summary":"Delete a knowledge pack","description":"Its documents go with it and are no longer answered from.\n\nScopes: `knowledge:write`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Knowledge base id (`kb_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","minLength":1,"pattern":"^kb_.*","description":"Knowledge base id (`kb_…`).","examples":["kb_cmfq2b7x10000abcd1234"]},"detachedFrom":{"type":"integer","description":"How many personas had it attached (it is detached from them)."}},"required":["deleted","id","detachedFrom"]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/knowledge/bases/{id}/documents":{"get":{"operationId":"listDocuments","summary":"List a knowledge pack's documents","description":"Newest first.\n\nScopes: `knowledge:read`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Knowledge base id (`kb_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of documents.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"post":{"operationId":"createDocument","summary":"Add a document (a file, an address or text)","description":"Three ways: a multipart `file`; or JSON `{ url }`; or JSON `{ text }`. Answers at once with the document `processing`; poll GET /knowledge/documents/{id}, or subscribe to the knowledge.document.* webhooks. Documents count against the plan (403 upgrade_required).\n\nScopes: `knowledge:write`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Knowledge base id (`kb_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/DocumentUpload"}},"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"}}}},"responses":{"202":{"description":"Accepted: the document is being read.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Document"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"`unsupported_media_type`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","idempotency_conflict","idempotency_in_progress","gone","too_large","unsupported_media_type","rate_limited","server_error"],"x-zentiq-events":["knowledge.document.processed","knowledge.document.failed"],"x-zentiq-since":"2026-07-08"}},"/knowledge/bases/{id}/search":{"post":{"operationId":"searchKnowledge","summary":"Search a knowledge pack","description":"The same look-up a live session makes, on its own: the passages closest to `query`.\n\nScopes: `knowledge:read`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Knowledge base id (`kb_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchInput"}}}},"responses":{"200":{"description":"The closest passages.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SearchResult"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`upstream_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:read"],"x-zentiq-rate-class":"search","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","too_large","rate_limited","server_error","upstream_error"],"x-zentiq-since":"2026-07-08"}},"/knowledge/documents/{id}":{"get":{"operationId":"getDocument","summary":"Get a document (poll until it is read)","description":"Scopes: `knowledge:read`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Document id (`doc_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The document.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Document"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"delete":{"operationId":"deleteDocument","summary":"Delete a document","description":"Its passages and its original file go with it.\n\nScopes: `knowledge:write`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Document id (`doc_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","minLength":1,"pattern":"^doc_.*","description":"Document id (`doc_…`).","examples":["doc_cmfq2b7x10000abcd1234"]}},"required":["deleted","id"]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/knowledge/documents/{id}/download":{"get":{"operationId":"downloadDocument","summary":"Download a document's original file","description":"A signed address that works for about ten minutes; never a storage path.\n\nScopes: `knowledge:read`.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Document id (`doc_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Where to download it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/DownloadUrl"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["knowledge:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/portals":{"get":{"operationId":"listPortals","summary":"List portals","description":"The organisation's portals, oldest first, a page at a time. Published ones unless `status` says otherwise; archived ones are never listed, and neither are the hidden portals behind personas' website widgets.\n\nScopes: `portals:read`.","tags":["Portals"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"status","in":"query","required":false,"description":"`published` (the default), `draft`, or `all` (both). Archived portals are never listed.","schema":{"type":"string","enum":["published","draft","all"]}},{"name":"unitId","in":"query","required":false,"description":"Only the portals of this team or class (`unit_…`).","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of portals.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Portal"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"post":{"operationId":"createPortal","summary":"Build a portal from templates","description":"Builds a portal with one subject per template (`GET /portals/templates`), and its own persona unless `personaId` is given. It starts as a draft: nobody meets it half set up. With `publish: true` (needs `portals:publish`) it is published once it passes the go-live check, together with its subjects; otherwise it stays a draft and `publishRefused` says what to finish first. Each template's family must be on the plan and one more portal must fit it (`403 upgrade_required`). A duo persona speaks only once it is live (`409 duo_not_live`). Website and screening portals open to visitors (their door opens once published) for a key holding `portals:publish`; without it they stay closed to visitors, and `visitor` in `loginMethods` is `403`, as on update. Speaking with an existing persona (`personaId`) needs `personas:write` as well: that persona speaks elsewhere too (`403`).\n\nScopes: `portals:write`.","tags":["Portals"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalInput"}}}},"responses":{"201":{"description":"The portal (a draft unless it was published).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Portal"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `duo_not_live`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","duo_not_live","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-events":["portal.created","workspace.created","portal.updated","workspace.published"],"x-zentiq-since":"2026-07-08"}},"/portals/templates":{"get":{"operationId":"listPortalTemplates","summary":"Portal templates (the gallery)","description":"The templates `POST /portals` builds subjects from, with what each needs from the plan and whether the organisation's plan includes it. Templates written for two people (duos) are listed where the duo builder is open for the organisation.\n\nAny valid key.","tags":["Portals"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The templates.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PortalTemplate"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/portals/{id}":{"get":{"operationId":"getPortal","summary":"Get a portal","description":"One portal, draft or published. An archived one is `410 gone`.\n\nScopes: `portals:read`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The portal.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Portal"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"patch":{"operationId":"updatePortal","summary":"Update a portal","description":"Changes its name, the sign-in page's welcome line, how people sign in, its team, who speaks on it or its brand: the changes the console's Settings make, with its rules. Adding `visitor` to `loginMethods` opens it to visitors (needs `portals:publish`; on a published portal, the go-live check runs first: `422 go_live_refused`). Publishing is `POST /portals/{id}/publish`. Pointing it at a persona that isn't its own (`personaId`: a standalone persona, a website widget's or another portal's) needs `personas:write` as well (`403`). An archived portal is `410 gone`; a website widget's portal is `409 conflict` (change it with `PUT /personas/{id}/widget`).\n\nScopes: `portals:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalUpdate"}}}},"responses":{"200":{"description":"The portal as it now stands.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Portal"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `duo_not_live`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`go_live_refused`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","duo_not_live","gone","go_live_refused","rate_limited","server_error"],"x-zentiq-events":["portal.updated"],"x-zentiq-since":"2026-07-08"}},"/portals/{id}/persona":{"get":{"operationId":"getPortalPersona","summary":"Who speaks on a portal","description":"An archived portal is `410 gone`.\n\nScopes: `portals:read`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Who speaks.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/PortalPersona"},{"type":"null"}]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"put":{"operationId":"updatePortalPersona","summary":"Change who speaks on a portal","description":"The console's Persona tab over the API. The face and voice by id (`avatarId` from `GET /avatars`, `voiceId` from `GET /voices`); `face` and `voice` by name still work and are deprecated. `accent` in plain words (British, Australian). `character` and `greeting` are set word for word within the console's limits (character 4,000, greeting 300, name 80 characters; longer is `413`). A duo keeps its two people (`409 conflict`). With `portals:write` this changes the portal's own persona only; one it borrows (a standalone persona, a website widget's or another portal's) changes wherever else it speaks, so it needs `personas:write` as well (`403`). An archived portal is `410 gone`.\n\nScopes: `portals:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalPersonaUpdate"}}}},"responses":{"200":{"description":"Who speaks now.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/PortalPersona"},{"type":"null"}]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","gone","too_large","rate_limited","server_error"],"x-zentiq-events":["portal.updated"],"x-zentiq-since":"2026-07-08"}},"/setup/plan":{"post":{"operationId":"planSetup","summary":"Plan a portal from one sentence","description":"Magic Setup's planner: what the avatar should do, in plain words, in; the template, a name and who it is for out. Writes nothing: `POST /portals` with the template builds it. A duo template is planned only where the duo builder is open for the organisation. Each plan spends one of the organisation's daily AI helper uses (`429 rate_limited`, `details.allowance: \"ai_daily\"`, when they are used up).\n\nScopes: `portals:read`.","tags":["Setup"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetupPlanInput"}}}},"responses":{"200":{"description":"The plan.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SetupPlan"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"409":{"description":"`idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:read"],"x-zentiq-rate-class":"heavy","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/portals/{id}/publish":{"post":{"operationId":"publishPortal","summary":"Publish a portal","description":"Opens a draft (or brings back an archived) portal at its address, once it passes the go-live check (every subject set up with the organisation's own details, never a template's example content); its draft subjects are published with it. A refusal is `422 go_live_refused` with `details.problems` for keys on 2026-10-01; keys on 2026-07-08 get the portal back unchanged (200) with `publishRefused`. Bringing back an archived portal must fit the plan's portal limit (`403 upgrade_required`). Already published: returned unchanged.\n\nScopes: `portals:publish`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"The portal.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Portal"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`go_live_refused`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:publish"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","go_live_refused","rate_limited","server_error"],"x-zentiq-events":["portal.updated","workspace.published"],"x-zentiq-since":"2026-07-08"}},"/portals/{id}/embed-tokens":{"post":{"operationId":"createEmbedToken","summary":"Sign one of your users in (an embed token)","description":"Called by your backend after your own login, never from a browser. Returns a five-minute, single-use token for a published portal: `embedUrl` goes in an iframe (zentiq-embed.js or `@zentiq/react`'s `<ZentiqPortal>`), `url` opens the portal as that user. The person is the one `POST /people` knows by the same `externalId`. Never someone who runs your Zentiq account. A leader beyond the plan's staff seats is `403 upgrade_required`; a learner under the consent age waits for a guardian's consent unless `consent: { by: \"organisation\" }` attests it (with `people:write` as well). A retry makes a new token (nothing is replayed).\n\nScopes: `embed:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedTokenInput"}}}},"responses":{"201":{"description":"The token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/EmbedToken"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["embed:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"natural","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/duos":{"get":{"operationId":"listDuos","summary":"List the organisation's duos","description":"Newest first. While duos are closed to the organisation (GET /duos/access `builderOpen: false`) this answers 404.\n\nScopes: `duos:read`.","tags":["Duos"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of duos.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Duo"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["duos:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"post":{"operationId":"createDuo","summary":"Add a ready-made duo","description":"A copy of a ready-made duo, as a draft: its persona (\"A & B\"), its picture and a voice each. It takes one of the plan's custom-avatar places (403 upgrade_required when there is none) and needs duos on the plan. Publish it to have it tested and go live. While duos are closed to the organisation (GET /duos/access `builderOpen: false`) this answers 404.\n\nScopes: `duos:write`.","tags":["Duos"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuoInput"}}}},"responses":{"201":{"description":"The new duo (draft).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Duo"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["duos:write"],"x-zentiq-rate-class":"heavy","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/duos/{id}":{"get":{"operationId":"getDuo","summary":"Get a duo","description":"Poll it after publishing: it goes live once its test run has passed. While duos are closed to the organisation (GET /duos/access `builderOpen: false`) this answers 404.\n\nScopes: `duos:read`.","tags":["Duos"],"parameters":[{"name":"id","in":"path","required":true,"description":"Duo id (`duo_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The duo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Duo"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["duos:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/duos/access":{"get":{"operationId":"getDuoAccess","summary":"What the organisation may do with duos","description":"Whether duos are open to the organisation, and what its plan allows: ready-made duos, its own duos.\n\nScopes: `duos:read`.","tags":["Duos"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The organisation's duo access.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/DuoAccess"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["duos:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/duos/library":{"get":{"operationId":"listDuoLibrary","summary":"Zentiq's ready-made duos","description":"The ready-made duos an organisation can copy (POST /duos), in library order. While duos are closed to the organisation (GET /duos/access `builderOpen: false`) this answers 404.\n\nScopes: `duos:read`.","tags":["Duos"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The library.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LibraryDuo"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["duos:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/duos/{id}/publish":{"post":{"operationId":"publishDuo","summary":"Publish a duo","description":"Sends it to be set up and tested: it becomes ready_for_render, then live once its short test run (each person says a line) has passed, or needs_changes. 409 says what is still missing; a second publish while it is on its way changes nothing; a live duo is published again only after a change. Sessions and portals take it once it is live. While duos are closed to the organisation (GET /duos/access `builderOpen: false`) this answers 404.\n\nScopes: `duos:write`.","tags":["Duos"],"parameters":[{"name":"id","in":"path","required":true,"description":"Duo id (`duo_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"The duo, on its way.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Duo"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["duos:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/personas/{id}/widget":{"get":{"operationId":"getPersonaWidget","summary":"Get a persona's website widget","description":"How it shows, where it may appear, where requests go, whether it is on and live, what it still needs (`steps`) and the code to paste. Before the first PUT it answers with `exists: false`. Only the organisation's own personas have a widget (not a portal's persona).\n\nScopes: `widgets:read`.","tags":["Widget"],"parameters":[{"name":"id","in":"path","required":true,"description":"Persona id (`pa_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The widget.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Widget"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["widgets:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"put":{"operationId":"updatePersonaWidget","summary":"Set up a persona's website widget, switch it on or off","description":"The first call makes the widget (a hidden website-assistant portal for the persona, never listed by GET /portals), off. Change how it shows (floating or inline, minimized or expanded, one of four corners, the button), the websites that may show it and where visitors' requests go. `on: true` needs the `portals:publish` scope, the plan's website assistants and website embedding (403 upgrade_required), and everything `steps` lists: otherwise `422 go_live_refused` names what is missing in `details.problems`, with the widget unchanged in `details.widget`. While it is on, changing `requestEmail` or `allowedOrigins` needs `portals:publish` too (403). Switching on also lets outside visitors talk to the organisation's avatars (its public-website switch). `on: false` closes its door at once.\n\nScopes: `widgets:write`.","tags":["Widget"],"parameters":[{"name":"id","in":"path","required":true,"description":"Persona id (`pa_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetInput"}}}},"responses":{"200":{"description":"The widget as saved, and what happened.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/WidgetSaved"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`go_live_refused`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["widgets:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","go_live_refused","rate_limited","server_error"],"x-zentiq-events":["portal.updated","portal.created","workspace.published"],"x-zentiq-since":"2026-10-01"}},"/sessions/{id}/staff-token":{"post":{"operationId":"createStaffToken","summary":"Join a visitor's live conversation as a person from your team","description":"A member of your team joins a website visitor's live avatar conversation as themselves (their own voice, and their camera when they turn it on), for example from your own helpdesk. The avatar says who joined and what the visitor needs, then goes quiet; when the last person leaves it carries on, or the conversation ends if the visitor has gone. A member's own key (made by them in the console) joins as them; a full-access key may name any member in `userId`. The member must be able to open the portal's inbox, the switch serve.staff_join must be on, and at most two people from the team can be in one call. Records handoff.joined.\n\nScopes: `sessions:write`.","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Session id (`sess_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffTokenInput"}}}},"responses":{"200":{"description":"The member's token for the visitor's room.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/StaffToken"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `session_ended`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`upstream_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`capacity`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["sessions:write"],"x-zentiq-rate-class":"live","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","session_ended","rate_limited","server_error","upstream_error","capacity"],"x-zentiq-events":["handoff.joined"],"x-zentiq-since":"2026-07-08","x-mcp-exclude":true}},"/portals/{id}/go-live":{"get":{"operationId":"getPortalGoLive","summary":"Check a portal can go live","description":"Runs the go-live check a publish runs, and says what each subject still needs (its content's field, in plain words). Changes nothing.\n\nScopes: `portals:read`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Whether it can go live, and what to finish first.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/PortalGoLive"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/portals/{id}/customer-tokens":{"post":{"operationId":"createCustomerToken","summary":"Mint an identity token for a signed-in customer (Actions)","description":"Called by your backend, where your customer is signed in, never from a browser. Returns a short-lived token naming that customer, for this portal only: give it to the website widget (`data-customer-token`, or `ZentiqWidget.identify(token)`) or to a conversation's start (`customerToken`), and the avatar's actions for signed-in customers run with that customer's id, never an id the visitor said. 10 minutes unless you ask; never more than 15 (a longer `ttlSeconds` is cut to 15: `expiresAt` says when). Mint one per page view. A token works for one conversation only: the first conversation that uses it keeps it, and any other refuses it even while it lives. A portal of another organisation is `404`; an archived one `410`. Each mint is recorded for your organisation with the portal, the key and how long the token lives, never who it names. A key that lives on your website's servers needs only this scope. Verified customer: `contact.email` is the address on record where Zentiq sends a one-time code before a sensitive action (when your organisation switches it on); it is signed into the token and never shown to the avatar or kept in a transcript or log. For a visitor who isn't signed in, an action's answer can name it instead, in the reserved field `zentiq_verify: { email }`.\n\nScopes: `customers:tokens`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerTokenInput"}}}},"responses":{"201":{"description":"The token.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CustomerToken"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["customers:tokens"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error"],"x-zentiq-since":"2026-07-08","x-mcp-exclude":true}},"/portals/{id}/escalations":{"post":{"operationId":"createEscalation","summary":"Hand a chat to the video avatar","description":"Called by your chat tool's server (Intercom, Zendesk or your own), never from a browser. Returns a link to show the customer: it opens the portal's website avatar, which starts knowing the chat so far (as information, never as instructions) and opens with a one-line recap. The link works for one conversation, for 30 minutes. When that conversation ends, `escalation.completed` goes to your webhooks with the outcome (the summary only with includeConversation), and the visitor is offered `returnUrl`. Needs the switch serve.chat_escalation on and the portal's public page open (`409 conflict`, `details.reason`: switched_off, door_closed or no_website_subject). Chat handover is on Starter and up: on a plan without it, `403 upgrade_required` with `details.reason` `plan_required` and `details.plan`. A portal of another organisation is `404`; an archived one `410`. A retry makes a new link (nothing is replayed).\n\nScopes: `escalations:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EscalationInput"}}}},"responses":{"201":{"description":"The link.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Escalation"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["escalations:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","gone","rate_limited","server_error"],"x-zentiq-since":"2026-10-01","x-mcp-exclude":true}},"/portals/{id}/case-links":{"get":{"operationId":"listCaseLinks","summary":"List a portal's case links","description":"The portal's case links, newest first, with their state and opens. Never the case's details or the links' addresses. A link's row is deleted 30 days after it stops working.\n\nScopes: `cases:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of links.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CaseLink"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["cases:write"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01","x-mcp-exclude":true},"post":{"operationId":"createCaseLink","summary":"Send a customer a link to their case","description":"A personal link to the portal's website door for one customer and one case (an order, a claim, an appointment, a support ticket), made by your CRM or helpdesk. Send `url` by email, text message or your app: when they open it, the avatar greets them about their case and already knows what it is about. The link expires (7 days unless you say, 30 at most), opens at most `maxOpens` conversations (20 unless you say) and can be revoked. The case is your record: the avatar reads it as data (never as instructions), only ever says the email masked, and stops talking about it if the visitor may be under 18. The conversation's actions run for this customer (`customer.id`) and carry the case (`case: { reference, kind }`), so your system finds it without asking. A link is recognition, not a full identity check (anyone holding it is taken for your customer): for anything sensitive, switch on Verified customer, which sends a one-time code to the email you gave. `url` is only in this answer: Zentiq keeps a hash, never the link. The case's details are kept encrypted and wiped when the link stops working. `409 conflict` with `details.reason` `case_links_off` while the organisation's serve.case_links switch is off, and `door_closed` while the portal's website door isn't open to visitors (published, open to visitors, with a website subject live). Case links are on Starter and up: on a plan without them, `403 upgrade_required` with `details.reason` `plan_required` and `details.plan`. A portal of another organisation is `404`; an archived one `410`.\n\nScopes: `cases:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseLinkInput"}}}},"responses":{"201":{"description":"The link, with the address to send (only in this answer).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CaseLinkCreated"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["cases:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","gone","rate_limited","server_error"],"x-zentiq-since":"2026-10-01","x-mcp-exclude":true}},"/case-links/{id}":{"get":{"operationId":"getCaseLink","summary":"Get a case link","description":"One link's state: whether it still opens, how many conversations it started, when it expires. Never the case's details or the link's address.\n\nScopes: `cases:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Case link id (`clk_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The link.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CaseLink"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["cases:write"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01","x-mcp-exclude":true},"delete":{"operationId":"revokeCaseLink","summary":"Revoke a case link","description":"The link stops opening at once and its case details are wiped; a conversation it already started goes on. Revoking a link that is already revoked changes nothing. Works while the switch is off.\n\nScopes: `cases:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Case link id (`clk_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The link, revoked.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CaseLink"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["cases:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01","x-mcp-exclude":true}},"/connections":{"get":{"operationId":"listConnections","summary":"List your connected systems","description":"Every connection of the organisation with its status and health (the share of calls answered, the median time, the last problem in plain words). Never a key: only a masked hint.\n\nScopes: `connections:write`.","tags":["Connections"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The connections, and whether the switch is on.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/ConnectionList"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["connections:write"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-07-08","x-mcp-exclude":true},"post":{"operationId":"createConnection","summary":"Connect one of your systems","description":"Connects a system the avatar will use through actions: a remote MCP server (no sign-in, a bearer token, or OAuth), Cal.com (an API key), HubSpot (a private app's token), Shopify (the shop and an Admin API token), a calendar (`google_calendar`, `microsoft_calendar`: a sign-in, once Zentiq's app is set up for them). A key is checked with a read-only call before it is saved, then sealed and never returned: only a masked hint. An MCP server's tools are read first. A sign-in answers with `authorizeUrl`, where an owner approves it while signed in to the console; until then the connection is `pending`. The address of an MCP server must be public https on the standard port. Off (`403`) while the organisation's actions.connectors switch is off. Connecting your own systems is on Plus and up: on a plan without it, `403 upgrade_required` with `details.reason` `plan_required` and `details.plan`.\n\nScopes: `connections:write`.","tags":["Connections"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionInput"}}}},"responses":{"201":{"description":"Connected (or waiting for its sign-in).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/ConnectionCreated"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["connections:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","conflict","rate_limited","server_error"],"x-zentiq-since":"2026-07-08","x-mcp-exclude":true}},"/connections/{id}":{"delete":{"operationId":"deleteConnection","summary":"Disconnect a system","description":"Deletes the connection and its key. Every action that used it is switched off (`actionsOff` says how many). Works while the switch is off, on any plan.\n\nScopes: `connections:write`.","tags":["Connections"],"parameters":[{"name":"id","in":"path","required":true,"description":"Connection id (`conn_…`).","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Disconnected.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/ConnectionDeleted"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["connections:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08","x-mcp-exclude":true}},"/connections/{id}/test":{"post":{"operationId":"testConnection","summary":"Test a connection","description":"A read-only call that proves the connection still works (an MCP server's tools are read again), counted on its health. It never changes anything. On a plan without connecting your own systems (Plus and up): `403 upgrade_required` with `details.reason` `plan_required`.\n\nScopes: `connections:write`.","tags":["Connections"],"parameters":[{"name":"id","in":"path","required":true,"description":"Connection id (`conn_…`).","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"How it went.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/ConnectionTest"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["connections:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-since":"2026-07-08","x-mcp-exclude":true}},"/portals/{id}/doors":{"get":{"operationId":"listPortalDoors","summary":"Every way in to a portal","description":"The addresses to hand out: the members' sign-in page, the visitors' page (whether it is open now, and what would open it), the embed for your signed-in users, and the custom domain.\n\nScopes: `portals:read`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The doors.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/PortalDoors"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/portals/{id}/doors/visitors":{"put":{"operationId":"updateVisitorDoor","summary":"Open or close the visitors' door","description":"Sets the websites that may show the visitor page and start conversations from it (`allowedOrigins`, at most 20; [] allows any), and opens or closes the door (`open`). Opening needs `portals:publish`; on a published portal it runs the go-live check on what the door opens (`422 go_live_refused`), and it lets outside people talk to the organisation's avatars (its public website switch). Only a portal with a website assistant or a screening role has a visitors' door (`409 conflict`).\n\nScopes: `portals:write`.","tags":["Portals"],"parameters":[{"name":"id","in":"path","required":true,"description":"Portal id (`portal_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitorsDoorUpdate"}}}},"responses":{"200":{"description":"The visitors' door as it now stands.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/VisitorsDoor"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`go_live_refused`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","go_live_refused","rate_limited","server_error"],"x-zentiq-events":["portal.updated","setting.changed"],"x-zentiq-since":"2026-07-08"}},"/subjects/{id}":{"get":{"operationId":"getSubject","summary":"Get a subject","description":"One subject: its template and kind, its live version and pending draft, its languages and the portals it is on.\n\nScopes: `content:read`.","tags":["Subjects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The subject.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Subject"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["content:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"patch":{"operationId":"updateSubject","summary":"Change a subject","description":"Its `name`, its unit (`unitId`; null: the organisation level), and for a website subject the language rule for its visitors (`visitorLanguage`: `follow` the visitor's language, keep to its `languages` (`listed`), or `english`; null goes back to the organisation's own setting). Only the fields sent change, and what sessions run changes at once. `visitorLanguage` on any other subject is `409 conflict` (`details.reason: \"not_a_website_subject\"`), and so is one the organisation has locked (`\"locked\"`). A website widget's subject changes with its avatar (`PUT /personas/{id}/widget`: `409 conflict`, `\"widget\"`).\n\nScopes: `content:write`.","tags":["Subjects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubjectInput"}}}},"responses":{"200":{"description":"The subject as it now stands.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Subject"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["content:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-events":["setting.changed"],"x-zentiq-since":"2026-07-08"}},"/subjects/{id}/content":{"get":{"operationId":"getSubjectContent","summary":"Read a subject's content","description":"The content document of one version: facts, FAQs, opening hours, scenarios, questions, the rubric, a screening role... one section per thing a business edits, in camelCase. By default the pending draft, or the live version when there is none (what your next change builds on). The `ETag` is `\"v<version>\"`: send it back as `If-Match` (or `baseVersion`) with your change.\n\nScopes: `content:read`.","tags":["Subjects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"`draft` (the default: the pending draft, or the live version when there is none: what your next change builds on), `live`, or a version number.","schema":{"anyOf":[{"type":"string","enum":["live","draft"]},{"type":"string","pattern":"^[1-9]\\d{0,6}$"}]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The content.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"description":"`\"v<version>\"`: the version shown.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SubjectContentVersion"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["content:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"},"patch":{"operationId":"updateSubjectContent","summary":"Change a subject's content (as a draft)","description":"Saves the sections in `set` as a new draft version; what sessions run changes only when it is published (`POST /subjects/{id}/publish`). A list section replaces the whole list (an item without an id gets one); an object section changes only the fields sent (null clears one); `facts` also takes `{ key: value }`. `facts.assistant_name` is always the name of the avatar that speaks, set on each portal with `PUT /portals/{id}/persona`: a changed value is `400 invalid_request` (`param: body.set.facts.assistant_name`). A document read with GET can be sent back as it is. The content's own rules are checked (`400 invalid_request`, `details.errors: [{ path, message }]` in the document's paths), and the plan's features (`403 upgrade_required`). With `If-Match` or `baseVersion`, a newer version is `409 version_conflict` (`details.currentVersion`); without, the change applies to the newest. The answer says whether the draft could go live (`goLive`). Sending the newest content again stores nothing.\n\nScopes: `content:write`.","tags":["Subjects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubjectContentUpdate"}}}},"responses":{"200":{"description":"The draft.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"description":"`\"v<version>\"`: the draft's version.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SubjectContentDraft"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`version_conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["content:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","version_conflict","rate_limited","server_error"],"x-zentiq-events":["subject.draft_saved"],"x-zentiq-since":"2026-07-08"}},"/subjects/{id}/go-live":{"get":{"operationId":"getSubjectGoLive","summary":"Check a subject can go live","description":"Runs the go-live check on a version (by default the pending draft, or the live version): what to finish first, in the content document's fields. Changes nothing.\n\nScopes: `content:read`.","tags":["Subjects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"`draft` (the default: the pending draft, or the live version when there is none: what your next change builds on), `live`, or a version number.","schema":{"anyOf":[{"type":"string","enum":["live","draft"]},{"type":"string","pattern":"^[1-9]\\d{0,6}$"}]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Whether it can go live.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SubjectGoLive"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["content:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/subjects/{id}/versions":{"get":{"operationId":"listSubjectVersions","summary":"List a subject's versions","description":"Every stored version of the subject's content, newest first: which is live, which is the pending draft, and who saved each.\n\nScopes: `content:read`.","tags":["Subjects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of versions.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SubjectVersion"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["content:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-07-08"}},"/subjects/{id}/publish":{"post":{"operationId":"publishSubject","summary":"Publish a subject's content","description":"Makes a version (by default the pending draft) what sessions run, and publishes the subject. It must pass the go-live check (`422 go_live_refused`, `details.problems`), the plan's features (`403 upgrade_required`) and, for a screening role that keeps candidates, the round lock (`409 conflict`, `details.reason: \"round_locked\"`: send `newRound: true` to start a new round). An older version is brought back as the newest. Already live and published: returned unchanged.\n\nScopes: `portals:publish`.","tags":["Subjects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubjectPublish"}}}},"responses":{"200":{"description":"The subject as it now stands.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Subject"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`go_live_refused`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["portals:publish"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","go_live_refused","rate_limited","server_error"],"x-zentiq-events":["workspace.published"],"x-zentiq-since":"2026-07-08"}},"/subjects/{id}/translate-questions":{"post":{"operationId":"translateSubjectQuestions","summary":"Translate a subject's questions (as a draft)","description":"Translates what is said of each question (the question, its options, follow-ups and complication) into `language` and saves it as a new draft, for you to check and publish (`POST /subjects/{id}/publish`); the guides for marking stay as written. A screening interview, an exam or an assessment asks each question word for word, so everyone is asked the same: translate once, here, rather than in each session. All or nothing: when a question can't be translated well enough (its numbers, its options and follow-ups kept), nothing is saved (`503`, try again). An unknown language, English, or a subject without questions is `400 invalid_request`.\n\nScopes: `content:write`.","tags":["Subjects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubjectQuestionsTranslate"}}}},"responses":{"200":{"description":"The draft with the translated questions.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/SubjectQuestionsTranslated"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`version_conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["content:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","version_conflict","rate_limited","server_error"],"x-zentiq-events":["subject.draft_saved"],"x-zentiq-since":"2026-07-08"}},"/results/{id}":{"get":{"operationId":"getResult","summary":"Get a result","description":"Numbers follow the released rule: nothing while a reviewer still decides a scored attempt or the organisation shares results through a person only, nothing for a void, the reviewer's decision once decided. A practice attempt is the person's own and is never listed; a candidate's interview or any other job interview isn't a result here.\n\nScopes: `results:read`.","tags":["Results"],"parameters":[{"name":"id","in":"path","required":true,"description":"Result id (`res_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The result.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Result"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["results:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/results/{id}/report":{"get":{"operationId":"getResultReport","summary":"A result's written report","description":"The report's words: its summary, strengths, what to work on and the next step. Only where the conversation itself may be read (never a young learner's, nor a website visitor's who said they are under 18: `403 learner_conversation`), once the result is released; a subject that keeps nothing has no words.\n\nScopes: `results:read`, `transcripts:read`.","tags":["Results"],"parameters":[{"name":"id","in":"path","required":true,"description":"Result id (`res_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The report's words.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/ResultReport"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required`, `candidate_interview`, `learner_conversation` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["results:read","transcripts:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","candidate_interview","learner_conversation","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01","x-zentiq-stability":"beta"}},"/results":{"get":{"operationId":"listResults","summary":"List results","description":"Newest first. Numbers follow the released rule: nothing while a reviewer still decides a scored attempt or the organisation shares results through a person only, nothing for a void, the reviewer's decision once decided. A practice attempt is the person's own and is never listed; a candidate's interview or any other job interview isn't a result here. `updatedAfter` lists what changed since (a review, a certificate, a completion): for syncing.\n\nScopes: `results:read`.","tags":["Results"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,}$"}},{"name":"portalId","in":"query","required":false,"description":"Portal id (`portal_…`).","schema":{"type":"string"}},{"name":"subjectId","in":"query","required":false,"description":"Subject id (`sub_…`).","schema":{"type":"string"}},{"name":"unitId","in":"query","required":false,"description":"Unit id (`unit_…`).","schema":{"type":"string"}},{"name":"personId","in":"query","required":false,"description":"Person id (`usr_…`).","schema":{"type":"string"}},{"name":"externalUserId","in":"query","required":false,"description":"The person you know by this id (needs `people:read`).","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"release","in":"query","required":false,"schema":{"type":"string","enum":["not_scored","awaiting_review","reviewers_only","voided","released"]}},{"name":"passed","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"from","in":"query","required":false,"description":"Reported at or after.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Reported before.","schema":{"type":"string"}},{"name":"updatedAfter","in":"query","required":false,"description":"Changed since (a report, a review, a contest, a certificate, a completion): for syncing.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of results.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Result"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["results:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/people/{id}/memberships":{"post":{"operationId":"addMembership","summary":"Give a person another place","description":"A role at a unit, or at the organisation level. The same place again is returned as it is (200). `ageBand: \"18+\"` marks an adult learner, where the organisation marks adult learners (`409 conflict` otherwise). The API never gives, changes, switches off or removes an owner's place, and only a full-access key gives, changes, switches off or removes an ADMIN, AVATAR_BUILDER or WORKSPACE_ADMIN place (`403 forbidden` otherwise): `people:write` alone manages learners, leaders and observers.\n\nScopes: `people:write`.","tags":["People"],"parameters":[{"name":"id","in":"path","required":true,"description":"Person id (`usr_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddMembershipInput"}}}},"responses":{"201":{"description":"The place.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Membership"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"natural","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-events":["member.added"],"x-zentiq-since":"2026-10-01"}},"/people":{"get":{"operationId":"listPeople","summary":"List people","description":"Everyone in the organisation (members, learners, parents) with their places here, newest first. `updatedAfter` lists those whose account or places changed since: for keeping your system in step.\n\nScopes: `people:read`.","tags":["People"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"unitId","in":"query","required":false,"description":"People with a place at this unit.","schema":{"type":"string"}},{"name":"subtree","in":"query","required":false,"description":"With unitId: the unit and every unit below it.","schema":{"type":"string","enum":["true","false"]}},{"name":"role","in":"query","required":false,"description":"People holding this role here.","schema":{"type":"string","enum":["OWNER","ADMIN","AVATAR_BUILDER","WORKSPACE_ADMIN","LEADER","LEARNER","OBSERVER"]}},{"name":"status","in":"query","required":false,"description":"People with a place in this status.","schema":{"type":"string","enum":["active","waiting_consent","disabled"]}},{"name":"externalId","in":"query","required":false,"description":"The person you know by this id.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"email","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":200}},{"name":"updatedAfter","in":"query","required":false,"description":"Changed since (the account or one of its places): for syncing.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of people.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Person"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"post":{"operationId":"createPerson","summary":"Add a person (or find them) and give them a place","description":"By `externalId` (your own id, the sync key: a repeat returns the same person, `200`), else by email, else a login card for a learner without an email. A new learner's place waits for a parent's consent where the organisation's rules say so (`status: waiting_consent`); never an adult learner's (`ageBand: \"18+\"`, where the organisation marks adult learners). A new login card's PIN is in this answer only (`Cache-Control: no-store`): a retry never gets it again. No email is sent. The API never gives, changes, switches off or removes an owner's place, and only a full-access key gives, changes, switches off or removes an ADMIN, AVATAR_BUILDER or WORKSPACE_ADMIN place (`403 forbidden` otherwise): `people:write` alone manages learners, leaders and observers.\n\nScopes: `people:write`.","tags":["People"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonInput"}}}},"responses":{"201":{"description":"The person (201 when a person or a place was made, 200 when both existed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Cache-Control":{"description":"no-store","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/PersonCreated"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"natural","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-events":["member.added"],"x-zentiq-since":"2026-10-01"}},"/units":{"get":{"operationId":"listUnits","summary":"List units","description":"The organisation's classes, teams and groups, in tree order, with their counts.\n\nScopes: `people:read`.","tags":["People"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"parentId","in":"query","required":false,"description":"Only the units directly under this one.","schema":{"type":"string"}},{"name":"includeDisabled","in":"query","required":false,"description":"Include switched-off units (default true).","schema":{"type":"string","enum":["true","false"]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of units.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"post":{"operationId":"createUnit","summary":"Add a unit (a class, team or group)","description":"Under another unit (`parentId`) or at the top level. A second unit with the same name at the same level is allowed and flagged (`duplicateName`). A leader named by email is invited and takes a staff seat (`403 upgrade_required` when they are all in use).\n\nScopes: `people:write`.","tags":["People"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUnitInput"}}}},"responses":{"201":{"description":"The new unit.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/UnitWritten"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-events":["unit.created","member.added"],"x-zentiq-since":"2026-10-01"}},"/memberships/{id}":{"patch":{"operationId":"updateMembership","summary":"Change a place","description":"Its role, unit, year or grade, whether it is an adult learner's, or switch it off or on. A place waiting for a parent's consent turns active only through guardian consent, or when it is marked as an adult learner's (`ageBand: \"18+\"`, where the organisation marks adult learners: `409 conflict` otherwise). The API never gives, changes, switches off or removes an owner's place, and only a full-access key gives, changes, switches off or removes an ADMIN, AVATAR_BUILDER or WORKSPACE_ADMIN place (`403 forbidden` otherwise): `people:write` alone manages learners, leaders and observers.\n\nScopes: `people:write`.","tags":["People"],"parameters":[{"name":"id","in":"path","required":true,"description":"Membership id (`mbr_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMembershipInput"}}}},"responses":{"200":{"description":"The place.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Membership"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-events":["member.updated","member.disabled","member.enabled"],"x-zentiq-since":"2026-10-01"},"delete":{"operationId":"deleteMembership","summary":"Remove a place","description":"The account stays. Someone's only organisation-level owner or admin place can't be removed this way, nor the last place of an owner or admin invited in the console (`409 conflict`: without a place their account would count as an owner; an owner or admin removes them from the organisation in the console). The API never gives, changes, switches off or removes an owner's place, and only a full-access key gives, changes, switches off or removes an ADMIN, AVATAR_BUILDER or WORKSPACE_ADMIN place (`403 forbidden` otherwise): `people:write` alone manages learners, leaders and observers.\n\nScopes: `people:write`.","tags":["People"],"parameters":[{"name":"id","in":"path","required":true,"description":"Membership id (`mbr_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"Removed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"object","properties":{"removed":{"type":"boolean","const":true},"id":{"type":"string","minLength":1,"pattern":"^mbr_.*","description":"Membership id (`mbr_…`).","examples":["mbr_cmfq2b7x10000abcd1234"]}},"required":["removed","id"]},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-events":["member.removed"],"x-zentiq-since":"2026-10-01"}},"/people/{id}":{"get":{"operationId":"getPerson","summary":"Get a person","description":"Scopes: `people:read`.","tags":["People"],"parameters":[{"name":"id","in":"path","required":true,"description":"Person id (`usr_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The person.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Person"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/units/{id}":{"get":{"operationId":"getUnit","summary":"Get a unit","description":"Scopes: `people:read`.","tags":["People"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unit id (`unit_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The unit.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Unit"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"patch":{"operationId":"updateUnit","summary":"Rename, move or switch off a unit","description":"Switching a unit off switches off everything below it: nothing is deleted, and it grants nothing until switched on. A unit can't move under itself.\n\nScopes: `people:write`.","tags":["People"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unit id (`unit_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUnitInput"}}}},"responses":{"200":{"description":"The unit.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/UnitWritten"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-events":["unit.renamed","unit.updated","unit.disabled","unit.enabled"],"x-zentiq-since":"2026-10-01"}},"/memberships/{id}/guardian-consent":{"post":{"operationId":"recordGuardianConsent","summary":"Record a parent's or guardian's consent","description":"On a learner's place that waits for it: the place turns active. A place that already has consent is returned as it is; a place switched off is refused (`409`). `consent.recorded` says who gave it, never the guardian's address.\n\nScopes: `people:write`.","tags":["People"],"parameters":[{"name":"id","in":"path","required":true,"description":"Membership id (`mbr_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuardianConsentInput"}}}},"responses":{"200":{"description":"The place.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Membership"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["people:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"natural","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-events":["consent.recorded"],"x-zentiq-since":"2026-10-01"}},"/invites/{id}":{"get":{"operationId":"getInvite","summary":"Get an invite","description":"One invite, its status now and its link while it can be used.\n\nScopes: `candidates:read`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Invite id (`inv_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The invite.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Invite"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"delete":{"operationId":"cancelInvite","summary":"Cancel an invite","description":"Withdraws a waiting invite (invited or opened): its link stops working and nothing is sent to the candidate. Records `candidate.invite_cancelled` (reason `withdrawn_by_team`).\n\nScopes: `candidates:write`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Invite id (`inv_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The invite, cancelled.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Invite"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-events":["candidate.invite_cancelled"],"x-zentiq-since":"2026-10-01"}},"/roles/{id}/invites":{"get":{"operationId":"listInvites","summary":"List a role's invites","description":"The role's invites, newest first, each with its status now and its link while it can be used.\n\nScopes: `candidates:read`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"status","in":"query","required":false,"description":"invited, opened, started, completed, cancelled or expired (comma-separated).","schema":{"type":"string"}},{"name":"externalId","in":"query","required":false,"description":"Only the invites your ATS gave this id.","schema":{"type":"string","pattern":"^[^\\s@]{1,200}$"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of invites.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invite"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"post":{"operationId":"createInvites","summary":"Invite candidates to a role","description":"Personal links to the role's first-round interview, from your ATS with its own ids (`externalId`, `metadata`). The role must be published and pass the go-live check. At most 200 candidates (100 when Zentiq emails them); an address with an open invite for the role, one that completed its interview within the role's retention, or one listed twice is skipped with the reason. The links open the role's portal door. Records `candidate.invited` per invite.\n\nScopes: `candidates:write`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvitesInput"}}}},"responses":{"201":{"description":"The invites made, each with its link, and those skipped.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CreatedInvites"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:write"],"x-zentiq-rate-class":"heavy","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-events":["candidate.invited"],"x-zentiq-since":"2026-10-01"}},"/candidates/{id}/decision":{"post":{"operationId":"decideCandidate","summary":"Record a person's decision","description":"The hiring team's decision on one candidate, made by the member named in `decidedBy` and carried by the key. A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically. The member's own hiring access applies; the reviews the role asks for come first (a decline waits for at least one); a decline needs the member to have opened the candidate's interview or added their own review in Zentiq (`409`, `details.reason: needs_open`); an erased candidate can't be decided; the same decision and reason again changes nothing. There is no bulk decline. Records `candidate.decided` (the decision and reason code only).\n\nScopes: `candidates:write`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Candidate id (`cand_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateDecisionInput"}}}},"responses":{"200":{"description":"The candidate with the decision recorded.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CandidateWithHistory"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`, `idempotency_conflict`, `idempotency_in_progress`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:write"],"x-zentiq-rate-class":"write","x-zentiq-idempotent":"replay","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","idempotency_conflict","idempotency_in_progress","rate_limited","server_error"],"x-zentiq-events":["candidate.decided"],"x-zentiq-since":"2026-10-01"}},"/candidates/{id}":{"get":{"operationId":"getCandidate","summary":"Get a candidate","description":"One candidate with their decision history. Never their answers, a summary, notes, review reasons, integrity flags or recordings here: a hiring system reads the interview itself with GET /candidates/{id}/interview (a key an owner or admin gave interview content, every read logged). Reading it here does not count as opening their interview. A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically.\n\nScopes: `candidates:read`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Candidate id (`cand_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The candidate.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CandidateWithHistory"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/candidates/{id}/compliance":{"get":{"operationId":"getCandidateCompliance","summary":"Get a candidate's US hiring record","description":"The US hiring pack (switch `hiring.us_compliance`, off by default; on Pro and up): the rules the pack applies to the candidate's role now, the notices the candidate read before the interview (kind, version and a fingerprint of the exact text) with when they agreed, their separate consent for Illinois, how New York City's notice reached them in time, and their requests. `consent` is null for an interview started before the pack was on. Never a candidate's message, an open-door request's contact details, a legal hold's reason or any demographic answer. Zentiq gives no legal advice.\n\nScopes: `candidates:read`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Candidate id (`cand_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The candidate's record.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CandidateCompliance"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/candidates/{id}/interview":{"get":{"operationId":"getCandidateInterview","summary":"Get a candidate's interview","description":"The interview for your hiring system: each must-have and interview question with the candidate's answer and what the platform found in it (verdict, marks, a note), the written summary, strengths and concerns, the evidence it quotes, the transcript (the AI interviewer and the candidate, turn by turn), whether they asked for an adjustment (never which one), their request for a review, the reviews as a reviewer who hasn't added one sees them (blind review hides them), and when it happened. A candidate under 18 or anything that is not a candidate's interview is `404`; an erased candidate, a deleted interview and one the candidate ended themselves are `410 gone` (`details.reason`: erased, deleted, withdrawn). Numbers (score, band, rank, marks, verdicts, competency scores, reviewers' ratings) are given only where the role shares scores (switch candidates.share_scores, off by default); otherwise they are null and `scoresShared` is false. Only with a key an owner or admin made in Zentiq with \"Interview content (hiring)\" ticked (`candidates:interviews`, which a key never passes on and a connected app or assistant never holds). Every read is logged on the candidate as opened by the API key, and the hiring team sees it in the candidate's history. It never counts as a person having opened the interview: a decline still needs one. Never: reviewers' or deciders' notes, the details of integrity moments or of the report's flags (their counts only), the recording (whether there is one only). A candidate under 18, a practice or mock interview and a builder's preview are never served. The practice question is never in the transcript. Webhooks carry no words: on `candidate.screened`, fetch the interview here. A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically.\n\nScopes: `candidates:read`, `candidates:interviews`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Candidate id (`cand_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The interview (the read is logged).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/CandidateInterview"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`gone`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`upstream_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read","candidates:interviews"],"x-zentiq-rate-class":"heavy","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","gone","rate_limited","server_error","upstream_error"],"x-zentiq-since":"2026-10-01","x-mcp-exclude":true}},"/roles/{id}/candidates":{"get":{"operationId":"listCandidates","summary":"List a role's candidates","description":"Everyone who took the role's interview. Where the role shares scores (switch `candidates.share_scores`, off by default), each carries `score`, `band` and `rank` and `sort=rank` puts the highest score first; otherwise those are null and the list sorts by interview date. Never answers, summaries, notes, review reasons, integrity flags, recordings or an adjustment's kind here: a hiring system reads those with GET /roles/{id}/interviews (a key an owner or admin gave interview content). A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically.\n\nScopes: `candidates:read`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"band","in":"query","required":false,"description":"Only where the role shares scores (candidates.share_scores).","schema":{"type":"string"}},{"name":"decision","in":"query","required":false,"description":"awaiting (no decision yet), invite, hold or decline.","schema":{"type":"string"}},{"name":"mustHaves","in":"query","required":false,"description":"One or more of met, missed, unclear, none, comma-separated.","schema":{"type":"string"}},{"name":"round","in":"query","required":false,"description":"latest, all (the default) or a round number: scores compare only within a round.","schema":{"type":"string","pattern":"^(latest|all|[1-9]\\d{0,3})$"}},{"name":"interviewedAfter","in":"query","required":false,"description":"ISO 8601 date and time.","schema":{"type":"string"}},{"name":"updatedAfter","in":"query","required":false,"description":"Only candidates with anything new since (a decision, a review, an erasure): for syncing.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"rank (best score first; only where the role shares scores, else by interview date), interviewed or name.","schema":{"type":"string","enum":["rank","interviewed","name"]}},{"name":"order","in":"query","required":false,"description":"rank: asc (1 first, the default); interviewed: desc (newest first, the default); name: asc.","schema":{"type":"string","enum":["asc","desc"]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of candidates.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/roles/{id}/interviews":{"get":{"operationId":"listRoleInterviews","summary":"List a role's interviews","description":"The role's interviews, oldest first by when each reached the hiring team, for syncing your hiring system: `since` gives only those after a moment, and `nextCursor` goes on from the last page. Each item is the whole interview, as GET /candidates/{id}/interview gives it. Erased and withdrawn candidates are never listed, and an interview that is never served is left out, so a page can hold fewer than `limit` and still have a `nextCursor`. Numbers (score, band, rank, marks, verdicts, competency scores, reviewers' ratings) are given only where the role shares scores (switch candidates.share_scores, off by default); otherwise they are null and `scoresShared` is false. Only with a key an owner or admin made in Zentiq with \"Interview content (hiring)\" ticked (`candidates:interviews`, which a key never passes on and a connected app or assistant never holds). Every read is logged on the candidate as opened by the API key, and the hiring team sees it in the candidate's history. It never counts as a person having opened the interview: a decline still needs one. Never: reviewers' or deciders' notes, the details of integrity moments or of the report's flags (their counts only), the recording (whether there is one only). A candidate under 18, a practice or mock interview and a builder's preview are never served. The practice question is never in the transcript. Webhooks carry no words: on `candidate.screened`, fetch the interview here. A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically.\n\nScopes: `candidates:read`, `candidates:interviews`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-50 (default 20): each item is a whole interview.","schema":{"type":"integer","minimum":1,"maximum":50,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"since","in":"query","required":false,"description":"Only interviews that reached the hiring team after this moment (ISO 8601): for syncing. Oldest first.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of interviews (each read is logged).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CandidateInterview"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`upstream_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read","candidates:interviews"],"x-zentiq-rate-class":"heavy","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error","upstream_error"],"x-zentiq-since":"2026-10-01","x-mcp-exclude":true}},"/roles/{id}/requests":{"get":{"operationId":"listRoleRequests","summary":"List a role's candidate requests","description":"The US hiring pack (switch `hiring.us_compliance`, off by default; on Pro and up): candidates' requests for a role under Illinois', New York City's or Colorado's rules, newest first, each with its due date and outcome: deletion (their interview, any recording and every copy; due in 30 days, carried out automatically on day 30 where the role says so, paused while a legal hold is on), alternative (another way to be assessed, or an accommodation; 14 days), review and correction (30 days). The hiring team answers them in Zentiq. Never a candidate's message, an open-door request's contact details, a legal hold's reason or any demographic answer. Zentiq gives no legal advice.\n\nScopes: `candidates:read`.","tags":["Hiring"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subject id (`sub_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"status","in":"query","required":false,"description":"open, paused (a legal hold keeps the interview) or done (comma-separated).","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"deletion, alternative, review or correction (comma-separated).","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of requests.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CandidateRequest"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/roles":{"get":{"operationId":"listRoles","summary":"List screening roles","description":"The organisation's screening roles (subjects candidates are interviewed on), newest first, with their doors, review settings and whether they share scores.\n\nScopes: `candidates:read`.","tags":["Hiring"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"portalId","in":"query","required":false,"description":"Only the roles on this portal.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"draft, published or archived (comma-separated).","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of roles.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["candidates:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/inbox/items/{id}":{"get":{"operationId":"getInboxItem","summary":"Get an inbox item","description":"One lead, booking request or hand-off with the visitor's contact details. The visitor's own words (need, budget, timeline, the summary, a hand-off's reason, a lead's answers) come only to a key holding `transcripts:read`, and never from an under-18's, a candidate's or a safety-flagged conversation.\n\nScopes: `inbox:read`.","tags":["Inbox"],"parameters":[{"name":"id","in":"path","required":true,"description":"Inbox item id (`inb_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The item.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/InboxItem"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["inbox:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"},"patch":{"operationId":"updateInboxItem","summary":"Move an inbox item on","description":"Sets its status (new, contacted, confirmed, closed; any to any) with an optional note. With `expectedStatus`, nothing changes when someone moved it meanwhile (409). Records `lead.updated` (or `booking.updated` for a booking) with `by` = this key, so your sync can ignore its own changes. The same status again without a note changes nothing. The visitor's contact details, booking and consent come back only to a key that also holds `inbox:read` (else null).\n\nScopes: `inbox:write`.","tags":["Inbox"],"parameters":[{"name":"id","in":"path","required":true,"description":"Inbox item id (`inb_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ZentiqVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxItemUpdate"}}}},"responses":{"200":{"description":"The item as it is now.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/InboxItem"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["inbox:write"],"x-zentiq-rate-class":"write","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","conflict","rate_limited","server_error"],"x-zentiq-events":["lead.updated","booking.updated"],"x-zentiq-since":"2026-10-01"}},"/inbox/items":{"get":{"operationId":"listInboxItems","summary":"List the inbox","description":"Website visitors' leads, booking requests and hand-offs, one item per conversation, newest first (or `order=asc`), placed by the conversation's first request. For syncing a CRM: `updatedAfter` with `order=asc`, then follow `nextCursor`. A filtered page may hold fewer than `limit` items and still have a `nextCursor`. The visitor's own words (need, budget, timeline, the summary, a hand-off's reason, a lead's answers) come only to a key holding `transcripts:read`, and never from an under-18's, a candidate's or a safety-flagged conversation.\n\nScopes: `inbox:read`.","tags":["Inbox"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"portalId","in":"query","required":false,"description":"Only the requests behind this portal's subjects.","schema":{"type":"string"}},{"name":"subjectId","in":"query","required":false,"description":"Subject id (`sub_…`).","schema":{"type":"string"}},{"name":"personaId","in":"query","required":false,"description":"Only the requests behind this persona's portals (its website widget's).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"new, contacted, confirmed or closed (comma-separated).","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"lead, booking or handoff (comma-separated): items with any of them.","schema":{"type":"string"}},{"name":"overdue","in":"query","required":false,"description":"true: still new past what the visitor was promised (or 24 hours).","schema":{"type":"string","enum":["true","false"]}},{"name":"createdAfter","in":"query","required":false,"description":"Items whose first request came in at or after this moment.","schema":{"type":"string"}},{"name":"createdBefore","in":"query","required":false,"description":"ISO 8601 date and time.","schema":{"type":"string"}},{"name":"updatedAfter","in":"query","required":false,"description":"Items with anything new since (a request, a status change, a detail removed): for syncing, with `order=asc`.","schema":{"type":"string"}},{"name":"order","in":"query","required":false,"description":"desc (newest first, the default) or asc, by when the item's first request came in.","schema":{"type":"string","enum":["asc","desc"]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of items.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxItem"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["inbox:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/events/{id}":{"get":{"operationId":"getEvent","summary":"Get an event","description":"One event as a webhook with this key's rights receives it. Each kind of event also needs the scope that reads its records (see `GET /events`); otherwise it is `404`. `?includeConversation=true` needs `transcripts:read`.\n\nScopes: `events:read`.","tags":["Events"],"parameters":[{"name":"id","in":"path","required":true,"description":"Event id (`evt_…`); the id without its prefix is accepted too.","schema":{"type":"string"}},{"name":"includeConversation","in":"query","required":false,"description":"Include conversation fields where Zentiq's privacy rules allow them, as a webhook with includeConversation would get them. Needs `transcripts:read`.","schema":{"type":"string","enum":["true","false"]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The event.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/Event"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["events:read"],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","not_found","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/event-types":{"get":{"operationId":"listEventTypes","summary":"The event catalogue","description":"Every event type a webhook can receive: what it says, its fields by class and its data's JSON Schema. Safety flags are never sent.\n\nAny valid key.","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"The catalogue.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventType"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-rate-class":"read","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/events":{"get":{"operationId":"listEvents","summary":"The event log","description":"Every event offered to webhooks, as a webhook with this key's rights receives it (the same `id` and `data`): for reconciling after an outage and for syncing (`after` and `order=asc`). Each kind of event is listed only for a key that also holds the scope reading its records: sessions, practice, sign-ins and ratings `sessions:read`; `transcript.final` and `session.transcript_ready` `transcripts:read`; reports, scores, reviews, certificates and completions `results:read`; assigned work `assignments:read`; `candidate.*` `candidates:read`; leads, bookings, hand-offs, forgotten details and knowledge gaps `inbox:read` (with the visitor's contact details); members, units and consent `people:read`; portals, subjects and jobs `portals:read`; the widget `widgets:read`; switches `settings:read`; knowledge documents `knowledge:read`; voices `voices:read`; usage `usage:read`; webhook tests `webhooks:manage`; connected systems `connections:write`. Conversation fields only with `?includeConversation=true`, which needs `transcripts:read`, and only where the rules allow them. An event this key's webhooks would never receive is left out, so a page can hold fewer than `limit` and still have a `nextCursor`.\n\nScopes: `events:read`.","tags":["Events"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}},{"name":"type","in":"query","required":false,"description":"One or more event types, comma-separated.","schema":{"type":"string"}},{"name":"after","in":"query","required":false,"description":"Only events after this one (for syncing: use with order=asc).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Events at or after this moment.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Events before this moment.","schema":{"type":"string"}},{"name":"sessionId","in":"query","required":false,"description":"Session id (`sess_…`).","schema":{"type":"string"}},{"name":"subjectId","in":"query","required":false,"description":"Subject id (`sub_…`).","schema":{"type":"string"}},{"name":"order","in":"query","required":false,"description":"desc (newest first, the default) or asc (for syncing).","schema":{"type":"string","enum":["asc","desc"]}},{"name":"includeConversation","in":"query","required":false,"description":"Include conversation fields where Zentiq's privacy rules allow them, as a webhook with includeConversation would get them. Needs `transcripts:read`.","schema":{"type":"string","enum":["true","false"]}},{"$ref":"#/components/parameters/ZentiqVersion"}],"responses":{"200":{"description":"A page of events.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`, `upgrade_required` (a plan refusal is an UpgradeRequired body for keys on 2026-07-08)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UpgradeRequired"}]}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":["events:read"],"x-zentiq-rate-class":"search","x-zentiq-errors":["invalid_request","unauthorized","forbidden","upgrade_required","rate_limited","server_error"],"x-zentiq-since":"2026-10-01"}},"/agents/{org}/{door}/ask":{"post":{"operationId":"askAgentDoor","summary":"Ask a business's website assistant a question","description":"For AI assistants and search tools, with no key: one question to a business's public website assistant, answered in writing from what the business has told it, with the same rules as a typed conversation on its page. Only for a public page whose business opted it in (its agent card is at `/v/{org}/{door}/agent-card.json`, its llms.txt at `/v/{org}/llms.txt`); any other address is `404 not_found`. Nothing is stored and no details are taken: a person is pointed to `url` to talk, book or reach the team. The question and the answer have email addresses, phone numbers and payment or identity numbers removed, and the answer is marked `aiGenerated`. Limited per caller and per page (`429 rate_limited` with `Retry-After`); `503 capacity` when no answer could be written just then.","tags":["Agents"],"security":[],"parameters":[{"name":"org","in":"path","required":true,"description":"The name in the assistant's public page address: https://app.zentiqai.com/v/{org}/{door}.","schema":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$","examples":["acme"]}},{"name":"door","in":"path","required":true,"description":"The name in the assistant's public page address: https://app.zentiqai.com/v/{org}/{door}.","schema":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$","examples":["acme"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAskInput"}}}},"responses":{"200":{"description":"The answer.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"type":"object","required":["data","error","requestId"],"properties":{"data":{"$ref":"#/components/schemas/AgentAnswer"},"error":{"type":"null"},"requestId":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}}}}}},"400":{"description":"`invalid_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`capacity`","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Zentiq-Version":{"$ref":"#/components/headers/Zentiq-Version"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-zentiq-scopes":[],"x-zentiq-rate-class":"none","x-zentiq-errors":["invalid_request","not_found","rate_limited","server_error","capacity"],"x-zentiq-since":"2026-10-01","x-mcp-exclude":true}}},"webhooks":{"assessment.completed":{"post":{"summary":"A scored attempt completed; the final result once a person has decided it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"assessment.completed"},"data":{"$ref":"#/components/schemas/AssessmentCompletedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"assignment.completed":{"post":{"summary":"A person completed assigned work.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"assignment.completed"},"data":{"$ref":"#/components/schemas/AssignmentCompletedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"assignment.created":{"post":{"summary":"Work was assigned.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"assignment.created"},"data":{"$ref":"#/components/schemas/AssignmentCreatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"assignment.started":{"post":{"summary":"A person started assigned work.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"assignment.started"},"data":{"$ref":"#/components/schemas/AssignmentStartedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"attempt.granted":{"post":{"summary":"A person was given one more scored attempt.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"attempt.granted"},"data":{"$ref":"#/components/schemas/AttemptGrantedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"attestation.recorded":{"post":{"summary":"A person confirmed an attestation before a completion.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"attestation.recorded"},"data":{"$ref":"#/components/schemas/AttestationRecordedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"booking.requested":{"post":{"summary":"A website visitor asked for a booking: contact details, the service and time asked for, and their consent.","description":"Carries the visitor's contact details (only on leads, bookings and hand-offs). Conversation fields (summary, need, budget, timeline) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"booking.requested"},"data":{"$ref":"#/components/schemas/BookingRequestedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"booking.updated":{"post":{"summary":"A booking request moved on in the inbox (its status, and who moved it).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"booking.updated"},"data":{"$ref":"#/components/schemas/InboxMoveData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.decided":{"post":{"summary":"The hiring team decided on a candidate (the decision and a reason code).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.decided"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.erased":{"post":{"summary":"A candidate's data was erased.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.erased"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.interview_booked":{"post":{"summary":"A candidate booked a human interview.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.interview_booked"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.interview_cancelled":{"post":{"summary":"A human interview was cancelled.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.interview_cancelled"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.interview_offered":{"post":{"summary":"A candidate was offered times for a human interview.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.interview_offered"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.invite_cancelled":{"post":{"summary":"A candidate's invite was cancelled (a reason code).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.invite_cancelled"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.invite_expired":{"post":{"summary":"A candidate's invite expired unused.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.invite_expired"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"candidate.invite_opened":{"post":{"summary":"A candidate opened their invite.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.invite_opened"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"candidate.invited":{"post":{"summary":"A candidate was invited (or invited again: resent).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.invited"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.reviewed":{"post":{"summary":"One person on the hiring team reviewed a candidate (their recommendation, never ratings or notes).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.reviewed"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"candidate.screened":{"post":{"summary":"A candidate's first-round interview was screened (ids and status only; scores never by webhook).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"candidate.screened"},"data":{"$ref":"#/components/schemas/CandidateWebhookData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"case_link.opened":{"post":{"summary":"A customer started a conversation from a case link you sent them (the link, your reference and customer id, the opens so far). The case summary only with includeConversation.","description":"Conversation fields (summary) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"case_link.opened"},"data":{"$ref":"#/components/schemas/CaseLinkOpenedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"certificate.expired":{"post":{"summary":"A certificate is past its valid-until date.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"certificate.expired"},"data":{"$ref":"#/components/schemas/CertificateNoticeData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"certificate.expiring":{"post":{"summary":"A certificate is close to its valid-until date.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"certificate.expiring"},"data":{"$ref":"#/components/schemas/CertificateNoticeData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"certificate.issued":{"post":{"summary":"A certificate was issued (its number, never the holder's name).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"certificate.issued"},"data":{"$ref":"#/components/schemas/CertificateIssuedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"certificate.revoked":{"post":{"summary":"A certificate was withdrawn (a fixed reason).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"certificate.revoked"},"data":{"$ref":"#/components/schemas/CertificateRevokedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"completion.recorded":{"post":{"summary":"A completion record was written for a confirmed pass.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"completion.recorded"},"data":{"$ref":"#/components/schemas/CompletionRecordedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"completion.withdrawn":{"post":{"summary":"A completion was withdrawn (a fixed reason).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"completion.withdrawn"},"data":{"$ref":"#/components/schemas/CompletionWithdrawnData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"connection.failed":{"post":{"summary":"One of your connected systems started failing (its id, kind, an error code and the HTTP status): its actions tell visitors they can't do that just now. Never its key or anything it sent back.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"connection.failed"},"data":{"$ref":"#/components/schemas/ConnectionFailedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"consent.recorded":{"post":{"summary":"Consent was recorded for a membership (who recorded it, never their address).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"consent.recorded"},"data":{"$ref":"#/components/schemas/ConsentRecordedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"conversation.rated":{"post":{"summary":"A visitor rated a conversation (the comment only with includeConversation). Never a candidate's.","description":"Conversation fields (comment) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"conversation.rated"},"data":{"$ref":"#/components/schemas/ConversationRatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"escalation.completed":{"post":{"summary":"A conversation your text chat handed to the video avatar ended: where it came from, your chat tool's ids, how long and the outcome. The summary only with includeConversation, where allowed.","description":"Conversation fields (summary) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"escalation.completed"},"data":{"$ref":"#/components/schemas/EscalationCompletedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"handoff.joined":{"post":{"summary":"Someone from your team joined a website visitor's live conversation as themselves (their user id, how they joined).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"handoff.joined"},"data":{"$ref":"#/components/schemas/HandoffJoinedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"handoff.left":{"post":{"summary":"Someone from your team left a website visitor's live conversation: how long they were in it, and whether the assistant carried on or the conversation ended.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"handoff.left"},"data":{"$ref":"#/components/schemas/HandoffLeftData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"handoff.requested":{"post":{"summary":"A website visitor asked for a person: their contact details, what they need and their consent. The summary and reason only with includeConversation.","description":"Carries the visitor's contact details (only on leads, bookings and hand-offs). Conversation fields (summary, need, budget, timeline, reason) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"handoff.requested"},"data":{"$ref":"#/components/schemas/HandoffRequestedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"handoff.updated":{"post":{"summary":"A website visitor's request for a person gained their contact details after it was sent (they agreed and said how to reach them later in the conversation): the same fields as handoff.requested, with the same reference.","description":"Carries the visitor's contact details (only on leads, bookings and hand-offs). Conversation fields (summary, need, budget, timeline, reason) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"handoff.updated"},"data":{"$ref":"#/components/schemas/HandoffUpdatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"job.completed":{"post":{"summary":"A long-running job finished (the drafts it wrote, by id).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"job.completed"},"data":{"$ref":"#/components/schemas/JobCompletedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"knowledge.document.failed":{"post":{"summary":"A knowledge document could not be read; errorCode says why.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"knowledge.document.failed"},"data":{"$ref":"#/components/schemas/KnowledgeDocumentFailedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"knowledge.document.processed":{"post":{"summary":"A knowledge document was read and is ready.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"knowledge.document.processed"},"data":{"$ref":"#/components/schemas/KnowledgeDocumentProcessedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"knowledge.gap":{"post":{"summary":"The assistant couldn't answer some questions (the questions only with includeConversation).","description":"Conversation fields (questions) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"knowledge.gap"},"data":{"$ref":"#/components/schemas/KnowledgeGapData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"lead.captured":{"post":{"summary":"A website visitor left their details as a lead: contact details, the lead's band and their consent. The summary only with includeConversation.","description":"Carries the visitor's contact details (only on leads, bookings and hand-offs). Conversation fields (summary, need, budget, timeline, answers) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"lead.captured"},"data":{"$ref":"#/components/schemas/LeadCapturedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"lead.updated":{"post":{"summary":"A lead moved on in the inbox (its status, and who moved it).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"lead.updated"},"data":{"$ref":"#/components/schemas/InboxMoveData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"learner.signed_in":{"post":{"summary":"A learner signed in to a portal.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"learner.signed_in"},"data":{"$ref":"#/components/schemas/LearnerSignedInData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"mastery.updated":{"post":{"summary":"A person's level on a skill moved.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"mastery.updated"},"data":{"$ref":"#/components/schemas/MasteryUpdatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"member.added":{"post":{"summary":"Someone was added to the organisation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"member.added"},"data":{"$ref":"#/components/schemas/MemberAddedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"member.disabled":{"post":{"summary":"A member (or one of their places) was switched off.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"member.disabled"},"data":{"$ref":"#/components/schemas/MemberStateData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"member.enabled":{"post":{"summary":"A member (or one of their places) was switched on again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"member.enabled"},"data":{"$ref":"#/components/schemas/MemberStateData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"member.removed":{"post":{"summary":"Someone was removed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"member.removed"},"data":{"$ref":"#/components/schemas/MemberRemovedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"member.updated":{"post":{"summary":"A member's role or unit changed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"member.updated"},"data":{"$ref":"#/components/schemas/MemberUpdatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"memory.written":{"post":{"summary":"The platform noted something for a person's next session (what kind, never the note).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"memory.written"},"data":{"$ref":"#/components/schemas/MemoryWrittenData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"portal.created":{"post":{"summary":"A portal was created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"portal.created"},"data":{"$ref":"#/components/schemas/PortalCreatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"portal.updated":{"post":{"summary":"A portal changed (which fields).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"portal.updated"},"data":{"$ref":"#/components/schemas/PortalUpdatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"practice.started":{"post":{"summary":"A person started a practice attempt.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"practice.started"},"data":{"$ref":"#/components/schemas/PracticeStartedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"report.produced":{"post":{"summary":"A session's report is ready: numbers once released; its words only with includeConversation, where allowed. Never for a candidate.","description":"Conversation fields (summary, report.summary, report.strengths, report.workOn, report.next, report.better, report.visitor.topics, report.visitor.answered, report.visitor.handoff.reason, report.visitor.unanswered) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"report.produced"},"data":{"$ref":"#/components/schemas/ReportProducedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"result.contested":{"post":{"summary":"A person asked for their result to be looked at again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"result.contested"},"data":{"$ref":"#/components/schemas/ResultContestedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"review.completed":{"post":{"summary":"A person decided a result under review.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"review.completed"},"data":{"$ref":"#/components/schemas/ReviewCompletedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"review.requested":{"post":{"summary":"A result waits for a person's review (why, never the score).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"review.requested"},"data":{"$ref":"#/components/schemas/ReviewRequestedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"score.recorded":{"post":{"summary":"A released score for a person's session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"score.recorded"},"data":{"$ref":"#/components/schemas/ScoreRecordedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"session.ended":{"post":{"summary":"A session ended, once: its length and minutes. Its summary only with includeConversation, where allowed.","description":"Conversation fields (summary) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"session.ended"},"data":{"$ref":"#/components/schemas/SessionEndedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"session.started":{"post":{"summary":"A live session started: an API session, or a member's session on a portal (never its plan).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"session.started"},"data":{"$ref":"#/components/schemas/SessionStartedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"session.transcript_ready":{"post":{"summary":"A session's whole transcript can be read with GET /v1/sessions/{id}/transcript (ids only; only where the API may read it).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"session.transcript_ready"},"data":{"$ref":"#/components/schemas/SessionTranscriptReadyData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"setting.changed":{"post":{"summary":"A switch changed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"setting.changed"},"data":{"$ref":"#/components/schemas/SettingChangedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"subject.draft_saved":{"post":{"summary":"A subject's draft version was saved.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"subject.draft_saved"},"data":{"$ref":"#/components/schemas/SubjectDraftSavedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"transcript.final":{"post":{"summary":"One finished turn of a session the API started, with its words. Needs includeConversation.","description":"Conversation fields (text) are sent only to a webhook with includeConversation, and never from a minor's, a candidate's or a safety-flagged session; otherwise they are null. Needs includeConversation, and must be named in the webhook's events (\"*\" never includes it).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"transcript.final"},"data":{"$ref":"#/components/schemas/TranscriptFinalData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08","x-zentiq-explicit-only":true}},"unit.created":{"post":{"summary":"A unit was created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"unit.created"},"data":{"$ref":"#/components/schemas/UnitCreatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"unit.deleted":{"post":{"summary":"A unit was deleted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"unit.deleted"},"data":{"$ref":"#/components/schemas/UnitDeletedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"unit.disabled":{"post":{"summary":"A unit was switched off, with everything below it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"unit.disabled"},"data":{"$ref":"#/components/schemas/UnitSwitchData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"unit.enabled":{"post":{"summary":"A unit was switched on again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"unit.enabled"},"data":{"$ref":"#/components/schemas/UnitSwitchData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"unit.renamed":{"post":{"summary":"A unit was renamed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"unit.renamed"},"data":{"$ref":"#/components/schemas/UnitRenamedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"unit.updated":{"post":{"summary":"A unit was moved or changed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"unit.updated"},"data":{"$ref":"#/components/schemas/UnitUpdatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"usage.threshold":{"post":{"summary":"The organisation's minutes crossed a warning level.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"usage.threshold"},"data":{"$ref":"#/components/schemas/UsageThresholdData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"visitor.detail_removed":{"post":{"summary":"A website visitor asked for details to be forgotten: which fields to delete from your systems.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"visitor.detail_removed"},"data":{"$ref":"#/components/schemas/VisitorDetailRemovedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"visitor.session.ended":{"post":{"summary":"A website visitor's conversation ended (never a candidate's interview).","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"visitor.session.ended"},"data":{"$ref":"#/components/schemas/VisitorSessionEndedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"voice.clone.completed":{"post":{"summary":"A cloned voice is ready to use.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"voice.clone.completed"},"data":{"$ref":"#/components/schemas/VoiceCloneCompletedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"webhook.test":{"post":{"summary":"A test ping, sent only to the webhook it was asked for.","description":"Sent only to the webhook it was asked for.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"webhook.test"},"data":{"$ref":"#/components/schemas/WebhookTestData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"widget.updated":{"post":{"summary":"A persona's website widget was switched on or off, or changed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"widget.updated"},"data":{"$ref":"#/components/schemas/WidgetUpdatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-10-01"}},"workspace.created":{"post":{"summary":"A subject was created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"workspace.created"},"data":{"$ref":"#/components/schemas/WorkspaceCreatedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}},"workspace.published":{"post":{"summary":"A subject's version went live.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"workspace.published"},"data":{"$ref":"#/components/schemas/WorkspacePublishedData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried."}},"x-zentiq-since":"2026-07-08"}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"zq_live_…","description":"Organisation API key."}},"schemas":{"AddMembershipInput":{"type":"object","properties":{"role":{"type":"string","enum":["OWNER","ADMIN","AVATAR_BUILDER","WORKSPACE_ADMIN","LEADER","LEARNER","OBSERVER"],"description":"OWNER (never given or changed through the API), ADMIN, AVATAR_BUILDER, WORKSPACE_ADMIN (these four at the organisation level only), LEADER, LEARNER, OBSERVER."},"unitId":{"anyOf":[{"description":"Unit id (`unit_…`).","type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"description":"Subject id (`sub_…`).","type":"string"},{"type":"null"}]},"gradeBand":{"anyOf":[{"type":"string","description":"A year or grade: a number (\"5\") or a range (\"7-9\").","examples":["5"]},{"type":"null"}]},"ageBand":{"anyOf":[{"type":"string","enum":["18+"],"description":"`\"18+\"` marks a learner as an adult: they start without a parent's or guardian's consent, and a place of theirs waiting for consent is switched on. Only on a learner's place, and only while the organisation has switched on \"Mark learners who are adults (18+)\" (`409 conflict`, `details.reason: \"adult_learners_off\"`).","examples":["18+"]},{"type":"null"}]}},"required":["role"]},"AgentAnswer":{"type":"object","properties":{"answer":{"type":"string","description":"The assistant's written answer, from what the business has told it. Email addresses, phone numbers and payment or identity numbers are removed.","examples":["Yes, we're open on Saturdays from 9am to 1pm."]},"url":{"type":"string","description":"The assistant's own page, where a person can talk to it, book or reach the team."},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: the answer is AI-generated (EU AI Act Article 50(2)). Say so when you pass it on."}},"required":["answer","url","aiGenerated"],"description":"One written answer from a business's public website assistant."},"AgentAskInput":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":800,"description":"One question, up to 800 characters. Leave out people's names and contact details: email addresses, phone numbers and payment or identity numbers are removed before it is read.","examples":["Are you open on Saturdays?"]}},"required":["question"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^key_.*","description":"API key id (`key_…`).","examples":["key_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"prefix":{"type":"string","description":"The key's first characters, as shown in the console.","examples":["zq_live_ab12"]},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes as set on the key; [] or [\"*\"] is full access (sensitive scopes are added by name)."},"apiVersion":{"type":"string","enum":["2026-07-08","2026-10-01"],"description":"The contract the key speaks."},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Who made it: a member (`usr_…`) or a key (`key_…`); null for older keys."},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","name","prefix","scopes","apiVersion","createdBy","lastUsedAt","revokedAt","createdAt"],"description":"An API key. The secret is never returned after creation."},"AssessmentCompletedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"marks":{"anyOf":[{"type":"number"},{"type":"null"}]},"outOf":{"anyOf":[{"type":"number"},{"type":"null"}]},"passMark":{"anyOf":[{"type":"number"},{"type":"null"}]},"questionSet":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]},"humanReview":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"review":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"criticalFail":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"string"},{"type":"null"}]},"final":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"ai":{"anyOf":[{"type":"object","properties":{"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"marks":{"anyOf":[{"type":"number"},{"type":"null"}]}}},{"type":"null"}]},"decision":{"anyOf":[{"type":"string"},{"type":"null"}]},"voided":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"reviewed":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A scored attempt completed; the final result once a person has decided it."},"AssignmentCompletedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"assignmentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"pass":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A person completed assigned work."},"AssignmentCreatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"assignmentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"learners":{"anyOf":[{"type":"integer"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"skills":{"anyOf":[{"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},{"type":"null"}]},"focus":{"anyOf":[{"type":"object","properties":{"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"string"},{"type":"null"}]},"target":{"anyOf":[{"type":"number"},{"type":"null"}]}},"description":"Work was assigned."},"AssignmentStartedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"assignmentId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A person started assigned work."},"AttemptGrantedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reportId":{"anyOf":[{"type":"string"},{"type":"null"}]},"incomplete":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A person was given one more scored attempt."},"AttestationRecordedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"questionSet":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"documentIds":{"anyOf":[{"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]}},"description":"A person confirmed an attestation before a completion."},"Avatar":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^av_.*","description":"Avatar id (`av_…`).","examples":["av_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"kind":{"type":"string","enum":["builtin","custom"],"description":"builtin: Zentiq's library; custom: your organisation's own."},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A library face's gender (female, male); null for your own pictures."},"ageBand":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A library face's age band (20s, 30s, 40s, 50s, 60s); null for your own."},"heritage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A library face's heritage (white, black, indian, chinese, korean, japanese, thai, hispanic, middleeastern, mixed); null for your own."},"previewUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The picture. A library face is public (usable in an <img>); your own needs your API key (or a console sign-in)."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: this avatar's video and voice in every session are AI-generated, and so is its picture unless it is a photo you uploaded (EU AI Act Article 50(2))."}},"required":["id","name","kind","gender","ageBand","heritage","previewUrl","createdAt","aiGenerated"],"description":"A face a persona can wear: from the library, or your organisation's own."},"AvatarInput":{"type":"object","properties":{"name":{"description":"Default \"Custom avatar\".","type":"string"},"imageBase64":{"description":"The picture as a data:image/… URI (PNG, JPEG or WebP).","type":"string"},"imageUrl":{"format":"uri","description":"Or a public https address to fetch it from (6 MB at most).","type":"string"},"consent":{"$ref":"#/components/schemas/Consent"}},"required":["consent"],"description":"Exactly one of imageBase64 or imageUrl, and `consent`: whose face it is and that they agreed, or subject \"generated\" for a face made by AI."},"BookingRequestedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"need":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"budget":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"timeline":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"contact":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"company":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"role":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"preferredTime":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"location":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"reference":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}}},{"type":"null"}]},"consent":{"anyOf":[{"type":"object","properties":{"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"marketing":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"text":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"given":{"anyOf":[{"type":"boolean"},{"type":"null"}]}}},{"type":"null"}]},"promise":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"department":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"service":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"when":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"inboxItemId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A website visitor asked for a booking: contact details, the service and time asked for, and their consent."},"Candidate":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^cand_.*","description":"`cand_…`: the candidate's interview.","examples":["cand_cmfq2b7x10000abcd1234"]},"sessionId":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"roleId":{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},"portalId":{"anyOf":[{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"inviteId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^inv_.*","description":"Invite id (`inv_…`).","examples":["inv_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your ATS's id from the invite."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Null once erased."},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"interviewedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"typed":{"type":"boolean","description":"They typed instead of speaking."},"round":{"anyOf":[{"type":"integer"},{"type":"null"}]},"withdrawn":{"type":"boolean","description":"They chose to end the interview: never scored."},"erased":{"type":"boolean"},"erasedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"mustHaves":{"anyOf":[{"type":"string","enum":["met","missed","unclear","none"]},{"type":"null"}],"description":"The must-have requirements: all met, one missed, unclear (a person checks), or none set. Flagged for a person, never acted on. Null once erased."},"requirements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"met":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"knockout":{"type":"boolean"}},"required":["id","met","knockout"]},"description":"Each requirement's result; never the answer. Empty once erased."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Only where the role shares scores, and never once erased; else null."},"band":{"anyOf":[{"type":"string","enum":["strong","possible","below","unscored"]},{"type":"null"}],"description":"Only where the role shares scores, and never once erased; else null."},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Place by score among the role's candidates in the same round (1 = highest; erased and withdrawn candidates hold no place); only where the role shares scores."},"decision":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","enum":["invite","hold","decline"],"description":"decline is shown to people as \"not progressing\"."},"reason":{"anyOf":[{"type":"string","enum":["must_haves","strong_answers","missing_must_have","stronger_candidate","more_evidence","withdrew","other"]},{"type":"null"}],"description":"The reason code from the fixed list (a note is never given out)."},"decidedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"decidedBy":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]}},"required":["id"]},{"type":"null"}],"description":"The member who decided (never an API key)."}},"required":["value","reason","decidedAt","decidedBy"]},{"type":"null"}],"description":"The latest decision a person made; null while it awaits one."},"reviews":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"required":{"type":"integer","minimum":0},"recommendations":{"anyOf":[{"type":"object","properties":{"advance":{"type":"integer","minimum":0},"hold":{"type":"integer","minimum":0},"doNotAdvance":{"type":"integer","minimum":0}},"required":["advance","hold","doNotAdvance"]},{"type":"null"}],"description":"How many reviewers recommend advance, hold or do not advance. Only where the role shares scores (candidates.share_scores), and never once erased; else null."}},"required":["count","required","recommendations"]},"hold":{"type":"boolean","description":"A legal hold keeps their data past the role's retention."},"reviewRequested":{"type":"boolean","description":"They asked for a review of the decision and no decision was recorded since."},"retentionExpiresAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When their data is erased (null while held or once erased)."},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","sessionId","roleId","portalId","inviteId","externalId","name","email","phone","interviewedAt","minutes","typed","round","withdrawn","erased","erasedAt","mustHaves","requirements","score","band","rank","decision","reviews","hold","reviewRequested","retentionExpiresAt","updatedAt"],"description":"A candidate: someone who took a role's interview. A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically."},"CandidateCompliance":{"type":"object","properties":{"candidateId":{"type":"string","minLength":1,"pattern":"^cand_.*","description":"Candidate id (`cand_…`).","examples":["cand_cmfq2b7x10000abcd1234"]},"roleId":{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},"laws":{"type":"array","items":{"type":"string","enum":["illinois","nyc","colorado"]},"description":"The US hiring rules the pack applies to the role now: illinois, nyc, colorado."},"consent":{"anyOf":[{"type":"object","properties":{"at":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When the candidate agreed to take part and started."},"shownAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When the page with the notices was made for them."},"notices":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["aivia","nyc","colorado"]},"version":{"type":"string"},"fingerprint":{"type":"string","description":"SHA-256 of the notice's exact text as shown."}},"required":["kind","version","fingerprint"]}},"illinoisConsent":{"type":"boolean","description":"They gave the separate consent to the AI analysing their interview (Illinois)."}},"required":["at","shownAt","notices","illinoisConsent"]},{"type":"null"}],"description":"What the candidate read and agreed to at the start; null for an interview started before the pack was on for the role."},"nycNotice":{"anyOf":[{"type":"object","properties":{"via":{"type":"string","enum":["posting","invite_email","invite_link","door_email"],"description":"posting (the date your job posting gave it), invite_email, invite_link or door_email."},"noticeAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"postedOn":{"anyOf":[{"type":"string","format":"date","description":"A calendar date (YYYY-MM-DD).","examples":["2026-09-25"]},{"type":"null"}]}},"required":["via","noticeAt","postedOn"]},{"type":"null"}],"description":"New York City: how the notice reached the candidate at least 10 business days before the interview."},"requests":{"type":"array","items":{"$ref":"#/components/schemas/CandidateRequest"}}},"required":["candidateId","roleId","laws","consent","nycNotice","requests"],"description":"A candidate's US hiring record: the notices they read, their consent and their requests."},"CandidateDecisionInput":{"type":"object","properties":{"decision":{"type":"string","enum":["invite","hold","decline"]},"reason":{"type":"string","enum":["must_haves","strong_answers","missing_must_have","stronger_candidate","more_evidence","withdrew","other"],"description":"must_haves, strong_answers, missing_must_have, stronger_candidate, more_evidence, withdrew or other (other needs a note)."},"note":{"description":"Kept for the hiring team; never given out through the API or webhooks.","type":"string","maxLength":600},"decidedBy":{"description":"The member who made the decision (`usr_…`). Their own hiring access applies, and a decline needs them to have opened the interview or reviewed it in Zentiq.","type":"string"},"sendOutcomeEmail":{"description":"Email the candidate the outcome, with their link to ask for a review.","type":"boolean"}},"required":["decision","reason","decidedBy"],"additionalProperties":false,"description":"A person's decision on one candidate. A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically."},"CandidateInterview":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^cand_.*","description":"Candidate id (`cand_…`).","examples":["cand_cmfq2b7x10000abcd1234"]},"sessionId":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"roleId":{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},"portalId":{"anyOf":[{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"inviteId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^inv_.*","description":"Invite id (`inv_…`).","examples":["inv_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your ATS's id from the invite."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string","description":"The job, as the interview named it."},"round":{"anyOf":[{"type":"integer"},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The version of the role the interview ran on."},"level":{"anyOf":[{"type":"string","enum":["relaxed","standard","rigorous"]},{"type":"null"}],"description":"How demanding the interview was set to be (the same for every candidate of the role)."},"panel":{"type":"boolean","description":"Two AI interviewers took turns."},"typed":{"type":"boolean","description":"They typed instead of speaking."},"practiceQuestion":{"type":"boolean","description":"It opened with an unscored practice question. Its answer is never kept, never in the transcript and never marked."},"startedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"interviewedAt":{"type":"string","format":"date-time","description":"When it ended and reached the hiring team.","examples":["2026-09-25T12:00:00.000Z"]},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"scoresShared":{"type":"boolean","description":"The role shares scores (candidates.share_scores): the numbers below are filled in."},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"band":{"anyOf":[{"type":"string","enum":["strong","possible","below","unscored"]},{"type":"null"}]},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Place by score among the role's candidates in the same round (1 = highest)."},"mustHaves":{"type":"string","enum":["met","missed","unclear","none"]},"requirements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"question":{"type":"string"},"answer":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Their answer in a few words, as the interview heard it; null when it was never answered."},"met":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether it meets the requirement (decided in code); null when unclear: a person checks it."},"knockout":{"type":"boolean","description":"A must-have: not meeting it is flagged to the hiring team, never acted on."},"why":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the role needs it, as the role says."}},"required":["id","question","answer","met","knockout","why"]},"description":"The must-have questions, with their answers."},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The question's id in the role's question set."},"n":{"type":"integer","minimum":1,"description":"Its number in the interview (\"Question 2 of 5\")."},"question":{"type":"string"},"answer":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What they said after the interviewer read the question, up to the next one, from the transcript; null when it can't be told or nothing is kept."},"status":{"type":"string","enum":["answered","skipped","asked"]},"verdict":{"anyOf":[{"type":"string","enum":["right","partial","not-yet"]},{"type":"null"}],"description":"How the answer compares with what the role looks for. Only where the role shares scores."},"marks":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Marks given. Only where the role shares scores."},"outOf":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The marks the question carries."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A short note on the answer, as the report wrote it."},"redFlag":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"The answer showed one of the question's red flags (for a person to check). Only where the role shares scores."},"hints":{"type":"integer","minimum":0,"description":"Hints the interviewer gave on it."}},"required":["id","n","question","answer","status","verdict","marks","outOf","note","redFlag","hints"]},"description":"The interview questions, in order, with the answers and what the platform found in them."},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The written summary for the hiring team."},"strengths":{"type":"array","items":{"type":"string"}},"concerns":{"type":"array","items":{"type":"string"},"description":"Where the evidence was thin."},"competencies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"weight":{"type":"number"},"score":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","label","weight","score"]},"description":"The role's competencies with their score (0-100) where there was evidence and the role shares scores."},"evidence":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":"string"},"quote":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Their own words."},"note":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["competencyId","quote","note"]},"description":"What the report quotes from the interview, by competency."},"transcript":{"type":"object","properties":{"kept":{"type":"boolean","description":"false when the role keeps no transcripts (then `turns` is empty)."},"turns":{"type":"array","items":{"type":"object","properties":{"speaker":{"type":"string","enum":["ai","candidate"],"description":"ai: Zentiq's AI interviewer; candidate: the person."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Which AI interviewer spoke, when two took turns; else null."},"text":{"type":"string"},"offsetMs":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Milliseconds from the start of the interview, when known."}},"required":["speaker","name","text","offsetMs"]}}},"required":["kept","turns"]},"adjustments":{"type":"object","properties":{"requested":{"type":"boolean"}},"required":["requested"],"description":"Whether they asked for an adjustment during the interview: make sure it was given. Never which one, nor why (it can reveal a disability): that stays with the hiring team in Zentiq."},"reviewRequest":{"anyOf":[{"type":"object","properties":{"requestedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]},"open":{"type":"boolean"}},"required":["requestedAt","message","open"]},{"type":"null"}],"description":"They asked for a review of the decision (from the link in an outcome email); open until a person decides again."},"reviews":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"required":{"type":"integer","minimum":0,"description":"Reviews a decision waits for (candidates.reviews_required)."},"blind":{"type":"boolean","description":"Blind review (candidates.blind_review): each reviewer sees the others' reviews only after adding their own."},"hiddenBy":{"anyOf":[{"type":"string","enum":["blind_review","scores_not_shared"]},{"type":"null"}],"description":"Why `items` is null: the role's blind review, or its scores aren't shared."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"reviewer":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]}},"required":["id"]},"recommendation":{"type":"string","enum":["advance","hold","do_not_advance"]},"ratings":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5}},"required":["competencyId","rating"]}},"reviewedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["reviewer","recommendation","ratings","reviewedAt"]}},{"type":"null"}],"description":"Each reviewer's recommendation and ratings, never their notes. Null while hidden."}},"required":["count","required","blind","hiddenBy","items"]},"integrity":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"kinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["face_out_of_view","another_person","left_page","pasted_text","camera_off","microphone_off","connection_dropped"]},"count":{"type":"integer","minimum":0}},"required":["kind","count"]}}},"required":["count","kinds"],"description":"Moments a recorded interview noted for a person to watch (how many, of which kinds), never part of the score. Their details stay in Zentiq."},"flags":{"type":"object","properties":{"count":{"type":"integer","minimum":0}},"required":["count"],"description":"Things the report asks a person to look at; their words stay in Zentiq."},"recorded":{"anyOf":[{"type":"string","enum":["audio","audio_video"]},{"type":"null"}],"description":"A recording exists (watch it in Zentiq); it is never given out."},"decision":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","enum":["invite","hold","decline"],"description":"decline is shown to people as \"not progressing\"."},"reason":{"anyOf":[{"type":"string","enum":["must_haves","strong_answers","missing_must_have","stronger_candidate","more_evidence","withdrew","other"]},{"type":"null"}],"description":"The reason code from the fixed list (a note is never given out)."},"decidedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"decidedBy":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]}},"required":["id"]},{"type":"null"}],"description":"The member who decided (never an API key)."}},"required":["value","reason","decidedAt","decidedBy"]},{"type":"null"}],"description":"The latest decision a person made; null while it awaits one."},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","sessionId","roleId","portalId","inviteId","externalId","name","email","phone","location","title","round","version","level","panel","typed","practiceQuestion","startedAt","endedAt","interviewedAt","minutes","scoresShared","score","band","rank","mustHaves","requirements","questions","summary","strengths","concerns","competencies","evidence","transcript","adjustments","reviewRequest","reviews","integrity","flags","recorded","decision","updatedAt"],"description":"A candidate's interview for your hiring system: every read is logged on the candidate. A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically."},"CandidateRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^creq_.*","description":"Candidate request id (`creq_…`).","examples":["creq_cmfq2b7x10000abcd1234"]},"kind":{"type":"string","enum":["deletion","alternative","review","correction"],"description":"deletion (their interview, any recording and every copy), alternative (another way to be assessed, or an accommodation), review (a person to review a decision) or correction (their data corrected)."},"status":{"type":"string","enum":["open","paused","done"],"description":"open; paused while a legal hold keeps the interview (the candidate was told); done once answered, or (a deletion) once the interview was erased."},"roleId":{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},"candidateId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^cand_.*","description":"Candidate id (`cand_…`).","examples":["cand_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The candidate whose interview it is about; null before an interview (an invitation) or from the door."},"inviteId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^inv_.*","description":"Invite id (`inv_…`).","examples":["inv_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"source":{"type":"string","enum":["link","interview","door","outcome_email"],"description":"link: the candidate's own page; door: the interview's page; outcome_email: the review link in an outcome email."},"requestedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"dueAt":{"type":"string","format":"date-time","description":"When the hiring team is asked to have answered: 30 days for a deletion, a review or a correction, 14 for another way.","examples":["2026-09-25T12:00:00.000Z"]},"autoDeleteAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"A deletion the role carries out automatically: when (day 30), unless a person acts first or a legal hold is on."},"overdue":{"type":"boolean"},"outcome":{"anyOf":[{"type":"string","enum":["deleted","deleted_automatically","alternative_offered","accommodation_given","not_possible","withdrawn_by_candidate","decision_stands","decision_changed","data_corrected","nothing_to_correct"]},{"type":"null"}],"description":"What happened, once done: deleted, deleted_automatically, alternative_offered, accommodation_given, not_possible, withdrawn_by_candidate, decision_stands, decision_changed, data_corrected or nothing_to_correct."},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]}},"required":["id","kind","status","roleId","candidateId","inviteId","source","requestedAt","dueAt","autoDeleteAt","overdue","outcome","resolvedAt"],"description":"A candidate's request under the US hiring pack. Their message and contact details stay in Zentiq."},"CandidateWebhookData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidateId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"inviteId":{"anyOf":[{"type":"string"},{"type":"null"}]},"roleId":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"decision":{"anyOf":[{"type":"string"},{"type":"null"}]},"recommendation":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"by":{"anyOf":[{"type":"string","enum":["team","candidate"]},{"type":"null"}]},"reviewerId":{"anyOf":[{"type":"string"},{"type":"null"}]},"offerId":{"anyOf":[{"type":"string"},{"type":"null"}]},"slotId":{"anyOf":[{"type":"string"},{"type":"null"}]},"timing":{"anyOf":[{"type":"string"},{"type":"null"}]},"startAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"opensAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"lateAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"deadlineAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"rescheduled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"occurredAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"resent":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["eventId","status","candidateId","sessionId","roleId","occurredAt"],"description":"A candidate event's data: ids, the role, the portal, a status and timestamps only. Never a name, an email, answers, notes, ratings or scores."},"CandidateWithHistory":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^cand_.*","description":"`cand_…`: the candidate's interview.","examples":["cand_cmfq2b7x10000abcd1234"]},"sessionId":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"roleId":{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},"portalId":{"anyOf":[{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"inviteId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^inv_.*","description":"Invite id (`inv_…`).","examples":["inv_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your ATS's id from the invite."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Null once erased."},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"interviewedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"typed":{"type":"boolean","description":"They typed instead of speaking."},"round":{"anyOf":[{"type":"integer"},{"type":"null"}]},"withdrawn":{"type":"boolean","description":"They chose to end the interview: never scored."},"erased":{"type":"boolean"},"erasedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"mustHaves":{"anyOf":[{"type":"string","enum":["met","missed","unclear","none"]},{"type":"null"}],"description":"The must-have requirements: all met, one missed, unclear (a person checks), or none set. Flagged for a person, never acted on. Null once erased."},"requirements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"met":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"knockout":{"type":"boolean"}},"required":["id","met","knockout"]},"description":"Each requirement's result; never the answer. Empty once erased."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Only where the role shares scores, and never once erased; else null."},"band":{"anyOf":[{"type":"string","enum":["strong","possible","below","unscored"]},{"type":"null"}],"description":"Only where the role shares scores, and never once erased; else null."},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Place by score among the role's candidates in the same round (1 = highest; erased and withdrawn candidates hold no place); only where the role shares scores."},"decision":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","enum":["invite","hold","decline"],"description":"decline is shown to people as \"not progressing\"."},"reason":{"anyOf":[{"type":"string","enum":["must_haves","strong_answers","missing_must_have","stronger_candidate","more_evidence","withdrew","other"]},{"type":"null"}],"description":"The reason code from the fixed list (a note is never given out)."},"decidedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"decidedBy":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]}},"required":["id"]},{"type":"null"}],"description":"The member who decided (never an API key)."}},"required":["value","reason","decidedAt","decidedBy"]},{"type":"null"}],"description":"The latest decision a person made; null while it awaits one."},"reviews":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"required":{"type":"integer","minimum":0},"recommendations":{"anyOf":[{"type":"object","properties":{"advance":{"type":"integer","minimum":0},"hold":{"type":"integer","minimum":0},"doNotAdvance":{"type":"integer","minimum":0}},"required":["advance","hold","doNotAdvance"]},{"type":"null"}],"description":"How many reviewers recommend advance, hold or do not advance. Only where the role shares scores (candidates.share_scores), and never once erased; else null."}},"required":["count","required","recommendations"]},"hold":{"type":"boolean","description":"A legal hold keeps their data past the role's retention."},"reviewRequested":{"type":"boolean","description":"They asked for a review of the decision and no decision was recorded since."},"retentionExpiresAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When their data is erased (null while held or once erased)."},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"decisions":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","enum":["invite","hold","decline"],"description":"decline is shown to people as \"not progressing\"."},"reason":{"anyOf":[{"type":"string","enum":["must_haves","strong_answers","missing_must_have","stronger_candidate","more_evidence","withdrew","other"]},{"type":"null"}],"description":"The reason code from the fixed list (a note is never given out)."},"decidedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"decidedBy":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]}},"required":["id"]},{"type":"null"}],"description":"The member who decided (never an API key)."}},"required":["value","reason","decidedAt","decidedBy"]},"description":"Every decision recorded, newest first."}},"required":["id","sessionId","roleId","portalId","inviteId","externalId","name","email","phone","interviewedAt","minutes","typed","round","withdrawn","erased","erasedAt","mustHaves","requirements","score","band","rank","decision","reviews","hold","reviewRequested","retentionExpiresAt","updatedAt","decisions"],"description":"A candidate with their decision history. A person decides every outcome: scores and bands are a sorting aid for the hiring team, never a verdict, and no decision is made automatically."},"CaseLink":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^clk_.*","description":"Case link id (`clk_…`).","examples":["clk_cmfq2b7x10000abcd1234"]},"portalId":{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},"reference":{"type":"string"},"kind":{"type":"string","enum":["case","order","claim","appointment","ticket","booking","application","renewal"]},"customerId":{"type":"string","description":"Your own id for the customer."},"status":{"type":"string","enum":["active","expired","revoked","used_up"],"description":"active: it opens; expired: past expiresAt; revoked: switched off; used_up: every conversation it may start has started."},"opens":{"type":"integer","description":"Conversations started from it so far."},"maxOpens":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"lastOpenedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"emailedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When your team emailed it from the console; null when it was sent some other way."},"source":{"type":"string","enum":["api","console"],"description":"Made with an API key, or by your team in the console."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","portalId","reference","kind","customerId","status","opens","maxOpens","expiresAt","revokedAt","lastOpenedAt","emailedAt","source","createdAt"],"description":"A personal link one customer was sent about their case. Never the case's details or the link's address: those went to the customer only."},"CaseLinkCreated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^clk_.*","description":"Case link id (`clk_…`).","examples":["clk_cmfq2b7x10000abcd1234"]},"portalId":{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},"reference":{"type":"string"},"kind":{"type":"string","enum":["case","order","claim","appointment","ticket","booking","application","renewal"]},"customerId":{"type":"string","description":"Your own id for the customer."},"status":{"type":"string","enum":["active","expired","revoked","used_up"],"description":"active: it opens; expired: past expiresAt; revoked: switched off; used_up: every conversation it may start has started."},"opens":{"type":"integer","description":"Conversations started from it so far."},"maxOpens":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"lastOpenedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"emailedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When your team emailed it from the console; null when it was sent some other way."},"source":{"type":"string","enum":["api","console"],"description":"Made with an API key, or by your team in the console."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"url":{"type":"string","description":"The link to send your customer (by email, text message or your app). Shown only now, never again: Zentiq keeps no copy it could show. Never put it in a public place."}},"required":["id","portalId","reference","kind","customerId","status","opens","maxOpens","expiresAt","revokedAt","lastOpenedAt","emailedAt","source","createdAt","url"],"description":"The new link, with the address to send your customer (only in this answer)."},"CaseLinkInput":{"type":"object","properties":{"customerId":{"type":"string","maxLength":128,"description":"Your own id for the customer: every action call from the conversation carries it as `customer.id`."},"reference":{"type":"string","maxLength":64,"description":"The case's own reference in your system (an order, claim, booking or ticket number): the avatar names it, and every action call carries it as `case.reference`.","examples":["10423"]},"kind":{"default":"case","description":"What the case is, for the avatar's words (\"your order 10423\", \"your support ticket 10423\").","anyOf":[{"type":"string","enum":["case","order","claim","appointment","ticket","booking","application","renewal"]},{"type":"null"}]},"summary":{"type":"string","maxLength":1000,"description":"What the case is about and where it stands, in a sentence or two the avatar may use with your customer. The avatar reads it as your record (data, never instructions).","examples":["The parcel is delayed at the depot; the new delivery date is Tuesday."]},"facts":{"description":"Up to 20 short facts, like { \"status\": \"delayed\", \"items\": 2 } (names of letters and digits, values of at most 200 characters). Never a password, code or card detail: a fact named like one is refused.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},{"type":"null"}]},"firstName":{"maxLength":40,"description":"Your customer's first name: the avatar greets them with it.","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"format":"email","description":"The email address you have on file for them. The avatar only ever sees it masked (\"s***@example.com\"). With Verified customer switched on, it is where the one-time code goes before a sensitive action.","anyOf":[{"type":"string"},{"type":"null"}]},"opening":{"maxLength":300,"description":"The avatar's first line about the case, in your words. Without it the avatar says what the case is and asks how it can help.","anyOf":[{"type":"string"},{"type":"null"}]},"expiresInDays":{"minimum":1,"maximum":30,"default":7,"description":"How long the link works, in whole days.","anyOf":[{"type":"number"},{"type":"null"}]},"maxOpens":{"minimum":1,"maximum":100,"default":20,"description":"How many conversations the link may start (so a forwarded link can't be used again and again). Opening the page alone uses none.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["customerId","reference","summary"],"description":"One customer's case, for a personal link to your portal's website door."},"CaseLinkOpenedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caseLinkId":{"anyOf":[{"type":"string"},{"type":"null"}]},"caseReference":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"customerId":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}]},"opens":{"anyOf":[{"type":"integer"},{"type":"null"}]},"maxOpens":{"anyOf":[{"type":"integer"},{"type":"null"}]},"channel":{"anyOf":[{"type":"string","enum":["voice","chat"]},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]}},"description":"A customer started a conversation from a case link you sent them (the link, your reference and customer id, the opens so far). The case summary only with includeConversation."},"CertificateIssuedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"issuedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"validUntil":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"level":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"issuer":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"showScore":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"setId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A certificate was issued (its number, never the holder's name)."},"CertificateNoticeData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"certificateId":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"validUntil":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"renewalAssignmentId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A certificate close to or past its valid-until date."},"CertificateRevokedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"certificateId":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string","enum":["Attempt voided after review","Result changed after review"]},{"type":"null"}]}},"description":"A certificate was withdrawn (a fixed reason)."},"ChatTurnInput":{"type":"object","properties":{"role":{"type":"string","enum":["visitor","agent","bot"],"description":"Who said it: the customer (`visitor`), a person on your team (`agent`) or your chat bot (`bot`)."},"text":{"type":"string","maxLength":4000,"description":"What they said: plain text."},"at":{"description":"When it was said: an ISO 8601 date and time (or seconds since 1970).","anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]}},"required":["role","text"],"description":"One message of the chat so far."},"CompletionRecordedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"passMark":{"anyOf":[{"type":"number"},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"setId":{"anyOf":[{"type":"string"},{"type":"null"}]},"setTitle":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"attempt":{"anyOf":[{"type":"integer"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"documents":{"anyOf":[{"maxItems":20,"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"hash":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]}},{"type":"null"}]},"documentsHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"reviewed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"reviewerId":{"anyOf":[{"type":"string"},{"type":"null"}]},"decision":{"anyOf":[{"type":"string"},{"type":"null"}]},"decidedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]}},"description":"A completion record was written for a confirmed pass."},"CompletionWithdrawnData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reason":{"anyOf":[{"type":"string","enum":["Attempt voided after review","Result changed after review"]},{"type":"null"}]}},"description":"A completion was withdrawn (a fixed reason)."},"Connection":{"type":"object","properties":{"id":{"type":"string","description":"Connection id (`conn_…`)."},"kind":{"type":"string","enum":["mcp","calcom","hubspot","shopify","google_calendar","microsoft_calendar","slack","zapier"]},"name":{"type":"string","description":"The system, in words."},"label":{"type":"string"},"status":{"type":"string","enum":["pending","active","failing","reconnect"]},"statusWords":{"type":"string"},"secretHint":{"type":"string","description":"The last four characters of its key, like \"…4f2a\" (\"\" when there is none): the only part of a key ever shown."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"health":{"type":"object","properties":{"calls":{"type":"integer"},"successRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Calls the system answered, as a share of all (0 to 1); null before the first."},"p50Ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The median time of the latest calls, in ms."},"lastError":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"words":{"type":"string"},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","words","at"]},{"type":"null"}]}},"required":["calls","successRate","p50Ms","lastError"]},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"What isn't secret: the server's host, the shop, the event type, the calendar."}},"required":["id","kind","name","label","status","statusWords","secretHint","createdAt","lastUsedAt","health","details"],"description":"One of the organisation's connected systems. Never a key or a token."},"ConnectionCreated":{"type":"object","properties":{"connection":{"$ref":"#/components/schemas/Connection"},"authorizeUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"For a sign-in: where an owner approves it, signed in to the console. null when it is connected already."}},"required":["connection","authorizeUrl"]},"ConnectionDeleted":{"type":"object","properties":{"id":{"type":"string"},"actionsOff":{"type":"integer","description":"Actions that used it, now switched off."}},"required":["id","actionsOff"],"description":"Disconnected: the connection and its key are deleted."},"ConnectionFailedData":{"type":"object","properties":{"connectionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"description":"One of your connected systems started failing (its id, kind, an error code and the HTTP status): its actions tell visitors they can't do that just now. Never its key or anything it sent back."},"ConnectionInput":{"type":"object","properties":{"kind":{"type":"string","enum":["mcp","calcom","hubspot","shopify","google_calendar","microsoft_calendar","slack","zapier"],"description":"Which system."},"label":{"maxLength":60,"description":"A plain name (never a key).","anyOf":[{"type":"string"},{"type":"null"}]},"url":{"description":"mcp: the server's public https MCP address (standard port; private and local addresses are refused).","anyOf":[{"type":"string"},{"type":"null"}]},"auth":{"description":"mcp: how it signs in. `oauth`: the answer's `authorizeUrl` is where an owner approves it, signed in to the console.","anyOf":[{"type":"string","enum":["none","bearer","oauth"]},{"type":"null"}]},"token":{"writeOnly":true,"description":"mcp (bearer), hubspot (a private app's access token) or shopify (an older app's Admin API access token, made in the Shopify admin before 2026). Write-only: checked, sealed in the vault and never returned (only a masked hint).","anyOf":[{"type":"string"},{"type":"null"}]},"apiKey":{"writeOnly":true,"description":"calcom: a Cal.com API key. Write-only: checked, sealed in the vault and never returned (only a masked hint).","anyOf":[{"type":"string"},{"type":"null"}]},"eventTypeId":{"description":"calcom: the event type's number.","anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"timeZone":{"description":"calcom, google_calendar, microsoft_calendar: an IANA time zone, like America/New_York.","anyOf":[{"type":"string"},{"type":"null"}]},"shop":{"description":"shopify: the shop's address, like your-shop.myshopify.com.","anyOf":[{"type":"string"},{"type":"null"}]},"clientId":{"maxLength":100,"description":"shopify: a Dev Dashboard app's Client ID (the app's Settings), with clientSecret instead of token. Zentiq asks Shopify for the app's 24-hour tokens itself (the client credentials grant: the store must be in the app's own Shopify organisation).","anyOf":[{"type":"string"},{"type":"null"}]},"clientSecret":{"writeOnly":true,"description":"shopify: a Dev Dashboard app's Client secret, with clientId. It also verifies the order notifications Shopify sends for order emails. Write-only: checked, sealed in the vault and never returned (only a masked hint).","anyOf":[{"type":"string"},{"type":"null"}]},"apiSecret":{"writeOnly":true,"description":"shopify with token: the older app's API secret key, which only order emails need (Shopify signs its order notifications with it). Write-only: checked, sealed in the vault and never returned (only a masked hint).","anyOf":[{"type":"string"},{"type":"null"}]},"properties":{"description":"hubspot: the contact properties the avatar may read (HubSpot's own names).","anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},{"type":"null"}]},"calendarId":{"description":"google_calendar: which calendar (\"primary\" unless named).","anyOf":[{"type":"string"},{"type":"null"}]},"hours":{"description":"google_calendar, microsoft_calendar: opening hours per day, like { \"mon\": \"09:00-17:00\" } (a day left out is closed).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]},"slotMinutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"lengthMinutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"title":{"maxLength":60,"description":"google_calendar, microsoft_calendar: a booking's title.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind"],"description":"A system to connect, and what it needs."},"ConnectionList":{"type":"object","properties":{"on":{"type":"boolean","description":"The organisation's actions.connectors switch: off, nothing connected is used and nothing new can be connected."},"connections":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}}},"required":["on","connections"]},"ConnectionTest":{"type":"object","properties":{"ok":{"type":"boolean"},"words":{"type":"string"},"connection":{"$ref":"#/components/schemas/Connection"}},"required":["ok","words","connection"],"description":"A read-only call that proves it still works."},"Consent":{"type":"object","required":["attested","subject"],"description":"Consent to clone a real person's voice or to make an avatar from their picture. Recorded with who confirmed it (the API key), when, a hashed IP address, the exact wording and its version. The organisation's owners can export records and withdraw them; a withdrawn voice or face stops starting new sessions.","properties":{"attested":{"type":"boolean","const":true,"description":"You confirm the person agreed (or, with subject \"generated\", that the face is not a real person)."},"subject":{"type":"string","enum":["myself","someone_else","generated"],"description":"Whose face or voice it is. \"generated\" is for a face made by AI; a voice can't be generated."},"subjectName":{"type":"string","minLength":2,"maxLength":120,"description":"Required with subject \"someone_else\": the person's name."},"textVersion":{"type":"string","examples":["2026-09-15"],"description":"Optional. When sent it must be the current wording version, or the request is refused with consent_outdated."}}},"ConsentRecordedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"by":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"Consent was recorded for a membership (who recorded it, never their address)."},"ConversationRatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"rating":{"anyOf":[{"type":"number"},{"type":"null"}]},"comment":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"description":"A visitor rated a conversation (the comment only with includeConversation). Never a candidate's."},"CreateInvitesInput":{"type":"object","properties":{"candidates":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"email":{"type":"string","maxLength":254},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"externalId":{"type":"string","pattern":"^[^\\s@]{1,200}$"},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own data about the applicant, returned as it was: at most 20 string keys. Never sent by webhook."}},"required":["name","email"],"additionalProperties":false},"description":"At most 200, or 100 when Zentiq emails them. An address with an open invite for the role, one that completed the interview within its retention, or one listed twice is skipped."},"timing":{"$ref":"#/components/schemas/InviteTiming"},"timeZone":{"description":"IANA time zone the emails' times read in (default Europe/London).","type":"string","maxLength":64},"send":{"description":"true: Zentiq emails each candidate their link (with a calendar file for a set time, and reminders). false (default): copy the links yourself.","type":"boolean"},"portalId":{"description":"The portal whose door the links open; default: the role's own (where it is published and open to visitors).","type":"string"}},"required":["candidates","timing"],"additionalProperties":false,"description":"Invite candidates to a role's first-round interview."},"CreatePersonInput":{"type":"object","properties":{"externalId":{"description":"Your own id for the person: the sync key. A repeat with it returns the same person.","anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"email":{"description":"Without an externalId, the person is found or added by email. An email another account already has is refused (409).","anyOf":[{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"role":{"type":"string","enum":["OWNER","ADMIN","AVATAR_BUILDER","WORKSPACE_ADMIN","LEADER","LEARNER","OBSERVER"],"description":"OWNER (never given or changed through the API), ADMIN, AVATAR_BUILDER, WORKSPACE_ADMIN (these four at the organisation level only), LEADER, LEARNER, OBSERVER."},"unitId":{"anyOf":[{"description":"Unit id (`unit_…`).","type":"string"},{"type":"null"}]},"workspaceId":{"description":"A workspace admin's subject.","anyOf":[{"description":"Subject id (`sub_…`).","type":"string"},{"type":"null"}]},"gradeBand":{"anyOf":[{"type":"string","description":"A year or grade: a number (\"5\") or a range (\"7-9\").","examples":["5"]},{"type":"null"}]},"ageBand":{"anyOf":[{"type":"string","enum":["18+"],"description":"`\"18+\"` marks a learner as an adult: they start without a parent's or guardian's consent, and a place of theirs waiting for consent is switched on. Only on a learner's place, and only while the organisation has switched on \"Mark learners who are adults (18+)\" (`409 conflict`, `details.reason: \"adult_learners_off\"`).","examples":["18+"]},{"type":"null"}]},"loginCard":{"description":"A learner without an email gets a login card (needs accounts without email switched on).","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["role"]},"CreateUnitInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"parentId":{"anyOf":[{"description":"Unit id (`unit_…`).","type":"string"},{"type":"null"}]},"kind":{"description":"class, team, group, department, region, school or club (default: the organisation's).","anyOf":[{"type":"string","maxLength":32},{"type":"null"}]},"gradeBand":{"anyOf":[{"type":"string","description":"A year or grade: a number (\"5\") or a range (\"7-9\").","examples":["5"]},{"type":"null"}]},"leader":{"description":"Invites the unit's leader by email (takes a staff seat).","anyOf":[{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["email"]},{"type":"null"}]}},"required":["name"]},"CreatedInvites":{"type":"object","properties":{"created":{"type":"array","items":{"$ref":"#/components/schemas/Invite"}},"skipped":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"type":"string","enum":["open_invite","already_interviewed","listed_twice"]},"message":{"type":"string"}},"required":["email","externalId","reason","message"]}},"email":{"type":"object","properties":{"requested":{"type":"boolean"},"sent":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"queued":{"type":"integer","minimum":0,"description":"Still to go: sent straight after this answer."}},"required":["requested","sent","failed","queued"]}},"required":["created","skipped","email"],"description":"The invites made, each with its link, and the candidates skipped with why."},"CustomerToken":{"type":"object","properties":{"token":{"type":"string","description":"zct1.…: for this portal and one conversation only. Give it to the website widget or a conversation's start; never put it in a URL."},"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["token","expiresAt"],"description":"A short-lived identity token for one signed-in customer."},"CustomerTokenInput":{"type":"object","properties":{"customerId":{"type":"string","maxLength":128,"description":"Your own id for the signed-in customer: sent to your system as customer.id on every call."},"name":{"maxLength":80,"description":"Shown to them as \"Signed in as …\".","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"format":"email","anyOf":[{"type":"string"},{"type":"null"}]},"authTime":{"description":"When they signed in, seconds since 1970 (within the last 30 days).","anyOf":[{"type":"number"},{"type":"null"}]},"ttlSeconds":{"minimum":30,"default":600,"description":"How long the token lasts, in seconds. At most 900: a longer one is cut to 900 (expiresAt says when).","anyOf":[{"type":"number"},{"type":"null"}]},"contact":{"description":"Verified customer: the contact on record, where Zentiq sends a one-time code before a sensitive action (when the organisation switches it on). Signed into the token; never shown to the avatar, the conversation or a log, only as a masked read-back (\"s***@example.com\"). Use the address you would send a password reset to.","anyOf":[{"type":"object","properties":{"email":{"format":"email","description":"The customer's email address on record: where a one-time code is sent.","anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]}},"required":["customerId"],"description":"The customer signed in on your website."},"Dashboard":{"type":"object","description":"A Workspaces portal: the front door (address, sign-in methods) and its subjects, each built from a template.","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"]},"welcome":{"type":["string","null"]},"address":{"type":"string","description":"Where people open it: /d/<org>/<slug>, or the verified custom domain."},"loginMethods":{"type":"array","items":{"type":"string","enum":["email","login_card","class_code","visitor"]}},"personaId":{"type":["string","null"],"example":"pa_…"},"subjects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"The template's blueprint key."},"status":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"publishRefused":{"type":"string","description":"Only on a publish that was refused (POST /portals with publish: true, POST /portals/{id}/publish): what to finish before the portal can go live. The portal stays a draft."}}},"DashboardInput":{"type":"object","required":["name","templates"],"properties":{"name":{"type":"string","maxLength":80},"templates":{"type":"array","items":{"type":"string","example":"sales-trainer"},"minItems":1,"maxItems":12,"description":"Template keys from GET /portals/templates."},"personaId":{"type":"string","description":"A persona of yours to serve every subject; omitted = the portal gets its own."},"welcome":{"type":"string","maxLength":160},"loginMethods":{"type":"array","items":{"type":"string","enum":["email","login_card","class_code","visitor"]}},"publish":{"type":"boolean","default":false,"description":"true publishes it once it passes the go-live check; otherwise, or when the check refuses it (see publishRefused), it stays a draft."}}},"DashboardPersona":{"type":"object","properties":{"name":{"type":"string"},"face":{"type":["string","null"]},"voice":{"type":["string","null"]},"accent":{"type":["string","null"]},"greeting":{"type":["string","null"]},"character":{"type":"string"},"ready":{"type":"boolean","description":"true once it has a face and a voice: people can talk to it."}}},"DashboardTemplate":{"type":"object","properties":{"key":{"type":"string","example":"candidate-screening"},"group":{"type":"string","enum":["Learn","Train","Serve","Assess"]},"label":{"type":"string"},"description":{"type":"string"},"available":{"type":"boolean","description":"Whether it can be built today."}}},"Deleted":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}},"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"}}}},"Document":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^doc_.*","description":"Document id (`doc_…`).","examples":["doc_cmfq2b7x10000abcd1234"]},"knowledgeBaseId":{"type":"string","minLength":1,"pattern":"^kb_.*","description":"Knowledge base id (`kb_…`).","examples":["kb_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"pdf, txt, md, docx, csv, url or text."},"bytes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"status":{"type":"string","enum":["processing","ready","failed"],"description":"processing until it has been read; then ready, or failed."},"chunkCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many passages were read from it, once ready."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When failed: one plain sentence (the file couldn't be read, took too long, reading is unavailable, or it couldn't be processed)."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","knowledgeBaseId","name","type","bytes","status","chunkCount","error","createdAt","updatedAt"],"description":"A document in a knowledge pack."},"DocumentInput":{"type":"object","properties":{"url":{"format":"uri","description":"A public https address to fetch and read (25 MB at most; every redirect is checked too).","type":"string"},"text":{"maxLength":1048576,"description":"Text to read (1 MB at most).","type":"string"},"name":{"maxLength":200,"type":"string"}},"description":"A document from an address (`{ url }`) or as text (`{ text }`): exactly one."},"DocumentUpload":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"pdf, txt, md, docx or csv; 25 MB at most."},"name":{"type":"string"}},"required":["file"],"description":"A document as a file."},"DoorReadiness":{"type":"object","properties":{"open":{"type":"boolean"},"text":{"type":"string","description":"The readiness line, in plain words (\"Public page open\")."},"fix":{"anyOf":[{"type":"string","enum":["publish","visitors","organisation"]},{"type":"null"}],"description":"What to do when it is closed: publish the portal, open it to visitors, or let outside people in (the organisation's public website switch)."}},"required":["open","text","fix"]},"DownloadUrl":{"type":"object","properties":{"url":{"type":"string","description":"A short-lived signed address of the original file."},"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["url","expiresAt"],"description":"Where to download the original file, for a few minutes."},"Duo":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^duo_.*","description":"Duo id (`duo_…`).","examples":["duo_cmfq2b7x10000abcd1234"]},"personaId":{"type":"string","minLength":1,"pattern":"^pa_.*","description":"The persona sessions and portals use (its name is \"A & B\").","examples":["pa_cmfq2b7x10000abcd1234"]},"source":{"type":"string","enum":["library","generated","composed","upload"],"description":"Where its picture came from."},"libraryKey":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The ready-made duo it was copied from."},"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"gender":{"type":"string","enum":["female","male"]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Their part in the conversation, in a few words."},"voiceId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^vo_.*","description":"Voice id (`vo_…`).","examples":["vo_cmfq2b7x10000abcd1234"]},{"type":"null"}]}},"required":["name","gender","role","voiceId"]}},"relationship":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["draft","ready_for_render","registering","testing","live","needs_changes","failed"],"description":"draft, then ready_for_render once published; registering and testing on the render side; live when its test run passed, or needs_changes / failed."},"statusWords":{"type":"string","description":"Where it is, in one plain sentence."},"previewUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Its picture (your API key reads it: it is the organisation's own avatar)."},"languages":{"type":"array","items":{"type":"string"},"description":"The languages a duo speaks (the ten codes GET /languages marks `duo`)."},"testReasons":{"type":"array","items":{"type":"string"},"description":"Why its test run didn't pass, in plain words (needs_changes, failed)."},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: the duo's video and voices are AI-generated, and so is their picture unless it is a photo you uploaded (EU AI Act Article 50(2))."}},"required":["id","personaId","source","libraryKey","people","relationship","status","statusWords","previewUrl","languages","testReasons","updatedAt","aiGenerated"],"description":"A duo of the organisation's."},"DuoAccess":{"type":"object","properties":{"builderOpen":{"type":"boolean","description":"Duos are open to the organisation (while not, every other /duos operation is 404)."},"canUse":{"type":"boolean","description":"The plan uses ready-made duos."},"canBuild":{"type":"boolean","description":"The plan builds its own duos."},"upgrade":{"anyOf":[{"type":"object","properties":{"plan":{"type":"string"},"message":{"type":"string"}},"required":["plan","message"]},{"type":"null"}],"description":"The plan that would add what's missing, and the words for it; null when nothing is."}},"required":["builderOpen","canUse","canBuild","upgrade"],"description":"What the organisation may do with duos now."},"DuoInput":{"type":"object","properties":{"source":{"type":"string","const":"library","description":"A copy of one of Zentiq's ready-made duos (your own duos come in a later release)."},"libraryKey":{"type":"string","minLength":1,"description":"From GET /duos/library."}},"required":["source","libraryKey"],"description":"A new duo, as a draft."},"EmbedToken":{"type":"object","properties":{"token":{"type":"string","description":"Five minutes, single use."},"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"url":{"type":"string","description":"Opens the portal as that person (a full page)."},"embedUrl":{"type":"string","description":"What an iframe mounts (`zentiq-embed.js`, `@zentiq/react`'s `<ZentiqPortal>`)."}},"required":["token","expiresAt","url","embedUrl"],"description":"A one-time sign-in for one of your users."},"EmbedTokenInput":{"type":"object","properties":{"externalUserId":{"type":"string","minLength":1,"maxLength":120,"description":"Your own id for this person: the same person as `POST /people` with this `externalId`."},"name":{"type":"string","maxLength":80},"email":{"type":"string","maxLength":200},"role":{"description":"Default `learner`. A leader takes a staff seat.","type":"string","enum":["learner","leader","observer"]},"unitId":{"description":"Their team or class (`unit_…`).","type":"string"},"unitName":{"description":"Or a group by name, made under the portal's team on first sight.","type":"string","minLength":1,"maxLength":80},"gradeBand":{"type":"string","maxLength":8},"consent":{"description":"`{ by: \"organisation\" }`: your organisation attests the consent a young learner needs (recorded as yours; needs `people:write` as well). Without it, a learner under the consent age waits for a guardian's consent.","type":"object","properties":{"by":{"type":"string","const":"organisation"}},"required":["by"]}},"required":["externalUserId"],"description":"The person your backend signs in."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","consent_required","consent_invalid","consent_outdated","unauthorized","insufficient_minutes","forbidden","upgrade_required","feature_not_in_plan","account_paused","candidate_interview","learner_conversation","not_found","conflict","version_conflict","session_ended","duo_not_live","face_not_ready","consent_withdrawn","on_hold","idempotency_conflict","idempotency_in_progress","gone","too_large","unsupported_media_type","go_live_refused","rate_limited","concurrency_limit","server_error","upstream_error","capacity","consent_unverified","upstream_timeout"],"description":"What went wrong, from the error catalogue."},"message":{"type":"string","description":"Plain English, safe to show an admin."},"param":{"description":"The input at fault, as a path: `body.faqs[3].a`, `query.limit`, `params.id`.","type":"string"},"details":{"description":"Structured extras: a plan refusal's feature and plan (and `reason: plan_required` when the plan is why a feature's switch is off), a conflict's reason, go-live problems, the current version.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message"]}},"required":["error"],"description":"The error envelope. The request id is in the `X-Request-Id` header."},"Escalation":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^esc_.*","description":"Escalation id (`esc_…`).","examples":["esc_cmfq2b7x10000abcd1234"]},"url":{"type":"string","description":"The link to show the customer (or open in the widget). It works once, for 30 minutes; the token is in its fragment, never sent to a server."},"token":{"type":"string","description":"zesc_…: the link's own token (already in url). For one conversation only; never put it in a query string or a log."},"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","url","token","expiresAt"],"description":"A link that opens the video avatar with the chat so far."},"EscalationCompletedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"escalationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string","enum":["api","intercom","zendesk","widget"]},{"type":"null"}]},"externalRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"customerRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string","enum":["completed","abandoned"]},{"type":"null"}]},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"turnsHandedOver":{"anyOf":[{"type":"integer"},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"outcome":{"anyOf":[{"type":"string","enum":["resolved","handoff","booking","lead","unresolved","no_conversation"]},{"type":"null"}]},"resolved":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},"description":"A conversation your text chat handed to the video avatar ended: where it came from, your chat tool's ids, how long and the outcome. The summary only with includeConversation, where allowed."},"EscalationInput":{"type":"object","properties":{"transcript":{"type":"array","items":{"$ref":"#/components/schemas/ChatTurnInput"},"maxItems":50,"description":"The chat so far, oldest first: at most 50 turns and 20,000 characters in all (send the newest). The avatar reads it as information, never as instructions."},"customer":{"description":"The customer, when your chat knows them.","anyOf":[{"type":"object","properties":{"externalId":{"maxLength":128,"description":"Your own id for the customer: it comes back on escalation.completed as customerRef.","anyOf":[{"type":"string"},{"type":"null"}]},"firstName":{"maxLength":80,"description":"The avatar greets them by it.","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"format":"email","description":"Kept with the escalation only; never read out, never sent back.","anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"reason":{"maxLength":120,"description":"A short phrase finishing \"your chat about …\" (\"the refund on order 1042\"): the avatar opens with it.","anyOf":[{"type":"string"},{"type":"null"}]},"returnUrl":{"format":"uri","maxLength":2000,"description":"An https address the visitor is offered at the end (back to your chat).","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["transcript"],"description":"A chat to hand to the video avatar."},"Event":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^evt_.*","description":"`evt_…`: the webhook envelope's `id`, the same on every delivery.","examples":["evt_cmfq2b7x10000abcd1234"]},"type":{"type":"string"},"apiVersion":{"description":"From 2026-10-01: the contract `data` is written in.","type":"string","enum":["2026-07-08","2026-10-01"]},"organizationId":{"description":"From 2026-10-01.","type":"string","minLength":1,"pattern":"^org_.*","examples":["org_cmfq2b7x10000abcd1234"]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Exactly what a webhook with this key's rights receives (the event type's data schema; see GET /v1/event-types)."},"aiGenerated":{"description":"Present, and true, when `data` carries words an avatar wrote: a summary, a report or an avatar's turn (EU AI Act Article 50(2)). Every contract.","type":"boolean","const":true}},"required":["id","type","createdAt","data"],"description":"An event as a webhook receives it, in the calling key's contract."},"EventType":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"since":{"type":"string","enum":["2026-07-08","2026-10-01"],"description":"The contract it appeared in."},"explicitOnly":{"type":"boolean","description":"Never part of \"*\": a webhook receives it only by naming it."},"requiresConversation":{"type":"boolean","description":"Only for a webhook with includeConversation."},"fields":{"type":"object","properties":{"structure":{"type":"array","items":{"type":"string"}},"contact":{"type":"array","items":{"type":"string"}},"result":{"type":"array","items":{"type":"string"}},"conversation":{"type":"array","items":{"type":"string"}}},"required":["structure","contact","result","conversation"],"description":"`data`'s fields by class (`a.b`, `[]` a list's items): contact only on leads, bookings and hand-offs; result only for released results; conversation only with includeConversation, where allowed."},"dataSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"`data`'s JSON Schema in the current contract."}},"required":["type","description","since","explicitOnly","requiresConversation","fields","dataSchema"],"description":"One event type a webhook can receive."},"GoLiveProblem":{"type":"object","properties":{"field":{"type":"string","description":"Where it is in the content document (`faqs`, `screening.requirements[1]`, `facts`); `setup` for the set-up as a whole.","examples":["hours"]},"message":{"type":"string"},"short":{"type":"string","description":"A few words for a list."}},"required":["field","message","short"],"description":"Something to finish before going live."},"GuardianConsentInput":{"type":"object","properties":{"by":{"type":"string","enum":["organisation","guardian","teacher"],"description":"Who gave it: the organisation attests, a guardian gave it, a teacher recorded it on file."},"guardianEmail":{"description":"Kept on the place as evidence; never sent in any event or webhook.","anyOf":[{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"method":{"type":"string","minLength":1,"maxLength":40,"description":"How it was given: school_form, in_person, email, …","examples":["school_form"]},"evidenceRef":{"description":"Your own reference to the evidence.","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["by","method"]},"HandoffJoinedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"staffUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"via":{"anyOf":[{"type":"string","enum":["console","email","api"]},{"type":"null"}]},"staffCount":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"description":"Someone from your team joined a website visitor's live conversation as themselves (their user id, how they joined)."},"HandoffLeftData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"staffUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"seconds":{"anyOf":[{"type":"integer"},{"type":"null"}]},"next":{"anyOf":[{"type":"string","enum":["stayed","resumed","ended"]},{"type":"null"}]}},"description":"Someone from your team left a website visitor's live conversation: how long they were in it, and whether the assistant carried on or the conversation ended."},"HandoffRequestedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"need":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"budget":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"timeline":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"contact":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"company":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"role":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"preferredTime":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"location":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"reference":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}}},{"type":"null"}]},"consent":{"anyOf":[{"type":"object","properties":{"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"marketing":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"text":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"given":{"anyOf":[{"type":"boolean"},{"type":"null"}]}}},{"type":"null"}]},"promise":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"department":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"intent":{"anyOf":[{"type":"string"},{"type":"null"}]},"inboxItemId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A website visitor asked for a person: their contact details, what they need and their consent. The summary and reason only with includeConversation."},"HandoffUpdatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"need":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"budget":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"timeline":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"contact":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"company":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"role":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"preferredTime":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"location":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"reference":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}}},{"type":"null"}]},"consent":{"anyOf":[{"type":"object","properties":{"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"marketing":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"text":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"given":{"anyOf":[{"type":"boolean"},{"type":"null"}]}}},{"type":"null"}]},"promise":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"department":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"intent":{"anyOf":[{"type":"string"},{"type":"null"}]},"inboxItemId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A website visitor's request for a person gained their contact details after it was sent (they agreed and said how to reach them later in the conversation): the same fields as handoff.requested, with the same reference."},"Health":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"version":{"type":"string","const":"v1"}},"required":["status","version"],"description":"The API is up."},"InboxItem":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^inb_.*","description":"`inb_…`: the visitor's conversation (webhooks' `inboxItemId`).","examples":["inb_cmfq2b7x10000abcd1234"]},"sessionId":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"portalId":{"anyOf":[{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The portal the visitor came through, when known."},"subjectId":{"anyOf":[{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The subject's name when the request came in."},"reference":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The reference the visitor was given."},"receivedAt":{"type":"string","format":"date-time","description":"When the conversation's first request came in.","examples":["2026-09-25T12:00:00.000Z"]},"kinds":{"type":"array","items":{"type":"string","enum":["lead","booking","handoff"]}},"primary":{"type":"string","enum":["lead","booking","handoff"],"description":"What the item is mainly about: a booking, else a lead, else a hand-off."},"status":{"type":"string","enum":["new","contacted","confirmed","closed"]},"statusAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"statusBy":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key"]},"id":{"type":"string","description":"`usr_…` or `key_…`."}},"required":["type","id"]},{"type":"null"}],"description":"Who moved it last: a member, or an API key (yours included, so a sync can ignore its own changes)."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The team's note with the latest status."},"overdue":{"type":"boolean"},"dueAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When the visitor was promised an answer by."},"promise":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What the visitor was told about when they would hear back."},"contact":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferredTime":{"anyOf":[{"type":"string"},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","email","phone","company","role","location","preferredTime","reference"]},{"type":"null"}],"description":"The details the visitor gave, with their consent, for this request; payment and identity numbers are masked. Never an under-18's."},"team":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The team it went to."},"lead":{"anyOf":[{"type":"object","properties":{"band":{"anyOf":[{"type":"string"},{"type":"null"}]},"points":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["band","points"]},{"type":"null"}]},"booking":{"anyOf":[{"type":"object","properties":{"service":{"anyOf":[{"type":"string"},{"type":"null"}]},"when":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["service","when"]},{"type":"null"}],"description":"A booking request: nothing is in a calendar until someone confirms it with the visitor."},"consent":{"anyOf":[{"type":"object","properties":{"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"marketing":{"type":"boolean","const":false},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"at":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"given":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["purpose","marketing","version","at","given"]},{"type":"null"}],"description":"What the visitor agreed to: to be contacted about this request, never marketing."},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"false: some of the request was read only from the visitor's page (it could be made up); null: recorded before Zentiq checked."},"removedFields":{"type":"array","items":{"type":"string"},"description":"Details the visitor had removed; delete them from your records too."},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"need":{"description":"What they need, in their words. Only for a key holding `transcripts:read`, and never from an under-18's, a candidate's or a safety-flagged conversation (absent otherwise).","anyOf":[{"type":"string"},{"type":"null"}]},"budget":{"description":"Only for a key holding `transcripts:read`, and never from an under-18's, a candidate's or a safety-flagged conversation (absent otherwise).","anyOf":[{"type":"string"},{"type":"null"}]},"timeline":{"description":"Only for a key holding `transcripts:read`, and never from an under-18's, a candidate's or a safety-flagged conversation (absent otherwise).","anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"description":"The conversation's summary. Only for a key holding `transcripts:read`, and never from an under-18's, a candidate's or a safety-flagged conversation (absent otherwise).","anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"description":"Why they asked for a person. Only for a key holding `transcripts:read`, and never from an under-18's, a candidate's or a safety-flagged conversation (absent otherwise).","anyOf":[{"type":"string"},{"type":"null"}]},"answers":{"description":"A lead's answers to the qualification questions. Only for a key holding `transcripts:read`, and never from an under-18's, a candidate's or a safety-flagged conversation (absent otherwise).","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["id","sessionId","portalId","subjectId","subject","reference","receivedAt","kinds","primary","status","statusAt","statusBy","note","overdue","dueAt","promise","contact","team","lead","booking","consent","verified","removedFields","updatedAt"],"description":"A website visitor's request the team acts on: a lead, a booking request or a hand-off (one per conversation)."},"InboxItemUpdate":{"type":"object","properties":{"status":{"type":"string","enum":["new","contacted","confirmed","closed"]},"note":{"description":"The team's note with the new status (at most 500 characters).","type":"string","maxLength":500},"expectedStatus":{"description":"The status you last saw: when it has changed since, nothing changes (409 conflict, `details.currentStatus`).","type":"string","enum":["new","contacted","confirmed","closed"]}},"required":["status"],"additionalProperties":false,"description":"Move a request on. Records lead.updated or booking.updated with `by` = this key."},"InboxMoveData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"request":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"type":"string"},{"type":"null"}]},"by":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string","enum":["user","api_key"]},{"type":"null"}]},"id":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]}},"description":"A website visitor's request moved on in the inbox: its status, the one before, and who moved it."},"Invite":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^inv_.*","description":"Invite id (`inv_…`).","examples":["inv_cmfq2b7x10000abcd1234"]},"roleId":{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},"portalId":{"anyOf":[{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The portal whose door the link opens."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your ATS's own id for the applicant, sent back on every candidate event."},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Null once the candidate's data was erased."},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["invited","opened","started","completed","cancelled","expired"],"description":"invited → opened → started → completed; or cancelled (by the team, rescheduled, or a missed set time) or expired (a passed deadline)."},"cancelReason":{"anyOf":[{"type":"string","enum":["late","withdrawn_by_team","rescheduled"]},{"type":"null"}]},"timing":{"type":"string","enum":["open","deadline","scheduled"]},"startAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"scheduled: the interview time."},"opensAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"scheduled: when the link opens."},"lateAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"scheduled: not started by then, the invite is cancelled as late."},"deadlineAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"deadline: the interview must be started by then."},"sentAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When Zentiq last emailed it; null when the link was only copied."},"openedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"candidateId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^cand_.*","description":"Candidate id (`cand_…`).","examples":["cand_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The candidate (`cand_…`) once their interview reached the hiring team."},"link":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The candidate's personal link while it can be used: a secret, give it only to them."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","roleId","portalId","externalId","metadata","name","email","phone","status","cancelReason","timing","startAt","opensAt","lateAt","deadlineAt","sentAt","openedAt","startedAt","completedAt","cancelledAt","candidateId","link","createdAt"],"description":"A personal invitation to a role's first-round interview."},"InviteTiming":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"open"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"deadline"},"deadlineAt":{"type":"string","format":"date-time","description":"30 minutes to 90 days from now."}},"required":["mode","deadlineAt"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"scheduled"},"startAt":{"type":"string","format":"date-time","description":"In the future, within 90 days."},"earlyMinutes":{"description":"scheduled: how early the link opens (default 10).","type":"integer","minimum":0,"maximum":120},"lateMinutes":{"description":"scheduled: how late a start may be before the invite is cancelled (default 15).","type":"integer","minimum":1,"maximum":120}},"required":["mode","startAt"],"additionalProperties":false}],"description":"When candidates may take the interview: any time, by a deadline, or at a set time."},"JobCompletedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"jobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"subjectIds":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]}},"description":"A long-running job finished (the drafts it wrote, by id)."},"KeyInput":{"type":"object","properties":{"name":{"description":"Up to 60 characters. Default \"API key\".","type":"string"},"scopes":{"description":"Scope names, or [\"*\"] (the default, [] means the same) for full access. A key can only give scopes it holds itself.","maxItems":64,"type":"array","items":{"type":"string"}},"apiVersion":{"description":"The contract the new key speaks. Default: the contract of this request.","type":"string","enum":["2026-07-08","2026-10-01"]}}},"KeyList":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"KeyRevoked":{"type":"object","properties":{"revoked":{"type":"boolean","const":true},"id":{"type":"string","minLength":1,"pattern":"^key_.*","description":"API key id (`key_…`).","examples":["key_cmfq2b7x10000abcd1234"]}},"required":["revoked","id"],"description":"The key stops working on its next request."},"KeyWithSecret":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^key_.*","description":"API key id (`key_…`).","examples":["key_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"prefix":{"type":"string","description":"The key's first characters, as shown in the console.","examples":["zq_live_ab12"]},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes as set on the key; [] or [\"*\"] is full access (sensitive scopes are added by name)."},"apiVersion":{"type":"string","enum":["2026-07-08","2026-10-01"],"description":"The contract the key speaks."},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Who made it: a member (`usr_…`) or a key (`key_…`); null for older keys."},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"key":{"type":"string","description":"The full key. Returned once: store it now."}},"required":["id","name","prefix","scopes","apiVersion","createdBy","lastUsedAt","revokedAt","createdAt","key"],"description":"A new key, with its secret (shown once)."},"KnowledgeBase":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^kb_.*","description":"Knowledge base id (`kb_…`).","examples":["kb_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"documentCount":{"type":"integer","description":"Its documents (not deleted ones)."},"readyCount":{"type":"integer","description":"Its documents that have been read: the ones the avatar answers from."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","name","documentCount","readyCount","createdAt","updatedAt"],"description":"A knowledge pack: documents an avatar answers from once attached to its persona."},"KnowledgeBaseInput":{"type":"object","properties":{"name":{"type":"string","maxLength":200}},"required":["name"],"description":"A knowledge pack's name."},"KnowledgeDocumentFailedData":{"type":"object","properties":{"documentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"knowledgeBaseId":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string","enum":["The document could not be read. Check that it is a readable PDF, Word, text, Markdown or CSV file.","No text was found in the document. If it is a scan or a picture, upload a version with text you can select.","Processing the document took too long. Try a smaller file.","Document processing is unavailable right now. Try again later.","The document could not be processed."]},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"string","enum":["unreadable","empty","timeout","unavailable","failed"]},{"type":"null"}]}},"description":"A knowledge document could not be read; errorCode says why."},"KnowledgeDocumentProcessedData":{"type":"object","properties":{"documentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"knowledgeBaseId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chunkCount":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"description":"A knowledge document was read and is ready."},"KnowledgeGapData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"questions":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},{"type":"null"}]}},"description":"The assistant couldn't answer some questions (the questions only with includeConversation)."},"Language":{"type":"object","properties":{"code":{"type":"string","description":"BCP-47 code: what the API takes and returns.","examples":["pt-BR"]},"name":{"type":"string","description":"English name.","examples":["Portuguese (Brazil)"]},"nativeName":{"type":"string","description":"Its own name.","examples":["Português (Brasil)"]},"duo":{"type":"boolean","description":"A duo (two people in one conversation) speaks it: ten languages do."},"duoName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How a duo shows it (a duo has one Portuguese); null when a duo doesn't speak it."},"beta":{"type":"boolean","description":"Offered to one avatar in beta (Cantonese)."}},"required":["code","name","nativeName","duo","duoName","beta"],"description":"A language from the catalogue."},"Languages":{"type":"object","properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/Language"},"description":"Every language an avatar speaks, from the catalogue: one avatar any of them, a duo the ten flagged `duo`."},"engines":{"type":"object","properties":{"premier":{"$ref":"#/components/schemas/VoiceEngine"},"global":{"$ref":"#/components/schemas/VoiceEngine"}},"required":["premier","global"],"description":"The two voice engines."},"accents":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"]},"description":"Values for `settings.accent` that speak English with the accent of another language."}},"required":["languages","engines","accents"],"description":"The language catalogue, the voice engines and the accent keys."},"LeadCapturedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"need":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"budget":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"timeline":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"contact":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"company":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"role":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"preferredTime":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"location":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"reference":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}}},{"type":"null"}]},"consent":{"anyOf":[{"type":"object","properties":{"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"marketing":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"text":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"given":{"anyOf":[{"type":"boolean"},{"type":"null"}]}}},{"type":"null"}]},"promise":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]},"department":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadBand":{"anyOf":[{"type":"string"},{"type":"null"}]},"points":{"anyOf":[{"type":"number"},{"type":"null"}]},"answers":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},{"type":"null"}]},"inboxItemId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A website visitor left their details as a lead: contact details, the lead's band and their consent. The summary only with includeConversation."},"LearnerSignedInData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"method":{"anyOf":[{"type":"string"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A learner signed in to a portal."},"LibraryDuo":{"type":"object","properties":{"key":{"type":"string","description":"What POST /duos takes as `libraryKey`.","examples":["second_viewing"]},"title":{"type":"string","examples":["Mark & Susan"]},"scenario":{"anyOf":[{"type":"string"},{"type":"null"}]},"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"gender":{"type":"string","enum":["female","male"]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Their part in the conversation, in a few words."}},"required":["name","gender","role"]},"description":"The person on the left, then the one on the right."},"relationship":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"couple, colleagues, family or panel."},"previewUrl":{"type":"string","description":"Their picture (public)."},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: the duo's video and voices are AI-generated, and so is their picture unless it is a photo you uploaded (EU AI Act Article 50(2))."}},"required":["key","title","scenario","people","relationship","previewUrl","aiGenerated"],"description":"One of Zentiq's ready-made duos."},"LoginCard":{"type":"object","properties":{"username":{"type":"string"},"orgCode":{"type":"string"},"pin":{"type":"string","description":"Shown once, never again: print or hand it over now."}},"required":["username","orgCode","pin"],"description":"How a learner without an email signs in."},"MasteryUpdatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"skill":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"topic":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"before":{"anyOf":[{"type":"number"},{"type":"null"}]},"after":{"anyOf":[{"type":"number"},{"type":"null"}]},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}]}},"description":"A person's level on a skill moved."},"Me":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^org_.*","description":"Organisation id (`org_…`).","examples":["org_cmfq2b7x10000abcd1234"]},"displayName":{"type":"string","description":"The name the organisation chose for the API (never an internal workspace name)."},"plan":{"type":"string","description":"The plan's code (free, starter, plus, pro, business, enterprise).","examples":["pro"]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","displayName","plan","createdAt"]},"plan":{"type":"object","properties":{"key":{"type":"string","examples":["pro"]},"name":{"type":"string","examples":["Pro"]},"includedMinutes":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The plan's minutes this cycle; null on an unlimited account."},"features":{"type":"array","items":{"type":"string"},"description":"The plan's features that are on (dashboards.serve, embed.website, api.access, …).","examples":[["api.access","dashboards.serve","embed.website"]]}},"required":["key","name","includedMinutes","features"]},"limits":{"type":"object","properties":{"maxConcurrentSessions":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Live sessions at once; null = no limit."},"activeSessions":{"type":"integer"},"minutesRemaining":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Minutes the account can still spend (and within its own monthly API cap); null = unlimited."}},"required":["maxConcurrentSessions","activeSessions","minutesRemaining"]},"rateLimits":{"type":"object","properties":{"windowSeconds":{"type":"integer"},"perKey":{"type":"object","properties":{"read":{"type":"integer"},"write":{"type":"integer"},"live":{"type":"integer"},"heavy":{"type":"integer"},"search":{"type":"integer"}},"required":["read","write","live","heavy","search"],"description":"Requests per window, by operation class (each operation's class is in the reference as x-zentiq-rate-class)."},"perOrganization":{"type":"object","properties":{"read":{"type":"integer"},"write":{"type":"integer"},"live":{"type":"integer"},"heavy":{"type":"integer"},"search":{"type":"integer"}},"required":["read","write","live","heavy","search"],"description":"Shared by all of the organisation's keys."}},"required":["windowSeconds","perKey","perOrganization"],"description":"The rate limits this key works within (RateLimit-* headers on every answer)."},"apiKey":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^key_.*","description":"API key id (`key_…`).","examples":["key_cmfq2b7x10000abcd1234"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"type":"string","description":"The key's first characters, as shown in the console.","examples":["zq_live_ab12"]},"scopes":{"type":"array","items":{"type":"string"},"description":"The key's scopes as set on it; [] or [\"*\"] is full access."},"effectiveScopes":{"type":"array","items":{"type":"string"},"description":"Every scope the key holds, after full access and the implied scopes of keys made before 2026-10-01."},"fullAccess":{"type":"boolean"},"apiVersion":{"type":"string","enum":["2026-07-08","2026-10-01"],"description":"The contract the key is pinned to (Zentiq-Version may ask for a newer one)."},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","name","prefix","scopes","effectiveScopes","fullAccess","apiVersion","lastUsedAt","createdAt"]}},"required":["organization","plan","limits","rateLimits","apiKey"],"description":"The calling key, its organisation, plan and limits."},"MemberAddedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"method":{"anyOf":[{"type":"string"},{"type":"null"}]},"gradeBand":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"Someone was added to the organisation."},"MemberRemovedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"anyOf":[{"type":"string"},{"type":"null"}]},"roles":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]},"teams":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]},"accountDeactivated":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"Someone was removed."},"MemberStateData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"scope":{"anyOf":[{"type":"string"},{"type":"null"}]},"roles":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]},"membershipId":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A member, or one of their places, switched off or on."},"MemberUpdatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"membershipId":{"anyOf":[{"type":"string"},{"type":"null"}]},"from":{"anyOf":[{"type":"object","properties":{"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"to":{"anyOf":[{"type":"object","properties":{"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]}},"description":"A member's role or unit changed."},"Membership":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^mbr_.*","description":"Membership id (`mbr_…`).","examples":["mbr_cmfq2b7x10000abcd1234"]},"personId":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]},"role":{"type":"string","description":"One of the member roles."},"unitId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The unit it is held at; null at the organisation level."},"workspaceId":{"anyOf":[{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"A workspace admin's subject (`sub_…`; bare for keys on 2026-07-08)."},"status":{"type":"string","description":"active, waiting_consent (a child's place waiting for a parent's consent) or disabled.","examples":["active"]},"gradeBand":{"anyOf":[{"type":"string"},{"type":"null"}]},"ageBand":{"anyOf":[{"type":"string","enum":["18+"]},{"type":"null"}],"description":"`\"18+\"`: an adult learner, who starts without a parent's or guardian's consent."},"consentAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"consentBy":{"anyOf":[{"type":"string","enum":["organisation","guardian","teacher"]},{"type":"null"}],"description":"Who gave a learner's consent: the organisation, a guardian or a teacher (never their details)."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","personId","role","unitId","workspaceId","status","gradeBand","ageBand","consentAt","consentBy","createdAt","updatedAt"],"description":"A person's place: a role at a unit or at the organisation level."},"MemoryWrittenData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"skill":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"chars":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"description":"The platform noted something for a person's next session (what kind, never the note)."},"Person":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your own id for the person (the sync key), when you gave one."},"name":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Null for a login card or a person known only by your id."},"loginName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A login card's sign-in name (`<organisation code>/<username>`)."},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/Membership"}},"lastSignInAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"disabled":{"type":"boolean","description":"Switched off: no sign-in anywhere; their places keep their own status."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","externalId","name","email","loginName","memberships","lastSignInAt","disabled","createdAt","updatedAt"],"description":"Someone in the organisation: a member, a learner, a parent."},"PersonCreated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your own id for the person (the sync key), when you gave one."},"name":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Null for a login card or a person known only by your id."},"loginName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A login card's sign-in name (`<organisation code>/<username>`)."},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/Membership"}},"lastSignInAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"disabled":{"type":"boolean","description":"Switched off: no sign-in anywhere; their places keep their own status."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"loginCard":{"anyOf":[{"$ref":"#/components/schemas/LoginCard"},{"type":"null"}],"description":"Only on the answer that made the card; never replayed."}},"required":["id","externalId","name","email","loginName","memberships","lastSignInAt","disabled","createdAt","updatedAt","loginCard"],"description":"The person, and a new login card's PIN once."},"Persona":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"systemPrompt":{"type":"string"},"greeting":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^av_.*","description":"Avatar id (`av_…`).","examples":["av_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^vo_.*","description":"Voice id (`vo_…`).","examples":["vo_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"settings":{"$ref":"#/components/schemas/PersonaSettings"},"knowledge":{"anyOf":[{"$ref":"#/components/schemas/PersonaKnowledge"},{"type":"null"}]},"cast":{"type":"object","properties":{"kind":{"type":"string","enum":["single","duo"]},"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"One person, or a duo's two, by name."}},"required":["kind","people"],"description":"Who the avatar is: one person, or a duo (two people in one conversation)."},"duoId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^duo_.*","description":"Duo id (`duo_…`).","examples":["duo_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The duo (GET /duos/{id}) when it is one made from /duos; null otherwise."},"avatar":{"anyOf":[{"$ref":"#/components/schemas/Avatar"},{"type":"null"}]},"voice":{"anyOf":[{"$ref":"#/components/schemas/Voice"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","name","systemPrompt","greeting","avatarId","voiceId","settings","knowledge","cast","duoId","avatar","voice","createdAt","updatedAt"],"description":"An avatar people talk to: a face, a voice, a character and what it knows."},"PersonaInput":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"systemPrompt":{"type":"string","maxLength":16000,"description":"The character: who they are, what they help with, how they behave."},"greeting":{"maxLength":2000,"description":"The first thing they say.","anyOf":[{"type":"string"},{"type":"null"}]},"avatarId":{"description":"Avatar id (`av_…`).","type":"string"},"voiceId":{"description":"Voice id (`vo_…`).","type":"string"},"voiceProfileId":{"deprecated":true,"description":"Deprecated: use `voiceId`.","type":"string"},"settings":{"$ref":"#/components/schemas/PersonaSettingsInput"},"llmSettings":{"deprecated":true,"description":"Deprecated: use `settings`.","$ref":"#/components/schemas/PersonaSettingsInput"},"knowledge":{"anyOf":[{"type":"object","properties":{"baseIds":{"type":"array","items":{"type":"string"},"description":"Knowledge base ids (`kb_…`), 1 to 20."},"topK":{"type":"number"},"minScore":{"type":"number"},"maxChars":{"type":"number"}},"required":["baseIds"],"description":"Attach knowledge packs (replaces what is attached); null clears them."},{"type":"null"}]}},"required":["name","systemPrompt"],"description":"A new persona."},"PersonaKnowledge":{"type":"object","properties":{"baseIds":{"type":"array","items":{"type":"string","minLength":1,"pattern":"^kb_.*","description":"Knowledge base id (`kb_…`).","examples":["kb_cmfq2b7x10000abcd1234"]}},"topK":{"type":"integer"},"minScore":{"type":"number"},"maxChars":{"type":"integer"}},"required":["baseIds","topK","minScore"],"description":"The knowledge packs attached to a persona: the avatar answers from them."},"PersonaPatch":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"systemPrompt":{"type":"string","maxLength":16000,"description":"The character: who they are, what they help with, how they behave."},"greeting":{"maxLength":2000,"description":"The first thing they say.","anyOf":[{"type":"string"},{"type":"null"}]},"avatarId":{"description":"Avatar id (`av_…`).","type":"string"},"voiceId":{"description":"Voice id (`vo_…`).","type":"string"},"voiceProfileId":{"deprecated":true,"description":"Deprecated: use `voiceId`.","type":"string"},"settings":{"$ref":"#/components/schemas/PersonaSettingsInput"},"llmSettings":{"deprecated":true,"description":"Deprecated: use `settings`.","$ref":"#/components/schemas/PersonaSettingsInput"},"knowledge":{"anyOf":[{"type":"object","properties":{"baseIds":{"type":"array","items":{"type":"string"},"description":"Knowledge base ids (`kb_…`), 1 to 20."},"topK":{"type":"number"},"minScore":{"type":"number"},"maxChars":{"type":"number"}},"required":["baseIds"],"description":"Attach knowledge packs (replaces what is attached); null clears them."},{"type":"null"}]}},"description":"What to change; what isn't sent stays as it is."},"PersonaSettings":{"type":"object","properties":{"engine":{"type":"string","enum":["premier","global"],"description":"The voice engine the persona runs on, decided by its voice: premier for your organisation's cloned voices, global for the studio voices."},"globalVoice":{"description":"Deprecated: present when `engine` is global. Choose a voice by `voiceId`.","type":"string"},"language":{"type":"string","description":"The language it speaks first: a code from GET /languages.","examples":["en"]},"languageMode":{"type":"string","enum":["follow","fixed"],"description":"follow: it answers in the language people speak to it (starting in `language`); fixed: it keeps to `language`."},"accent":{"type":"string","description":"An accent for English, in words (\"Scottish\") or a key from GET /languages `accents`; \"\" for none."},"voice_accent":{"type":"string","description":"A studio voice's English accent variant (neutral is American)."},"skipGreeting":{"type":"boolean"},"interruptible":{"type":"boolean","description":"People can talk over it."},"cc":{"type":"boolean","description":"Captions shown by default."},"company":{"type":"string"},"greet_mode":{"type":"string","enum":["single","rotate","ai"]},"greetings":{"type":"array","items":{"type":"string"}},"idle_actions":{"type":"boolean","description":"Small natural movements between turns."},"display_mode":{"type":"string","enum":["half_body","presenter","full_body"],"description":"How the camera frames it."},"hand_motion":{"type":"boolean","description":"Hand gestures while speaking."},"vision":{"type":"boolean","description":"It may see the user's camera, when the user allows it."},"vision_safe_mode":{"type":"boolean","description":"Seeing, without reading emotions."},"ai_disclosure":{"type":"boolean","description":"Always true: every avatar tells people it's an AI (EU AI Act Article 50(1)), and it can't be switched off."},"ai_disclosure_text":{"type":"string","description":"Your own wording for the AI disclosure (it always says it's an AI); \"\" for the standard one, \"You're speaking with an AI avatar.\""}},"required":["engine","language","languageMode","accent","voice_accent","skipGreeting","interruptible","cc","company","greet_mode","greetings","idle_actions","display_mode","hand_motion","vision","vision_safe_mode","ai_disclosure","ai_disclosure_text"],"description":"Behaviour settings."},"PersonaSettingsInput":{"type":"object","properties":{"language":{"description":"A code or a name from GET /languages (a duo: one of its ten).","anyOf":[{"type":"string"},{"type":"null"}]},"languageMode":{"description":"follow: answer in the language people speak; fixed: keep to `language` (the default).","anyOf":[{"type":"string","enum":["follow","fixed"]},{"type":"null"}]},"accent":{"maxLength":60,"description":"An accent for English, in words, or a key from GET /languages `accents` (longer is cut at 60).","anyOf":[{"type":"string"},{"type":"null"}]},"voice_accent":{"anyOf":[{"type":"string","enum":["neutral","amgen","valley","south","rp","brixton","transat","aussie"]},{"type":"null"}]},"skipGreeting":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"interruptible":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cc":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"company":{"maxLength":80,"anyOf":[{"type":"string"},{"type":"null"}]},"greet_mode":{"anyOf":[{"type":"string","enum":["single","rotate","ai"]},{"type":"null"}]},"greetings":{"maxItems":10,"description":"Opening lines to choose from (the first 10, each cut at 200).","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"idle_actions":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"display_mode":{"anyOf":[{"type":"string","enum":["half_body","presenter","full_body"]},{"type":"null"}]},"hand_motion":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"vision":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"vision_safe_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"ai_disclosure":{"description":"Always true: every avatar tells people it's an AI (EU AI Act Article 50(1)), and it can't be switched off. Accepted for compatibility; false is ignored, and the persona reads back true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"ai_disclosure_text":{"maxLength":140,"examples":["You're talking to Maya, an AI assistant."],"description":"Your own wording for the AI disclosure. It must still say plainly that it's an AI (\"AI\", or \"artificial intelligence\" in the avatar's language), or the request is refused (400 invalid_request). \"\" = the default, \"You're speaking with an AI avatar.\"","anyOf":[{"type":"string"},{"type":"null"}]},"engine":{"deprecated":true,"description":"Read-only from 2026-10-01 (ignored): the voice decides the engine. Choose a voice by `voiceId`.","type":"string","enum":["premier","global"]},"globalVoice":{"deprecated":true,"description":"Read-only from 2026-10-01 (ignored). Keys on 2026-07-08 may still name a studio voice here when they send no `voiceId`.","type":"string"}},"description":"Behaviour settings to set (see PersonaSettings)."},"Portal":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"],"description":"`draft` until published; people only reach a published portal."},"group":{"anyOf":[{"type":"string","enum":["learn","train","serve","assess","mixed"]},{"type":"null"}],"description":"Its subjects' group, `mixed` when they differ; null without subjects."},"welcome":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"type":"string","description":"Where people open it: the sign-in page, or the verified custom domain."},"addresses":{"type":"object","properties":{"members":{"type":"string","description":"The sign-in page (`/d/<org>/<portal>`)."},"visitors":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The visitor page (`/v/<org>/<portal>`) when a subject opens to visitors; null otherwise."},"embed":{"type":"string","description":"What an iframe mounts, with `?t=<embed token>`."}},"required":["members","visitors","embed"]},"loginMethods":{"type":"array","items":{"type":"string","enum":["email","login_card","class_code","visitor"],"description":"How people come in: `email` (a link by email), `login_card` (username and PIN), `class_code`, `visitor` (open to visitors, no sign-in)."}},"unitId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The team or class it is for; null = the whole organisation."},"personaId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"Who speaks on it."},"brand":{"type":"object","properties":{"primary":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`#rrggbb`"},"logoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"anyOf":[{"type":"string","enum":["light","dark","system"]},{"type":"null"}]}},"required":["primary","logoUrl","mode"]},"domain":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"verified":{"type":"boolean"},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]}},"required":["name","verified","verifiedAt"]},{"type":"null"}],"description":"The organisation's own address for it, when one is set."},"subjects":{"type":"array","items":{"$ref":"#/components/schemas/PortalSubject"}},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"publishRefused":{"description":"Only when a publish was asked for and the go-live check refused it (`POST /portals` with `publish: true`; `POST /portals/{id}/publish` for keys on 2026-07-08): what to finish first. The portal stays a draft.","type":"string"}},"required":["id","name","slug","status","group","welcome","address","addresses","loginMethods","unitId","personaId","brand","domain","subjects","createdAt","updatedAt"],"description":"A portal: its doors, how people sign in, who speaks, and its subjects."},"PortalCreatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"subjects":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]},"via":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A portal was created."},"PortalDoors":{"type":"object","properties":{"members":{"type":"object","properties":{"url":{"type":"string","description":"The sign-in page."},"loginMethods":{"type":"array","items":{"type":"string","enum":["email","login_card","class_code","visitor"],"description":"How people come in: `email` (a link by email), `login_card` (username and PIN), `class_code`, `visitor` (open to visitors, no sign-in)."}},"unitId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},{"type":"null"}]}},"required":["url","loginMethods","unitId"]},"visitors":{"$ref":"#/components/schemas/VisitorsDoor"},"embed":{"type":"object","properties":{"url":{"type":"string","description":"What an iframe mounts, with `?t=` and a token from `POST /portals/{id}/embed-tokens`."},"script":{"type":"string","description":"The snippet for a signed-in embed (your backend gets the token)."}},"required":["url","script"]},"customDomain":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"verified":{"type":"boolean"},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]}},"required":["name","verified","verifiedAt"]},{"type":"null"}]}},"required":["members","visitors","embed","customDomain"],"description":"Every way in to a portal."},"PortalGoLive":{"type":"object","properties":{"ready":{"type":"boolean","description":"Publishing would go through."},"problems":{"type":"array","items":{"$ref":"#/components/schemas/PortalGoLiveProblem"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PortalGoLiveProblem"},"description":"Worth fixing; never a refusal."}},"required":["ready","problems","warnings"],"description":"What stops the portal going live, subject by subject."},"PortalGoLiveProblem":{"type":"object","properties":{"field":{"type":"string","description":"Where it is in the content document (`faqs`, `screening.requirements[1]`, `facts`); `setup` for the set-up as a whole.","examples":["hours"]},"message":{"type":"string"},"short":{"type":"string","description":"A few words for a list."},"subjectId":{"anyOf":[{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The subject it is about; null for something about the whole portal: its actions (`field` is `actions`) or its rehearsal before go-live (`field` is `rehearsal`)."},"subjectName":{"type":"string"}},"required":["field","message","short","subjectId","subjectName"],"description":"Something a subject still needs before the portal goes live."},"PortalInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"templates":{"description":"Template keys from `GET /portals/templates`; one subject each.","minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":60}},"template":{"description":"One template (the 2026-07-08 form of `templates`).","deprecated":true,"type":"string","minLength":1,"maxLength":60},"personaId":{"description":"A persona of yours to speak on every subject; left out = the portal gets its own.","type":"string"},"unitId":{"description":"The team or class it is for; left out or null = the whole organisation.","anyOf":[{"description":"Unit id (`unit_…`).","type":"string"},{"type":"null"}]},"welcome":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"loginMethods":{"minItems":1,"type":"array","items":{"type":"string","enum":["email","login_card","class_code","visitor"],"description":"How people come in: `email` (a link by email), `login_card` (username and PIN), `class_code`, `visitor` (open to visitors, no sign-in)."}},"publish":{"description":"Publish it once it passes the go-live check (needs `portals:publish`); otherwise it stays a draft and `publishRefused` says why.","type":"boolean"}},"required":["name"],"description":"A new portal. It starts as a draft."},"PortalPersona":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"face":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The face's name."},"voice":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The voice's name."},"avatarId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^av_.*","description":"Avatar id (`av_…`).","examples":["av_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^vo_.*","description":"Voice id (`vo_…`).","examples":["vo_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"accent":{"anyOf":[{"type":"string"},{"type":"null"}]},"greeting":{"anyOf":[{"type":"string"},{"type":"null"}]},"character":{"type":"string"},"language":{"type":"string","description":"The language it speaks (a name from `GET /languages`): English unless set."},"ready":{"type":"boolean","description":"It has a face and a voice: people can talk to it."}},"required":["id","name","face","voice","avatarId","voiceId","accent","greeting","character","language","ready"],"description":"Who speaks on a portal."},"PortalPersonaUpdate":{"type":"object","properties":{"avatarId":{"description":"A face (`av_…`) from `GET /avatars`.","type":"string"},"voiceId":{"description":"A voice (`vo_…`) from `GET /voices`.","type":"string"},"face":{"description":"A library face by first name (\"Marcus\"). Prefer `avatarId`.","deprecated":true,"type":"string","maxLength":40},"voice":{"description":"A studio voice by name (\"James\"). Prefer `voiceId`.","deprecated":true,"type":"string","maxLength":40},"accent":{"description":"In plain words (\"British\").","type":"string","maxLength":60},"character":{"description":"Who they are and how they behave, word for word (up to 4,000 characters; longer is 413).","type":"string"},"greeting":{"description":"Their first line (up to 300 characters).","type":"string"},"name":{"description":"Up to 80 characters.","type":"string"},"language":{"description":"The language it speaks: a name or code from `GET /languages` (\"German\", \"es\"); one it doesn't know is `400`. A duo speaks one of its ten.","type":"string","maxLength":80}},"description":"What to change about who speaks. A new face of the other gender brings a matching voice unless one is given."},"PortalSubject":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"template":{"type":"string","description":"The template it was built from (`custom` for one written for the organisation)."},"type":{"type":"string","description":"The same as `template` (its name in the 2026-07-08 contract)."},"kind":{"type":"string","enum":["tutor","roleplay","assessor","service"],"description":"What the avatar does: `tutor` teaches, `roleplay` plays someone to practise with, `assessor` asks and scores, `service` talks to website visitors."},"group":{"type":"string","enum":["learn","train","serve","assess"]},"screening":{"type":"boolean","description":"A candidate screening role."},"status":{"type":"string","enum":["draft","published","archived"]},"hasDraft":{"type":"boolean","description":"A draft version waits to be published (`POST /subjects/{id}/publish`)."}},"required":["id","name","template","type","kind","group","screening","status","hasDraft"],"description":"A subject on a portal."},"PortalTemplate":{"type":"object","properties":{"key":{"type":"string","description":"What `POST /portals` takes in `templates`.","examples":["sales-trainer"]},"group":{"type":"string","enum":["Learn","Train","Serve","Assess"]},"label":{"type":"string"},"description":{"type":"string"},"available":{"type":"boolean","description":"It can be built today."},"kind":{"type":"string","enum":["tutor","roleplay","assessor","service"],"description":"What the avatar does: `tutor` teaches, `roleplay` plays someone to practise with, `assessor` asks and scores, `service` talks to website visitors."},"duo":{"type":"boolean","description":"Written for two people in one conversation (needs a duo)."},"requires":{"type":"array","items":{"type":"string"},"description":"The plan features it needs (its portal family, candidate screening, ready-made duos).","examples":[["dashboards.train"]]},"includedInPlan":{"type":"boolean","description":"The organisation's plan has every feature it needs."}},"required":["key","group","label","description","available","kind","duo","requires","includedInPlan"],"description":"A template a portal's subjects are built from."},"PortalUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"welcome":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"loginMethods":{"description":"Adding `visitor` opens it to visitors: needs `portals:publish`, and runs the go-live check on a published portal.","minItems":1,"type":"array","items":{"type":"string","enum":["email","login_card","class_code","visitor"],"description":"How people come in: `email` (a link by email), `login_card` (username and PIN), `class_code`, `visitor` (open to visitors, no sign-in)."}},"unitId":{"anyOf":[{"description":"Unit id (`unit_…`).","type":"string"},{"type":"null"}]},"personaId":{"description":"One of your personas to speak on it instead of its own.","type":"string"},"brand":{"type":"object","properties":{"primary":{"description":"`#rrggbb` or a colour name (`green`); null goes back to the organisation's colour.","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"mode":{"anyOf":[{"type":"string","enum":["light","dark","system"]},{"type":"null"}]},"hideZentiqBadge":{"description":"Honoured when the plan includes removing the badge.","anyOf":[{"type":"boolean"},{"type":"null"}]}}}},"description":"The fields to change."},"PortalUpdatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"personaId":{"anyOf":[{"type":"string"},{"type":"null"}]},"fields":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"via":{"anyOf":[{"type":"string"},{"type":"null"}]},"added":{"anyOf":[{"type":"string"},{"type":"null"}]},"removed":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},{"type":"null"}]},"domain":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}]},"domainVerified":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}]},"allowedOrigins":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},{"type":"null"}]},"loginMethods":{"anyOf":[{"maxItems":10,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]},"tool":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A portal changed (which fields)."},"PracticeStartedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A person started a practice attempt."},"ReportProducedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"overall":{"anyOf":[{"type":"number"},{"type":"null"}]},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"practice":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"scenario":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]},"questionSet":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"string"},{"type":"null"}]},"held":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"screening":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"provisional":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"final":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"report":{"anyOf":[{"type":"object","properties":{"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"scores":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]}},{"type":"null"}]},"overall":{"anyOf":[{"type":"number"},{"type":"null"}]},"strengths":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},{"type":"null"}]},"workOn":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},{"type":"null"}]},"next":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"better":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},{"type":"null"}]},"mastery":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"skill":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"topic":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"level":{"anyOf":[{"type":"number"},{"type":"null"}]}}},{"type":"null"}]}},{"type":"null"}]},"delivery":{"anyOf":[{"type":"object","properties":{"learnerWords":{"anyOf":[{"type":"integer"},{"type":"null"}]},"avatarWords":{"anyOf":[{"type":"integer"},{"type":"null"}]},"talkShare":{"anyOf":[{"type":"number"},{"type":"null"}]},"questionsAsked":{"anyOf":[{"type":"integer"},{"type":"null"}]},"fillerWords":{"anyOf":[{"type":"integer"},{"type":"null"}]},"fillerPerHundred":{"anyOf":[{"type":"number"},{"type":"null"}]},"longestTurnWords":{"anyOf":[{"type":"integer"},{"type":"null"}]},"turns":{"anyOf":[{"type":"integer"},{"type":"null"}]},"paceWpm":{"anyOf":[{"type":"number"},{"type":"null"}]},"topFillers":{"anyOf":[{"maxItems":20,"type":"array","items":{"anyOf":[{"type":"object","properties":{"word":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"count":{"anyOf":[{"type":"integer"},{"type":"null"}]}}},{"type":"null"}]}},{"type":"null"}]}}},{"type":"null"}]},"assessment":{"anyOf":[{"type":"object","properties":{"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"marks":{"anyOf":[{"type":"number"},{"type":"null"}]},"outOf":{"anyOf":[{"type":"number"},{"type":"null"}]},"passMark":{"anyOf":[{"type":"number"},{"type":"null"}]},"practice":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"review":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"humanReview":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"certificate":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"criticalFail":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"items":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"n":{"anyOf":[{"type":"integer"},{"type":"null"}]},"questionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"verdict":{"anyOf":[{"type":"string"},{"type":"null"}]},"marks":{"anyOf":[{"type":"number"},{"type":"null"}]},"outOf":{"anyOf":[{"type":"number"},{"type":"null"}]},"redFlag":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hints":{"anyOf":[{"type":"integer"},{"type":"null"}]}}},{"type":"null"}]}},{"type":"null"}]}}},{"type":"null"}]},"visitor":{"anyOf":[{"type":"object","properties":{"intent":{"anyOf":[{"type":"string"},{"type":"null"}]},"topics":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},{"type":"null"}]},"answered":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"object","properties":{"q":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"a":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]}}},{"type":"null"}]}},{"type":"null"}]},"consent":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"handoff":{"anyOf":[{"type":"object","properties":{"needed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"department":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]},"booking":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"leadScore":{"anyOf":[{"type":"string"},{"type":"null"}]},"resolved":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"points":{"anyOf":[{"type":"number"},{"type":"null"}]},"unanswered":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},{"type":"null"}]},"forgotten":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]}}},{"type":"null"}]},"outcome":{"anyOf":[{"type":"object","properties":{"agreed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"issues":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"unit":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"beyondWalkAway":{"anyOf":[{"type":"boolean"},{"type":"null"}]}}},{"type":"null"}]}},{"type":"null"}]}}},{"type":"null"}]},"critical":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"quote":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}}},{"type":"null"}]}},{"type":"null"}]},"practiceNote":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"omitted":{"anyOf":[{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]},"scenario":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]},"questionSet":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]}},"description":"A session's report is ready: numbers once released; its words only with includeConversation, where allowed. Never for a candidate."},"ResponseTimes":{"type":"object","properties":{"p50Ms":{"type":"integer","description":"The typical wait in milliseconds: half the answers started sooner.","examples":[1900]},"p90Ms":{"type":"integer","description":"Nine answers in ten started within this many milliseconds.","examples":[2600]},"maxMs":{"type":"integer","description":"The slowest answer's wait, in milliseconds.","examples":[3400]},"turns":{"type":"integer","description":"How many turns were timed. Turns that couldn't be timed fairly (talking over each other, a page in the background, a reconnect) aren't counted.","examples":[12]}},"required":["p50Ms","p90Ms","maxMs","turns"],"description":"How long the avatar took to start answering each turn, measured in the person's browser from when they stopped speaking or sent a typed line to the avatar's first sound. Only where the organisation measures response times (Settings, Features: \"Measure how fast the avatar answers\"), and only on Zentiq's own session pages (a portal's sessions, your website avatar's conversations): a session your own app shows isn't timed, and a builder's preview never is."},"Result":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^res_.*","description":"`res_` + the session's id.","examples":["res_cmfq2b7x10000abcd1234"]},"sessionId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The portal it was started from (`portal_…`; bare for keys on 2026-07-08)."},"subjectId":{"anyOf":[{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"`sub_…` (bare for keys on 2026-07-08)."},"subjectName":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What the subject is: assessor, roleplay, tutor, …","examples":["roleplay"]},"person":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your own id for them; only for a key holding people:read."}},"required":["id","externalId"]},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"integer"},{"type":"null"}]},"scored":{"type":"boolean","description":"A scored attempt (an assessment); its numbers follow the released rule."},"release":{"type":"string","enum":["not_scored","awaiting_review","reviewers_only","voided","released"],"description":"not_scored (a role-play, a lesson: its numbers are the report's); awaiting_review (a reviewer still decides it); reviewers_only (results go to the person through a reviewer only); voided; released."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"0-100: the released percent of a scored attempt, else the report's overall. Null while not released."},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"passMark":{"anyOf":[{"type":"number"},{"type":"null"}]},"scenario":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"]},{"type":"null"}]},"questionSet":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"]},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"string"},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"score":{"type":"number"}},"required":["id","label","score"]},"description":"The rubric's categories with evidence, 0-100. Empty while not released."},"review":{"anyOf":[{"type":"object","properties":{"decision":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"confirm, pass, not_yet or void."},"decidedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"reviewer":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]}},"required":["id"]},{"type":"null"}]},"corrected":{"type":"boolean","description":"The reviewer corrected marks."}},"required":["decision","decidedAt","reviewer","corrected"]},{"type":"null"}],"description":"A reviewer's decision; null while the result is held for a reviewer or kept from the person (it would say pass or fail)."},"contest":{"anyOf":[{"type":"object","properties":{"at":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"open":{"type":"boolean"}},"required":["at","open"]},{"type":"null"}],"description":"The person asked for another look (never their words)."},"certificate":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^cert_.*","description":"Certificate id (`cert_…`).","examples":["cert_cmfq2b7x10000abcd1234"]},"number":{"type":"string"},"status":{"type":"string","enum":["valid","expired","withdrawn"]},"validUntil":{"anyOf":[{"type":"string"},{"type":"null"}]},"verifyUrl":{"type":"string"}},"required":["id","number","status","validUntil","verifyUrl"]},{"type":"null"}],"description":"The certificate; null while the result is held for a reviewer or kept from the person."},"completion":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["recorded","withdrawn"]},"at":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["status","at"]},{"type":"null"}],"description":"The completion record; null while the result is held for a reviewer or kept from the person."},"reportAvailable":{"type":"boolean","description":"A written report exists (GET /results/{id}/report, with transcripts:read, where the rules allow the words)."},"erased":{"type":"boolean","description":"The retention job took the conversation's words out."},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","sessionId","portalId","subjectId","subjectName","kind","person","unitId","startedAt","endedAt","durationSeconds","scored","release","score","percent","passed","passMark","scenario","questionSet","difficulty","categories","review","contest","certificate","completion","reportAvailable","erased","updatedAt"],"description":"A session's result: numbers only (never the summary, feedback, evidence, answers, flags or notes). Practice attempts, candidates' interviews and other job interviews are never results here."},"ResultContestedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"questionSet":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},{"type":"null"}]}},"description":"A person asked for their result to be looked at again."},"ResultReport":{"type":"object","properties":{"resultId":{"type":"string","minLength":1,"pattern":"^res_.*","description":"Result id (`res_…`).","examples":["res_cmfq2b7x10000abcd1234"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"strengths":{"type":"array","items":{"type":"string"}},"workOn":{"type":"array","items":{"type":"string"}},"next":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["resultId","summary","strengths","workOn","next"],"description":"The report's words, where the conversation's rules allow them."},"ReviewCompletedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"decision":{"anyOf":[{"type":"string"},{"type":"null"}]},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"voided":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"marks":{"anyOf":[{"type":"number"},{"type":"null"}]},"outOf":{"anyOf":[{"type":"number"},{"type":"null"}]},"passMark":{"anyOf":[{"type":"number"},{"type":"null"}]},"ai":{"anyOf":[{"type":"object","properties":{"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"marks":{"anyOf":[{"type":"number"},{"type":"null"}]}}},{"type":"null"}]},"reviewerId":{"anyOf":[{"type":"string"},{"type":"null"}]},"reportId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contested":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"before":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"final":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"incomplete":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A person decided a result under review."},"ReviewRequestedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"passMark":{"anyOf":[{"type":"number"},{"type":"null"}]}},"description":"A result waits for a person's review (why, never the score)."},"Role":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The role is a screening subject (`sub_…`); edit its content through /subjects/{id}/content.","examples":["sub_cmfq2b7x10000abcd1234"]},"title":{"type":"string","description":"The job being hired for (the screening block's role), or the subject's name while it has none."},"subjectName":{"type":"string"},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"market":{"anyOf":[{"type":"string","enum":["us","uk","eu"]},{"type":"null"}],"description":"Where the role hires (its own, or the organisation's country): us, uk or eu. Null while unpublished."},"status":{"type":"string","enum":["draft","published","archived"]},"portalIds":{"type":"array","items":{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]}},"timing":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["open","deadline","scheduled"]},"deadlineDays":{"anyOf":[{"type":"integer"},{"type":"null"}]},"earlyMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"lateMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["mode","deadlineDays","earlyMinutes","lateMinutes"]},{"type":"null"}],"description":"The role's default timing for new invites; null when it sets none."},"closesOn":{"anyOf":[{"type":"string","format":"date","description":"A calendar date (YYYY-MM-DD).","examples":["2026-09-25"]},{"type":"null"}],"description":"Applications close at the end of this day (the role's time zone); no invite may start after it."},"bands":{"anyOf":[{"type":"object","properties":{"strong":{"type":"number"},"possible":{"type":"number"}},"required":["strong","possible"]},{"type":"null"}],"description":"The score bands the hiring team sorts by (a sorting aid, never a verdict)."},"rounds":{"type":"array","items":{"type":"object","properties":{"round":{"type":"integer","minimum":1},"version":{"type":"integer","minimum":1,"description":"The first published version of the role in this round."},"changed":{"type":"array","items":{"type":"string","enum":["set","questions","level","bands","mustHaves"]},"description":"What changed from the round before: the question set, the questions, the level, the bands or the must-haves."}},"required":["round","version","changed"]},"description":"Rounds of the interview candidates took: scores compare only within a round."},"latestRound":{"anyOf":[{"type":"integer"},{"type":"null"}]},"reviewsRequired":{"type":"integer","minimum":0,"description":"Reviews a decision waits for (switch candidates.reviews_required); a decline waits for at least one."},"blindReview":{"type":"boolean"},"shareScores":{"type":"boolean","description":"Switch candidates.share_scores: whether candidates' score, band and rank are given out through the API. Off by default. Never by webhook."},"hold":{"type":"boolean","description":"A legal hold is on the whole role: nothing about its candidates is erased while it is on."},"door":{"anyOf":[{"type":"object","properties":{"portalId":{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},"url":{"type":"string"},"open":{"type":"boolean"}},"required":["portalId","url","open"]},{"type":"null"}],"description":"The interview link a job advert carries (a portal's visitor door), open once it is published and open to visitors."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","title","subjectName","location","market","status","portalIds","timing","closesOn","bands","rounds","latestRound","reviewsRequired","blindReview","shareScores","hold","door","createdAt","updatedAt"],"description":"A screening role: the subject candidates are interviewed on."},"SayInput":{"type":"object","properties":{"text":{"type":"string","description":"Up to 2,000 characters."},"interrupt":{"description":"Cut off any speech in progress first (default true).","anyOf":[{"type":"boolean"},{"type":"null"}]},"language":{"description":"The line's language: one of GET /languages. Default: the session's.","anyOf":[{"type":"string"},{"type":"null"}]},"turnId":{"description":"External turn mode: the turn this line answers.","anyOf":[{"type":"string"},{"type":"null"}]},"eventId":{"description":"External turn mode: makes a redelivered line idempotent.","anyOf":[{"type":"string"},{"type":"null"}]},"endSession":{"description":"External turn mode: end the session after this line.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["text"]},"ScoreRecordedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"scores":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]}},{"type":"null"}]}},"description":"A released score for a person's session."},"SearchInput":{"type":"object","properties":{"query":{"type":"string","maxLength":4096},"topK":{"description":"How many passages (default 5).","type":"integer","minimum":1,"maximum":50},"minScore":{"description":"Leave out passages below this similarity (0-1, default 0).","type":"number","minimum":0,"maximum":1}},"required":["query"],"description":"What to look for."},"SearchResult":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"documentId":{"type":"string","minLength":1,"pattern":"^doc_.*","description":"Document id (`doc_…`).","examples":["doc_cmfq2b7x10000abcd1234"]},"text":{"type":"string"},"score":{"type":"number","description":"0-1 similarity (higher is closer)."},"metadata":{"type":"object","properties":{"page":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["page"]}},"required":["documentId","text","score","metadata"]}}},"required":["results"],"description":"The closest passages, best first."},"Session":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"personaId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The persona that spoke (`pa_…`)."},"status":{"type":"string","enum":["ACTIVE","COMPLETED","ABANDONED"],"description":"ACTIVE while live; COMPLETED or ABANDONED once ended."},"source":{"type":"string","description":"Where it started: api, portal, visitor, playground, demo or guide.","examples":["api"]},"turnMode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`external` when your app owns every avatar turn (autoRespond false); null otherwise."},"autoRespond":{"type":"boolean","description":"False when the avatar only speaks the lines your app sends (POST /sessions/{id}/say)."},"room":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The realtime room, while it has one."},"minutesBilled":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Minutes charged once the session ended; null while live."},"startedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"endedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"duration":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Seconds, once ended."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"mode":{"type":"string","description":"AVATAR (a talking avatar), VOICE_CALL or CHAT (typed).","examples":["AVATAR"]},"subjectId":{"anyOf":[{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The portal subject it ran in (`sub_…`; bare for keys on 2026-07-08); null for a persona session."},"kind":{"type":"string","enum":["persona","subject","visitor"],"description":"A persona session (your app's, or the console's), a lesson or role-play in a subject, or a website visitor's conversation."},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: the avatar's video, voice and words are AI-generated (EU AI Act Article 50(2)). Keep this marker with the content when you store or pass it on."},"responseTimes":{"anyOf":[{"$ref":"#/components/schemas/ResponseTimes"},{"type":"null"}],"description":"How fast the avatar started answering, once the session ended; null when it wasn't measured."}},"required":["id","personaId","status","source","turnMode","autoRespond","room","minutesBilled","startedAt","endedAt","duration","createdAt","mode","subjectId","kind","aiGenerated","responseTimes"],"description":"A live conversation with a persona."},"SessionAnalytics":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"status":{"type":"string"},"source":{"type":"string"},"duration":{"type":"object","properties":{"seconds":{"type":"integer"},"live":{"type":"boolean"},"startedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"endedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]}},"required":["seconds","live","startedAt","endedAt"]},"billing":{"type":"object","properties":{"rate":{"type":"number"},"billedSeconds":{"type":"integer"},"billedMinutes":{"type":"number"},"ledger":{"type":"object","properties":{"chargedSeconds":{"type":"integer"},"absorbedSeconds":{"type":"integer"},"unmeteredSeconds":{"type":"integer"},"wallSeconds":{"type":"integer"},"entries":{"type":"integer"}},"required":["chargedSeconds","absorbedSeconds","unmeteredSeconds","wallSeconds","entries"],"description":"The minutes ledger entries for this session."}},"required":["rate","billedSeconds","billedMinutes","ledger"]},"turns":{"type":"object","properties":{"total":{"type":"integer"},"user":{"type":"integer"},"avatar":{"type":"integer"}},"required":["total","user","avatar"]},"talkShare":{"type":"object","properties":{"method":{"anyOf":[{"type":"string","enum":["word_timings","word_count"]},{"type":"null"}]},"user":{"anyOf":[{"type":"number"},{"type":"null"}]},"avatar":{"anyOf":[{"type":"number"},{"type":"null"}]},"userWords":{"type":"integer"},"avatarWords":{"type":"integer"},"userSpeechMs":{"anyOf":[{"type":"integer"},{"type":"null"}]},"avatarSpeechMs":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["method","user","avatar","userWords","avatarWords","userSpeechMs","avatarSpeechMs"]},"timing":{"type":"object","properties":{"turnTimestamps":{"type":"boolean"},"wordTimings":{"type":"boolean"},"userToAvatarMs":{"anyOf":[{"type":"object","properties":{"median":{"type":"integer"},"p90":{"type":"integer"},"samples":{"type":"integer"}},"required":["median","p90","samples"]},{"type":"null"}],"description":"Time between a person's turn being recorded and the avatar's reply being recorded. Not a pure response latency: turns are timestamped when they are stored."},"turns":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"role":{"type":"string","enum":["user","avatar"]},"speaker":{"description":"A duo's speaker.","type":"string"},"atMs":{"anyOf":[{"type":"integer"},{"type":"null"}]},"words":{"type":"integer"},"speechMs":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sincePreviousMs":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["index","role","atMs","words","speechMs","sincePreviousMs"]}}},"required":["turnTimestamps","wordTimings","userToAvatarMs","turns"]},"interruptions":{"type":"null","description":"Not recorded yet."},"clientMetrics":{"anyOf":[{"type":"object","properties":{"paceWpm":{"anyOf":[{"type":"number"},{"type":"null"}]},"talkListenRatio":{"anyOf":[{"type":"number"},{"type":"null"}]},"fillerWordsPerMinute":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["paceWpm","talkListenRatio","fillerWordsPerMinute"]},{"type":"null"}]},"candidate":{"type":"boolean","description":"A candidate's screening interview: report and summary are always null."},"report":{"anyOf":[{"type":"object","properties":{"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"overall":{"anyOf":[{"type":"number"},{"type":"null"}]},"percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"producedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["kind","summary","score","overall","percent","passed","producedAt"]},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"disclosure":{"anyOf":[{"type":"object","properties":{"required":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"method":{"anyOf":[{"type":"string"},{"type":"null"}]},"recordedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["required","text","method","recordedAt"]},{"type":"null"}]},"notRecorded":{"type":"array","items":{"type":"string"},"examples":[["speech_recognition_latency","model_latency","speech_synthesis_latency","interruptions"]]},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: the avatar's video, voice and words are AI-generated (EU AI Act Article 50(2)). Keep this marker with the content when you store or pass it on."}},"required":["sessionId","status","source","duration","billing","turns","talkShare","timing","interruptions","clientMetrics","candidate","report","summary","disclosure","notRecorded","aiGenerated"],"description":"Only recorded data: speech-recognition, model and speech-synthesis timings and interruptions are not recorded and are listed in `notRecorded`."},"SessionAnalyticsSummary":{"type":"object","properties":{"durationSeconds":{"type":"integer"},"billedMinutes":{"type":"number"},"billedSeconds":{"type":"integer"},"billingRate":{"type":"number","description":"Billable seconds per wall-clock second, fixed when the session started."},"turnCount":{"type":"integer"},"talkShare":{"type":"object","properties":{"user":{"anyOf":[{"type":"number"},{"type":"null"}]},"avatar":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user","avatar"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The report's short summary, or a transcript summary already made in the portal: conversation words, so only where the transcript may be read (never a candidate's interview, a young learner's conversation or a website visitor's who said they are under 18)."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The report's score, when it has one."}},"required":["durationSeconds","billedMinutes","billedSeconds","billingRate","turnCount","talkShare","summary","score"],"description":"The short analytics GET /sessions/{id} carries."},"SessionDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"personaId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The persona that spoke (`pa_…`)."},"status":{"type":"string","enum":["ACTIVE","COMPLETED","ABANDONED"],"description":"ACTIVE while live; COMPLETED or ABANDONED once ended."},"source":{"type":"string","description":"Where it started: api, portal, visitor, playground, demo or guide.","examples":["api"]},"turnMode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`external` when your app owns every avatar turn (autoRespond false); null otherwise."},"autoRespond":{"type":"boolean","description":"False when the avatar only speaks the lines your app sends (POST /sessions/{id}/say)."},"room":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The realtime room, while it has one."},"minutesBilled":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Minutes charged once the session ended; null while live."},"startedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"endedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"duration":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Seconds, once ended."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"mode":{"type":"string","description":"AVATAR (a talking avatar), VOICE_CALL or CHAT (typed).","examples":["AVATAR"]},"subjectId":{"anyOf":[{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The portal subject it ran in (`sub_…`; bare for keys on 2026-07-08); null for a persona session."},"kind":{"type":"string","enum":["persona","subject","visitor"],"description":"A persona session (your app's, or the console's), a lesson or role-play in a subject, or a website visitor's conversation."},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: the avatar's video, voice and words are AI-generated (EU AI Act Article 50(2)). Keep this marker with the content when you store or pass it on."},"responseTimes":{"anyOf":[{"$ref":"#/components/schemas/ResponseTimes"},{"type":"null"}],"description":"How fast the avatar started answering, once the session ended; null when it wasn't measured."},"analytics":{"anyOf":[{"$ref":"#/components/schemas/SessionAnalyticsSummary"},{"type":"null"}]}},"required":["id","personaId","status","source","turnMode","autoRespond","room","minutesBilled","startedAt","endedAt","duration","createdAt","mode","subjectId","kind","aiGenerated","responseTimes","analytics"],"description":"A session with its short analytics (the full breakdown is GET /sessions/{id}/analytics)."},"SessionEndedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"personaId":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"billedMinutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAssignments":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},{"type":"null"}]},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"self":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"withheld":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"withdrawn":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"incomplete":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"unverified":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"reaped":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"voided":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},"description":"A session ended, once: its length and minutes. Its summary only with includeConversation, where allowed."},"SessionStartedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"personaId":{"anyOf":[{"type":"string"},{"type":"null"}]},"identity":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"self":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"portalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"focus":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"string"},{"type":"null"}]},"bootstrap":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"assignments":{"anyOf":[{"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},{"type":"null"}]}},"description":"A live session started: an API session, or a member's session on a portal (never its plan)."},"SessionToken":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"sessionToken":{"type":"string","description":"Short-lived client token (15 minutes) for the realtime room."},"url":{"type":"string","description":"The realtime transport URL."},"room":{"type":"string"},"persona":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},"name":{"type":"string","description":"The name the avatar hears. Only a duo's carries \" & \" (\"Mark & Susan\"); a single persona named \"Smith & Jones\" comes back as \"Smith and Jones\"."}},"required":["id","name"]},"disclosure":{"type":"object","properties":{"required":{"type":"boolean","description":"Always true: the AI disclosure can't be switched off."},"text":{"type":"string","description":"The notice to show when the session starts, in the session's language (the persona's own wording when it has one).","examples":["You're speaking with an AI avatar."]},"label":{"type":"string","description":"The short label to keep on or right next to the avatar's video for the whole session, in the session's language (the persona's own wording when it has one). The browser and React SDKs draw it for you.","examples":["AI avatar"]},"language":{"type":"string","description":"The language of `label` and `text`, as a code.","examples":["en"]},"display":{"type":"string","const":"whole_session","description":"When the label shows: for the whole session."},"rule":{"type":"string","description":"What your app must do, in plain words: keep the label visible for the whole session and show the notice at the start. You may restyle or move it, never remove, hide or cover it."},"ownLabel":{"type":"boolean","description":"True only when an owner of your organisation has confirmed, in the console, that your app shows its own AI label for the whole of every session. Only then may the SDKs' own label be hidden."}},"required":["required","text","label","language","display","rule","ownLabel"],"description":"The AI disclosure (EU AI Act Article 50): keep `label` visible on or next to the avatar's video for the whole session and show `text` at its start. Recorded against the session."},"cc":{"type":"boolean","description":"The persona's caption preference. The transcript always streams on the data topic \"chat\"; cc is a render hint."},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: the avatar's video, voice and words are AI-generated (EU AI Act Article 50(2)). Keep this marker with the content when you store or pass it on."}},"required":["sessionId","sessionToken","url","room","persona","disclosure","cc","aiGenerated"],"description":"What your app needs to join the session."},"SessionTokenInput":{"type":"object","properties":{"personaId":{"type":"string","minLength":1,"description":"The persona to start (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},"identity":{"description":"Your end user's id (optional): the participant identity in the room.","anyOf":[{"type":"string"},{"type":"null"}]},"language":{"description":"Per-session spoken-language override: one of GET /languages, as a code or the name.","anyOf":[{"type":"string"},{"type":"null"}]},"languageMode":{"description":"How this session keeps its language: `follow` switches to the person's language when they use another; `fixed` answers in the session's language anyway. Default: the persona's own setting.","anyOf":[{"type":"string","enum":["follow","fixed"]},{"type":"null"}]},"overrides":{"anyOf":[{"type":"object","properties":{"systemPrompt":{"description":"Replaces the persona's prompt for this session (up to 16,000 characters).","anyOf":[{"type":"string"},{"type":"null"}]},"greeting":{"description":"Replaces the greeting (up to 2,000 characters); an empty string means no greeting.","anyOf":[{"type":"string"},{"type":"null"}]},"variables":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Fills {{name}} placeholders in the prompt and greeting."},{"type":"null"}]}}},{"type":"null"}]},"autoRespond":{"description":"false: your app owns every avatar turn; the avatar only speaks the greeting and the lines you send with say.","anyOf":[{"type":"boolean"},{"type":"null"}]},"turnMode":{"description":"`{ mode: \"external\" }` is the same as autoRespond false.","anyOf":[{"type":"object","properties":{"mode":{"type":"string"}},"additionalProperties":{}},{"type":"null"}]}},"required":["personaId"]},"SessionTranscriptReadyData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"personaId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A session's whole transcript can be read with GET /v1/sessions/{id}/transcript (ids only; only where the API may read it)."},"SettingChangedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"key":{"anyOf":[{"type":"string"},{"type":"null"}]},"scopeType":{"anyOf":[{"type":"string"},{"type":"null"}]},"scopeId":{"anyOf":[{"type":"string"},{"type":"null"}]},"from":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},{"type":"null"}]},"to":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},{"type":"null"}]},"locked":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A switch changed."},"SetupPlan":{"type":"object","properties":{"template":{"type":"string","description":"A key from `GET /portals/templates`, or `custom` when nothing there fits."},"fit":{"type":"string","enum":["exact","close","none"],"description":"How well the template fits; `none` goes with `custom`."},"customKind":{"description":"For `custom`: what the avatar mostly does.","type":"string","enum":["service","tutor","roleplay","assessor"]},"templateLabel":{"type":"string"},"portalName":{"type":"string"},"audience":{"type":"string","description":"Who the avatar talks to, in plain words."},"orgType":{"type":"string","enum":["company","school","tutoring","individual","family","other"]},"summary":{"type":"string"}},"required":["template","fit","templateLabel","portalName","audience","orgType","summary"],"description":"What to build for a goal. `POST /portals` with the template builds it."},"SetupPlanInput":{"type":"object","properties":{"goal":{"type":"string","minLength":1,"maxLength":600,"examples":["Train my sales team to handle price objections"]}},"required":["goal"]},"StaffToken":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"staffToken":{"type":"string","description":"Short-lived client token (15 minutes) for the realtime room, as the person: microphone and camera, no data channel."},"url":{"type":"string","description":"The realtime transport URL."},"room":{"type":"string"},"identity":{"type":"string","description":"The person's identity in the room: `staff-<userId>-<random>`, with the attribute zq_role=staff.","examples":["staff-cmfq2b7x10000abcd1234-k3m9qa"]},"userId":{"type":"string","minLength":1,"pattern":"^usr_.*","description":"Person id (`usr_…`).","examples":["usr_cmfq2b7x10000abcd1234"]},"handedOver":{"type":"boolean","description":"True when this person is the first from the team in the call: the avatar says who joined and what the visitor needs, then goes quiet until the team has left."}},"required":["sessionId","staffToken","url","room","identity","userId","handedOver"],"description":"What your helpdesk needs to join the visitor's call as the member, as themselves."},"StaffTokenInput":{"type":"object","properties":{"userId":{"description":"The member who joins. A member's own key (made by them in the console) joins as them and may leave this out; only a full-access key may name another member.","anyOf":[{"description":"Person id (`usr_…`).","type":"string"},{"type":"null"}]}}},"SteerInput":{"type":"object","properties":{"systemPrompt":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"language":{"description":"One of GET /languages (a duo's: one of the ten it speaks).","anyOf":[{"type":"string"},{"type":"null"}]},"variables":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Fills {{name}} placeholders in the prompt and greeting."},{"type":"null"}]}}},"Subject":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"template":{"type":"string","description":"The template it was built from (`custom` for one written for the organisation)."},"kind":{"type":"string","enum":["tutor","roleplay","assessor","service"]},"group":{"type":"string","enum":["learn","train","serve","assess"]},"screening":{"type":"boolean","description":"A candidate screening role (its invites and candidates are under /roles)."},"status":{"type":"string","enum":["draft","published","archived"],"description":"`draft` until it (or its portal) is published."},"liveVersion":{"type":"integer","description":"The version sessions run; 0 when there is none."},"draftVersion":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"A pending draft to publish; null when there is none."},"languages":{"type":"array","items":{"type":"string"},"description":"Language codes (`GET /languages`)."},"visitorLanguage":{"anyOf":[{"type":"string","enum":["follow","listed","english"]},{"type":"null"}],"description":"A website subject: whether it follows the visitor's language, keeps to `languages`, or speaks English. Null for any other."},"unitId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},{"type":"null"}]},"portalIds":{"type":"array","items":{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]}},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","name","template","kind","group","screening","status","liveVersion","draftVersion","languages","visitorLanguage","unitId","portalIds","createdAt","updatedAt"],"description":"A subject: what an avatar teaches, practises, assesses or answers, on one or more portals."},"SubjectAssessment":{"type":"object","properties":{"questions":{"type":"integer","description":"How many questions one attempt asks."},"passMark":{"type":"number"},"timedSeconds":{"type":"integer"},"feedback":{"type":"string","enum":["after-each","at-end"]},"hints":{"type":"boolean"},"hintCost":{"type":"number"},"factChecked":{"type":"boolean"},"purpose":{"type":"string","description":"What the assessment is for, in the notice people confirm before a scored attempt."},"contact":{"type":"string","description":"Who people ask for an adjustment or about a result."},"review":{"type":"string","enum":["borderline","all"]},"certificate":{"type":"boolean"},"humanReview":{"type":"boolean"},"retakeAfterDays":{"type":"integer"},"retakeLimit":{"type":"object","properties":{"attempts":{"type":"integer"},"withinDays":{"type":"integer"}},"required":["attempts","withinDays"]},"contestDays":{"type":"integer"},"practiceMode":{"type":"boolean"},"report":{"type":"string","description":"What the report contains."}},"required":["questions","passMark","feedback","report"],"description":"How a structured assessment runs. On a write, the fields sent replace theirs."},"SubjectAssessmentInput":{"type":"object","properties":{"questions":{"type":"integer","minimum":1,"maximum":80,"description":"How many questions one attempt asks."},"passMark":{"type":"number","minimum":0,"maximum":100},"timedSeconds":{"anyOf":[{"type":"integer","minimum":10,"maximum":900},{"type":"null"}]},"feedback":{"type":"string","enum":["after-each","at-end"]},"hints":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hintCost":{"anyOf":[{"type":"number","minimum":0,"maximum":5},{"type":"null"}]},"factChecked":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"purpose":{"anyOf":[{"type":"string","minLength":0,"maxLength":300,"description":"What the assessment is for, in the notice people confirm before a scored attempt."},{"type":"null"}]},"contact":{"anyOf":[{"type":"string","minLength":0,"maxLength":200,"description":"Who people ask for an adjustment or about a result."},{"type":"null"}]},"review":{"anyOf":[{"type":"string","enum":["borderline","all"]},{"type":"null"}]},"certificate":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"humanReview":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"retakeAfterDays":{"anyOf":[{"type":"integer","minimum":0,"maximum":365},{"type":"null"}]},"retakeLimit":{"anyOf":[{"type":"object","properties":{"attempts":{"type":"integer","minimum":1,"maximum":20},"withinDays":{"type":"integer","minimum":1,"maximum":1095}},"required":["attempts","withinDays"],"additionalProperties":false},{"type":"null"}]},"contestDays":{"anyOf":[{"type":"integer","minimum":0,"maximum":90},{"type":"null"}]},"practiceMode":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"report":{"type":"string","minLength":1,"maxLength":600,"description":"What the report contains."}},"additionalProperties":false,"description":"How a structured assessment runs. On a write, the fields sent replace theirs."},"SubjectBookableService":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"name":{"type":"string"},"minutes":{"type":"integer"},"details":{"type":"string"},"leadTimeHours":{"type":"integer"},"hours":{"type":"string"}},"required":["id","name","minutes"],"description":"Something visitors can ask to book."},"SubjectBookableServiceInput":{"type":"object","properties":{"id":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"name":{"type":"string","minLength":1,"maxLength":80},"minutes":{"type":"integer","minimum":5,"maximum":480},"details":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"leadTimeHours":{"anyOf":[{"type":"integer","minimum":0,"maximum":720},{"type":"null"}]},"hours":{"anyOf":[{"type":"string","minLength":0,"maxLength":40},{"type":"null"}]}},"required":["name","minutes"],"additionalProperties":false,"description":"Something visitors can ask to book."},"SubjectContent":{"type":"object","properties":{"name":{"type":"string"},"audience":{"anyOf":[{"type":"string"},{"type":"null"}]},"languages":{"type":"array","items":{"type":"string"}},"gradeBand":{"anyOf":[{"type":"array","prefixItems":[{"type":"integer"},{"type":"integer"}],"description":"`[lowest, highest]` grade, 1 to 12."},{"type":"null"}]},"facts":{"type":"array","items":{"$ref":"#/components/schemas/SubjectFact"}},"topics":{"type":"array","items":{"$ref":"#/components/schemas/SubjectTopic"}},"frame":{"anyOf":[{"type":"string"},{"type":"null"}]},"scenarios":{"type":"array","items":{"$ref":"#/components/schemas/SubjectScenario"}},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SubjectQuestion"}},"questionSets":{"type":"array","items":{"$ref":"#/components/schemas/SubjectQuestionSet"}},"rubric":{"$ref":"#/components/schemas/SubjectRubric"},"assessment":{"$ref":"#/components/schemas/SubjectAssessment"},"service":{"$ref":"#/components/schemas/SubjectService"},"faqs":{"type":"array","items":{"$ref":"#/components/schemas/SubjectFaq"}},"departments":{"type":"array","items":{"$ref":"#/components/schemas/SubjectDepartment"}},"hours":{"anyOf":[{"$ref":"#/components/schemas/SubjectHours"},{"type":"null"}]},"locations":{"type":"array","items":{"$ref":"#/components/schemas/SubjectLocation"}},"services":{"type":"array","items":{"$ref":"#/components/schemas/SubjectBookableService"}},"qualification":{"type":"array","items":{"$ref":"#/components/schemas/SubjectQualification"}},"leadScoring":{"anyOf":[{"$ref":"#/components/schemas/SubjectLeadScoring"},{"type":"null"}]},"safetyLines":{"anyOf":[{"$ref":"#/components/schemas/SubjectSafetyLines"},{"type":"null"}]},"widget":{"$ref":"#/components/schemas/SubjectWidget"},"screening":{"$ref":"#/components/schemas/SubjectScreening"}},"required":["name","audience","languages","gradeBand","facts"],"description":"A subject's content, one section per thing a business edits. Sections that don't apply to the subject's kind are left out; a section that applies but isn't set is null (objects) or [] (lists)."},"SubjectContentDraft":{"type":"object","properties":{"version":{"type":"integer","description":"The version shown; its `ETag` is `\"v<version>\"`."},"live":{"type":"boolean","description":"It is what sessions run."},"basedOn":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The version it was saved over; null for the first."},"content":{"$ref":"#/components/schemas/SubjectContent"},"goLive":{"type":"object","properties":{"ready":{"type":"boolean"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/GoLiveProblem"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/GoLiveProblem"},"description":"Worth fixing; never a refusal."}},"required":["ready","problems","warnings"]}},"required":["version","live","basedOn","content","goLive"],"description":"The draft saved, and whether it could go live."},"SubjectContentSet":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"audience":{"anyOf":[{"type":"string","minLength":0,"maxLength":120},{"type":"null"}]},"languages":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":2,"maxLength":80}},"gradeBand":{"anyOf":[{"type":"array","prefixItems":[{"type":"integer","minimum":1,"maximum":12},{"type":"integer","minimum":1,"maximum":12}],"description":"`[lowest, highest]` grade, 1 to 12."},{"type":"null"}]},"facts":{"anyOf":[{"maxItems":30,"type":"array","items":{"$ref":"#/components/schemas/SubjectFactInput"}},{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"description":"Values by fact key: sets each one given (a new key is added); null clears a value."}],"description":"Either the whole list of facts (replacing it), or `{ key: value }` to set values by key."},"topics":{"minItems":1,"maxItems":500,"type":"array","items":{"$ref":"#/components/schemas/SubjectTopicInput"}},"frame":{"anyOf":[{"type":"string","minLength":0,"maxLength":1200},{"type":"null"}]},"scenarios":{"minItems":0,"maxItems":60,"type":"array","items":{"$ref":"#/components/schemas/SubjectScenarioInput"}},"questions":{"minItems":0,"maxItems":300,"type":"array","items":{"$ref":"#/components/schemas/SubjectQuestionInput"}},"questionSets":{"minItems":0,"maxItems":40,"type":"array","items":{"$ref":"#/components/schemas/SubjectQuestionSetInput"}},"rubric":{"$ref":"#/components/schemas/SubjectRubricInput"},"assessment":{"$ref":"#/components/schemas/SubjectAssessmentInput"},"service":{"$ref":"#/components/schemas/SubjectServiceInput"},"faqs":{"minItems":0,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/SubjectFaqInput"}},"departments":{"minItems":0,"maxItems":20,"type":"array","items":{"$ref":"#/components/schemas/SubjectDepartmentInput"}},"hours":{"anyOf":[{"$ref":"#/components/schemas/SubjectHoursInput"},{"type":"null"}]},"locations":{"minItems":0,"maxItems":10,"type":"array","items":{"$ref":"#/components/schemas/SubjectLocationInput"}},"services":{"minItems":0,"maxItems":30,"type":"array","items":{"$ref":"#/components/schemas/SubjectBookableServiceInput"}},"qualification":{"minItems":0,"maxItems":15,"type":"array","items":{"$ref":"#/components/schemas/SubjectQualificationInput"}},"leadScoring":{"anyOf":[{"$ref":"#/components/schemas/SubjectLeadScoringInput"},{"type":"null"}]},"safetyLines":{"anyOf":[{"$ref":"#/components/schemas/SubjectSafetyLinesInput"},{"type":"null"}]},"widget":{"$ref":"#/components/schemas/SubjectWidgetInput"},"screening":{"$ref":"#/components/schemas/SubjectScreeningInput"}},"additionalProperties":false,"description":"The sections to change. A list replaces the whole list; an object section changes only the fields sent (null clears an optional one); `facts` also takes `{ key: value }`. A document read with GET can be sent back as it is."},"SubjectContentUpdate":{"type":"object","properties":{"set":{"$ref":"#/components/schemas/SubjectContentSet"},"note":{"description":"Kept with the version.","type":"string","maxLength":200},"baseVersion":{"description":"The version your change is based on (or send `If-Match: \"v<n>\"`); a newer one is `409 version_conflict`.","type":"integer","minimum":1}},"required":["set"],"additionalProperties":false,"description":"Sections to change. Always saved as a draft; publish it with `POST /subjects/{id}/publish`."},"SubjectContentVersion":{"type":"object","properties":{"version":{"type":"integer","description":"The version shown; its `ETag` is `\"v<version>\"`."},"live":{"type":"boolean","description":"It is what sessions run."},"basedOn":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The version it was saved over; null for the first."},"content":{"$ref":"#/components/schemas/SubjectContent"}},"required":["version","live","basedOn","content"],"description":"One version of a subject's content."},"SubjectDepartment":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"name":{"type":"string"},"handles":{"type":"string"},"contact":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"hours":{"type":"string","description":"A set of opening hours, by its id in `hours.sets`."},"callbackPromise":{"type":"string"},"callbackWithinHours":{"type":"integer"}},"required":["name","handles"],"description":"A team visitors can be passed to."},"SubjectDepartmentInput":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},{"type":"null"}]},"name":{"type":"string","minLength":1,"maxLength":80},"handles":{"type":"string","minLength":1,"maxLength":400},"contact":{"anyOf":[{"type":"string","minLength":0,"maxLength":200},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","minLength":0,"maxLength":40},{"type":"null"}]},"email":{"anyOf":[{"type":"string","minLength":0,"maxLength":120},{"type":"null"}]},"hours":{"anyOf":[{"type":"string","minLength":0,"maxLength":40,"description":"A set of opening hours, by its id in `hours.sets`."},{"type":"null"}]},"callbackPromise":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"callbackWithinHours":{"anyOf":[{"type":"integer","minimum":1,"maximum":168},{"type":"null"}]}},"required":["name","handles"],"additionalProperties":false,"description":"A team visitors can be passed to."},"SubjectDraftSavedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"via":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A subject's draft version was saved."},"SubjectFact":{"type":"object","properties":{"key":{"type":"string","description":"Fills `{{key}}` wherever the subject's content says it."},"label":{"type":"string"},"value":{"type":"string","description":"The organisation's own value; \"\" = not filled in yet."},"help":{"type":"string"},"keep":{"type":"boolean","description":"A method or guardrail default the organisation keeps until it writes its own."},"perPerson":{"type":"boolean","description":"Each person gives their own value on the start screen (the role an interview is for)."}},"required":["key","label","value"],"description":"A fact about the organisation that the subject's content uses."},"SubjectFactInput":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z][a-z0-9_]*$","description":"Fills `{{key}}` wherever the subject's content says it."},"label":{"type":"string","minLength":1,"maxLength":80},"value":{"type":"string","minLength":0,"maxLength":2000,"description":"The organisation's own value; \"\" = not filled in yet."},"help":{"anyOf":[{"type":"string","minLength":0,"maxLength":240},{"type":"null"}]},"keep":{"anyOf":[{"type":"boolean","description":"A method or guardrail default the organisation keeps until it writes its own."},{"type":"null"}]},"perPerson":{"anyOf":[{"type":"boolean","description":"Each person gives their own value on the start screen (the role an interview is for)."},{"type":"null"}]}},"required":["key","value"],"additionalProperties":false,"description":"A fact about the organisation that the subject's content uses."},"SubjectFaq":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"q":{"type":"string","description":"The question, as visitors ask it."},"ask":{"type":"array","items":{"type":"string"},"description":"Other ways visitors ask it (any language)."},"a":{"type":"string","description":"The approved answer."},"link":{"type":"string"},"then":{"type":"string","description":"What to do after answering: `offer_handoff:<team>`, `start_booking:<service>`."}},"required":["q","a"],"description":"An approved answer to a question visitors ask."},"SubjectFaqInput":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},{"type":"null"}]},"q":{"type":"string","minLength":1,"maxLength":300,"description":"The question, as visitors ask it."},"ask":{"anyOf":[{"maxItems":6,"type":"array","items":{"type":"string","minLength":1,"maxLength":160},"description":"Other ways visitors ask it (any language)."},{"type":"null"}]},"a":{"type":"string","minLength":1,"maxLength":1200,"description":"The approved answer."},"link":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"then":{"anyOf":[{"type":"string","minLength":0,"maxLength":120,"description":"What to do after answering: `offer_handoff:<team>`, `start_booking:<service>`."},{"type":"null"}]}},"required":["q","a"],"additionalProperties":false,"description":"An approved answer to a question visitors ask."},"SubjectGoLive":{"type":"object","properties":{"version":{"type":"integer","description":"The version checked."},"ready":{"type":"boolean"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/GoLiveProblem"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/GoLiveProblem"},"description":"Worth fixing; never a refusal."}},"required":["version","ready","problems","warnings"],"description":"Whether a version of the subject can go live, and what to finish first."},"SubjectHours":{"type":"object","properties":{"timezone":{"type":"string","description":"An IANA time zone, like `America/New_York`."},"bankHolidays":{"type":"string","enum":["england-and-wales","scotland","northern-ireland","us-common","us-federal","none"]},"sets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"mon":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"tue":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"wed":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"thu":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"fri":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"sat":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"sun":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"openOnBankHolidays":{"type":"boolean"}},"required":["mon","tue","wed","thu","fri","sat","sun"]},"description":"Opening hours by set id (`main`, `sales`). A day left out on a write is closed."},"closures":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"label":{"type":"string"},"sets":{"type":"array","items":{"type":"string"}}},"required":["date","label"]}}},"required":["timezone","sets"],"description":"Opening hours the assistant can reason about. On a write, the fields sent replace theirs."},"SubjectHoursInput":{"type":"object","properties":{"timezone":{"type":"string","minLength":1,"maxLength":60,"description":"An IANA time zone, like `America/New_York`."},"bankHolidays":{"anyOf":[{"type":"string","enum":["england-and-wales","scotland","northern-ireland","us-common","us-federal","none"]},{"type":"null"}]},"sets":{"type":"object","propertyNames":{"type":"string","maxLength":32,"pattern":"^[a-z0-9_-]{1,32}$"},"additionalProperties":{"type":"object","properties":{"mon":{"minItems":0,"maxItems":4,"type":"array","items":{"type":"array","prefixItems":[{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"},{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"tue":{"minItems":0,"maxItems":4,"type":"array","items":{"type":"array","prefixItems":[{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"},{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"wed":{"minItems":0,"maxItems":4,"type":"array","items":{"type":"array","prefixItems":[{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"},{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"thu":{"minItems":0,"maxItems":4,"type":"array","items":{"type":"array","prefixItems":[{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"},{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"fri":{"minItems":0,"maxItems":4,"type":"array","items":{"type":"array","prefixItems":[{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"},{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"sat":{"minItems":0,"maxItems":4,"type":"array","items":{"type":"array","prefixItems":[{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"},{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"sun":{"minItems":0,"maxItems":4,"type":"array","items":{"type":"array","prefixItems":[{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"},{"type":"string","maxLength":5,"pattern":"^\\d{2}:\\d{2}$"}]},"description":"Up to four `[from, to]` pairs in 24-hour HH:MM; [] = closed."},"openOnBankHolidays":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":false},"description":"Opening hours by set id (`main`, `sales`). A day left out on a write is closed."},"closures":{"anyOf":[{"minItems":0,"maxItems":60,"type":"array","items":{"type":"object","properties":{"date":{"type":"string","maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"label":{"type":"string","minLength":0,"maxLength":80},"sets":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["date","label"],"additionalProperties":false}},{"type":"null"}]}},"additionalProperties":false,"description":"Opening hours the assistant can reason about. On a write, the fields sent replace theirs."},"SubjectLeadScoring":{"type":"object","properties":{"hot":{"type":"string"},"warm":{"type":"string"},"cold":{"type":"string"},"hotAt":{"type":"integer"},"warmAt":{"type":"integer"}},"required":["hot","warm","cold"],"description":"How a lead is banded. On a write, the fields sent replace theirs."},"SubjectLeadScoringInput":{"type":"object","properties":{"hot":{"type":"string","minLength":1,"maxLength":500},"warm":{"type":"string","minLength":1,"maxLength":500},"cold":{"type":"string","minLength":1,"maxLength":500},"hotAt":{"anyOf":[{"type":"integer","minimum":-500,"maximum":500},{"type":"null"}]},"warmAt":{"anyOf":[{"type":"integer","minimum":-500,"maximum":500},{"type":"null"}]}},"additionalProperties":false,"description":"How a lead is banded. On a write, the fields sent replace theirs."},"SubjectLocation":{"type":"object","properties":{"name":{"type":"string"},"address":{"type":"string"},"mapUrl":{"type":"string"},"parking":{"type":"string"},"access":{"type":"string"}},"required":["name","address"],"description":"Where the business is."},"SubjectLocationInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"address":{"type":"string","minLength":1,"maxLength":300},"mapUrl":{"anyOf":[{"type":"string","minLength":0,"maxLength":500},{"type":"null"}]},"parking":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"access":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]}},"required":["name","address"],"additionalProperties":false,"description":"Where the business is."},"SubjectPublish":{"type":"object","properties":{"version":{"description":"The version to publish (default: the newest, the pending draft). An older one is brought back as the newest.","type":"integer","minimum":1},"newRound":{"description":"A screening role that keeps candidates: changes to how candidates compare start a new round (otherwise `409 conflict`, reason `round_locked`).","type":"boolean"}},"description":"What to publish."},"SubjectQualification":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"question":{"type":"string"},"field":{"type":"string","enum":["name","email","phone","company","role","need","budget","timeline","preferred_time","location","reference"]},"why":{"type":"string"},"points":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer"},"description":"Points per kind of answer, for the lead score."}},"required":["id","question"],"description":"A question asked about an enquiry before it goes to the team."},"SubjectQualificationInput":{"type":"object","properties":{"id":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"question":{"type":"string","minLength":1,"maxLength":300},"field":{"anyOf":[{"type":"string","enum":["name","email","phone","company","role","need","budget","timeline","preferred_time","location","reference"]},{"type":"null"}]},"why":{"anyOf":[{"type":"string","minLength":0,"maxLength":240},{"type":"null"}]},"points":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-50,"maximum":50},"description":"Points per kind of answer, for the lead score."},{"type":"null"}]}},"required":["question"],"additionalProperties":false,"description":"A question asked about an enquiry before it goes to the team."},"SubjectQuestion":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"text":{"type":"string"},"topic":{"type":"string"},"competency":{"type":"string","description":"The rubric category it measures."},"difficulty":{"type":"string","enum":["easy","medium","hard"]},"format":{"type":"string","enum":["open","short","scenario","choice"]},"options":{"type":"array","items":{"type":"string"}},"followUps":{"type":"array","items":{"type":"string"}},"followUpsRigorous":{"type":"array","items":{"type":"string"}},"twist":{"type":"string"},"lookFor":{"type":"array","items":{"type":"string"}},"redFlags":{"type":"array","items":{"type":"string"}},"anchors":{"type":"object","properties":{"1":{"type":"string"},"3":{"type":"string"},"5":{"type":"string"}}},"note":{"type":"string"},"modelAnswer":{"type":"string"},"accepted":{"type":"array","items":{"type":"string"}},"marks":{"type":"integer"},"timeSeconds":{"type":"integer"},"critical":{"type":"boolean"},"pinned":{"type":"string","enum":["first","last"]}},"required":["id","text"],"description":"A question people are asked (the answer key is the organisation's own content)."},"SubjectQuestionInput":{"type":"object","properties":{"id":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"text":{"type":"string","minLength":1,"maxLength":600},"topic":{"anyOf":[{"type":"string","minLength":0,"maxLength":60},{"type":"null"}]},"competency":{"anyOf":[{"type":"string","minLength":0,"maxLength":60,"description":"The rubric category it measures."},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"string","enum":["easy","medium","hard"]},{"type":"null"}]},"format":{"anyOf":[{"type":"string","enum":["open","short","scenario","choice"]},{"type":"null"}]},"options":{"anyOf":[{"maxItems":6,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"}]},"followUps":{"anyOf":[{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}},{"type":"null"}]},"followUpsRigorous":{"anyOf":[{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}},{"type":"null"}]},"twist":{"anyOf":[{"type":"string","minLength":1,"maxLength":400},{"type":"null"}]},"lookFor":{"anyOf":[{"maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":240}},{"type":"null"}]},"redFlags":{"anyOf":[{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":240}},{"type":"null"}]},"anchors":{"anyOf":[{"type":"object","properties":{"1":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"3":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"5":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]},"note":{"anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"null"}]},"modelAnswer":{"anyOf":[{"type":"string","minLength":0,"maxLength":1500},{"type":"null"}]},"accepted":{"anyOf":[{"maxItems":16,"type":"array","items":{"type":"string","minLength":1,"maxLength":160}},{"type":"null"}]},"marks":{"anyOf":[{"type":"integer","minimum":0,"maximum":20},{"type":"null"}]},"timeSeconds":{"anyOf":[{"type":"integer","minimum":10,"maximum":900},{"type":"null"}]},"critical":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"pinned":{"anyOf":[{"type":"string","enum":["first","last"]},{"type":"null"}]}},"required":["text"],"additionalProperties":false,"description":"A question people are asked (the answer key is the organisation's own content)."},"SubjectQuestionSet":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"title":{"type":"string"},"description":{"type":"string"},"questionIds":{"type":"array","items":{"type":"string"}},"order":{"type":"string","enum":["fixed","shuffled"],"description":"Left out on a write: `fixed`."},"ask":{"type":"integer"},"level":{"type":"string","enum":["easy","medium","hard","mixed"]},"region":{"type":"string","enum":["uk","us","intl"],"description":"The country the content is written for: `uk` or `us`, or `intl` for a law module's version for everywhere outside the UK; left out = anywhere."},"hidden":{"type":"boolean"},"form":{"type":"string"},"intensity":{"type":"string","enum":["relaxed","standard","rigorous"]},"assessment":{"type":"object","properties":{"mode":{"type":"string","enum":["scored","practice","either"]},"passMark":{"type":"number"},"timedSeconds":{"type":"integer"},"feedback":{"type":"string","enum":["after-each","at-end"]},"hints":{"type":"boolean"},"hintCost":{"type":"number"},"review":{"type":"string","enum":["borderline","all"]},"certificate":{"type":"boolean"}}}},"required":["id","title","questionIds","order"],"description":"A named group of questions."},"SubjectQuestionSetInput":{"type":"object","properties":{"id":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"title":{"type":"string","minLength":1,"maxLength":80},"description":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"questionIds":{"minItems":1,"maxItems":80,"type":"array","items":{"type":"string","minLength":1,"maxLength":60}},"order":{"type":"string","enum":["fixed","shuffled"],"description":"Left out on a write: `fixed`."},"ask":{"anyOf":[{"type":"integer","minimum":1,"maximum":80},{"type":"null"}]},"level":{"anyOf":[{"type":"string","enum":["easy","medium","hard","mixed"]},{"type":"null"}]},"region":{"anyOf":[{"type":"string","enum":["uk","us","intl"],"description":"The country the content is written for: `uk` or `us`, or `intl` for a law module's version for everywhere outside the UK; left out = anywhere."},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"form":{"anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]},"intensity":{"anyOf":[{"type":"string","enum":["relaxed","standard","rigorous"]},{"type":"null"}]},"assessment":{"anyOf":[{"type":"object","properties":{"mode":{"anyOf":[{"type":"string","enum":["scored","practice","either"]},{"type":"null"}]},"passMark":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"timedSeconds":{"anyOf":[{"type":"integer","minimum":10,"maximum":900},{"type":"null"}]},"feedback":{"anyOf":[{"type":"string","enum":["after-each","at-end"]},{"type":"null"}]},"hints":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hintCost":{"anyOf":[{"type":"number","minimum":0,"maximum":5},{"type":"null"}]},"review":{"anyOf":[{"type":"string","enum":["borderline","all"]},{"type":"null"}]},"certificate":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]}},"required":["title","questionIds"],"additionalProperties":false,"description":"A named group of questions."},"SubjectQuestionsTranslate":{"type":"object","properties":{"language":{"type":"string","minLength":1,"maxLength":80,"description":"A name or code from `GET /languages` (\"German\", \"es\"): the portal's language."}},"required":["language"],"additionalProperties":false,"description":"The language to translate the subject's questions into."},"SubjectQuestionsTranslated":{"type":"object","properties":{"version":{"type":"integer","description":"The draft that holds the translated questions."},"language":{"type":"string","description":"The language's name."},"translated":{"type":"integer","description":"How many questions were translated."}},"required":["version","language","translated"],"description":"A draft with the subject's questions in another language, to check and publish."},"SubjectRubric":{"type":"object","properties":{"scale":{"type":"number"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"weight":{"type":"number"},"note":{"type":"string"},"anchors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["id","weight"]},"description":"Weights add up to 1."},"masteredAt":{"type":"number"},"critical":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"label":{"type":"string"},"cap":{"type":"number"},"categories":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"when":{"type":"string","enum":["beyond_walk_away"]}},"required":["id","label"]}}},"required":["scale","categories","masteredAt"],"description":"How conversations are marked. On a write, the fields sent replace theirs."},"SubjectRubricInput":{"type":"object","properties":{"scale":{"type":"number","exclusiveMinimum":0},"categories":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":60},"label":{"anyOf":[{"type":"string","minLength":0,"maxLength":60},{"type":"null"}]},"weight":{"type":"number","minimum":0,"maximum":1},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"anchors":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","minLength":0,"maxLength":500}},{"type":"null"}]}},"required":["weight"],"additionalProperties":false},"description":"Weights add up to 1."},"masteredAt":{"type":"number","minimum":0},"critical":{"anyOf":[{"minItems":0,"maxItems":12,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"label":{"type":"string","minLength":1,"maxLength":200},"cap":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"categories":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number","minimum":0,"maximum":100}},{"type":"null"}]},"when":{"anyOf":[{"type":"string","enum":["beyond_walk_away"]},{"type":"null"}]}},"required":["label"],"additionalProperties":false}},{"type":"null"}]}},"additionalProperties":false,"description":"How conversations are marked. On a write, the fields sent replace theirs."},"SubjectSafetyLines":{"type":"object","properties":{"emergency":{"type":"string"},"crisis":{"type":"string"},"child":{"type":"string"},"domesticAbuse":{"type":"string"},"cannotSpeak":{"type":"string"}},"description":"The organisation's exact safety wording. On a write, the fields sent replace theirs."},"SubjectSafetyLinesInput":{"type":"object","properties":{"emergency":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"crisis":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"child":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"domesticAbuse":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"cannotSpeak":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]}},"additionalProperties":false,"description":"The organisation's exact safety wording. On a write, the fields sent replace theirs."},"SubjectScenario":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"title":{"type":"string"},"context":{"type":"string","description":"The situation, shown to the person before they start."},"counterpart":{"type":"string","description":"Who the avatar plays, shown to the person."},"private":{"type":"string","description":"The counterpart's hidden brief: never shown to the person."},"goal":{"type":"string"},"opening":{"type":"string"},"difficulty":{"type":"string","enum":["easy","medium","hard","any"],"description":"Left out on a write: `any`."},"skills":{"type":"array","items":{"type":"string"}},"success":{"type":"string"},"minutes":{"type":"integer"},"audienceBrief":{"type":"string"},"audienceQuestions":{"type":"object","properties":{"easy":{"type":"array","items":{"type":"string"}},"medium":{"type":"array","items":{"type":"string"}},"hard":{"type":"array","items":{"type":"string"}}},"required":["easy","medium","hard"]},"traineeBrief":{"type":"string"},"sensitive":{"type":"boolean"},"hidden":{"type":"boolean","description":"Kept but never offered: a sensitive situation written for another industry, until it is rewritten for this business and checked."},"contentNote":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"label":{"type":"string"},"unit":{"type":"string"},"better":{"type":"string","enum":["high","low"],"description":"`high` = the trainee wants a bigger number; `low` = a smaller one."},"target":{"type":"number"},"walkAway":{"type":"number"},"counterpartLimit":{"type":"number","description":"The counterpart's real limit: never shown to the trainee."},"weight":{"type":"number"}},"required":["id","label","better","target","walkAway"]}}},"required":["id","title","counterpart","goal","difficulty"],"description":"A role-play scenario: the avatar plays the counterpart."},"SubjectScenarioInput":{"type":"object","properties":{"id":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"title":{"type":"string","minLength":1,"maxLength":80},"context":{"anyOf":[{"type":"string","minLength":0,"maxLength":600,"description":"The situation, shown to the person before they start."},{"type":"null"}]},"counterpart":{"type":"string","minLength":1,"maxLength":400,"description":"Who the avatar plays, shown to the person."},"private":{"anyOf":[{"type":"string","minLength":0,"maxLength":1500,"description":"The counterpart's hidden brief: never shown to the person."},{"type":"null"}]},"goal":{"type":"string","minLength":1,"maxLength":300},"opening":{"anyOf":[{"type":"string","minLength":0,"maxLength":400},{"type":"null"}]},"difficulty":{"type":"string","enum":["easy","medium","hard","any"],"description":"Left out on a write: `any`."},"skills":{"anyOf":[{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":60}},{"type":"null"}]},"success":{"anyOf":[{"type":"string","minLength":0,"maxLength":400},{"type":"null"}]},"minutes":{"anyOf":[{"type":"integer","minimum":1,"maximum":60},{"type":"null"}]},"audienceBrief":{"anyOf":[{"type":"string","minLength":0,"maxLength":600},{"type":"null"}]},"audienceQuestions":{"anyOf":[{"type":"object","properties":{"easy":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}},"medium":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}},"hard":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}}},"required":["easy","medium","hard"],"additionalProperties":false},{"type":"null"}]},"traineeBrief":{"anyOf":[{"type":"string","minLength":0,"maxLength":1200},{"type":"null"}]},"sensitive":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean","description":"Kept but never offered: a sensitive situation written for another industry, until it is rewritten for this business and checked."},{"type":"null"}]},"contentNote":{"anyOf":[{"type":"string","minLength":0,"maxLength":240},{"type":"null"}]},"issues":{"anyOf":[{"minItems":0,"maxItems":8,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"label":{"type":"string","minLength":1,"maxLength":80},"unit":{"anyOf":[{"type":"string","minLength":0,"maxLength":20},{"type":"null"}]},"better":{"type":"string","enum":["high","low"],"description":"`high` = the trainee wants a bigger number; `low` = a smaller one."},"target":{"type":"number"},"walkAway":{"type":"number"},"counterpartLimit":{"anyOf":[{"type":"number","description":"The counterpart's real limit: never shown to the trainee."},{"type":"null"}]},"weight":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]}},"required":["label","better","target","walkAway"],"additionalProperties":false}},{"type":"null"}]}},"required":["title","counterpart","goal"],"additionalProperties":false,"description":"A role-play scenario: the avatar plays the counterpart."},"SubjectScreening":{"type":"object","properties":{"role":{"type":"string","description":"The job title."},"location":{"type":"string"},"intro":{"type":"string","description":"What candidates read before they start."},"notice":{"type":"string"},"capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","location"]}},"requirements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"question":{"type":"string","description":"Asked word for word near the start."},"kind":{"type":"string","enum":["yes_no","choice","number","text"]},"options":{"type":"array","items":{"type":"string"}},"meets":{"type":"object","properties":{"anyOf":{"type":"array","items":{"type":"string"}},"min":{"type":"number"},"max":{"type":"number"}},"description":"The answer that meets it: one of `anyOf` (`yes` for yes/no), or a range; left out = recorded, not judged."},"knockout":{"type":"boolean","description":"Not meeting it is flagged to the hiring team; a person decides."},"why":{"type":"string"}},"required":["id","question","kind"]}},"setId":{"type":"string","description":"The question set the interview uses."},"unchecked":{"type":"array","items":{"type":"string","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"description":"Questions written for the role by Magic Setup that no person has checked yet: the role can't go live until this is empty. Send [] once they are checked."},"bands":{"type":"object","properties":{"strong":{"type":"number"},"possible":{"type":"number"}},"required":["strong","possible"]},"humanContact":{"type":"string","description":"Who candidates contact for adjustments or a person instead."},"adjustments":{"type":"string"},"retentionDays":{"type":"integer"},"closesOn":{"type":"string"},"timing":{"type":"object","properties":{"mode":{"type":"string","enum":["open","deadline","scheduled"]},"deadlineDays":{"type":"integer"},"earlyMinutes":{"type":"integer"},"lateMinutes":{"type":"integer"}},"required":["mode"]},"recording":{"type":"string","enum":["transcript","audio","audio_video"]},"cameraOptional":{"type":"boolean"},"openDoor":{"type":"boolean"},"intensity":{"type":"string","enum":["relaxed","standard","rigorous"]},"style":{"type":"string","enum":["structured","natural"]},"bookingUrl":{"type":"string"},"hiringFor":{"type":"string"},"outcomeEmails":{"type":"object","properties":{"invite":{"type":"string"},"hold":{"type":"string"},"decline":{"type":"string"}}},"market":{"type":"string","enum":["us","uk","eu"]},"usState":{"type":"string"},"nyc":{"type":"boolean"},"timeZone":{"type":"string"}},"required":["role","intro","notice","capture","requirements","bands","humanContact","adjustments","retentionDays"],"description":"A candidate screening role. On a write, the fields sent replace theirs."},"SubjectScreeningInput":{"type":"object","properties":{"role":{"type":"string","minLength":2,"maxLength":120,"description":"The job title."},"location":{"anyOf":[{"type":"string","minLength":0,"maxLength":120},{"type":"null"}]},"intro":{"type":"string","minLength":10,"maxLength":1200,"description":"What candidates read before they start."},"notice":{"type":"string","minLength":10,"maxLength":1500},"capture":{"minItems":2,"maxItems":4,"type":"array","items":{"type":"string","enum":["name","email","phone","location"]}},"requirements":{"minItems":0,"maxItems":10,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"question":{"type":"string","minLength":3,"maxLength":300,"description":"Asked word for word near the start."},"kind":{"type":"string","enum":["yes_no","choice","number","text"]},"options":{"anyOf":[{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},{"type":"null"}]},"meets":{"anyOf":[{"type":"object","properties":{"anyOf":{"anyOf":[{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},{"type":"null"}]},"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false,"description":"The answer that meets it: one of `anyOf` (`yes` for yes/no), or a range; left out = recorded, not judged."},{"type":"null"}]},"knockout":{"anyOf":[{"type":"boolean","description":"Not meeting it is flagged to the hiring team; a person decides."},{"type":"null"}]},"why":{"anyOf":[{"type":"string","minLength":0,"maxLength":240},{"type":"null"}]}},"required":["question","kind"],"additionalProperties":false}},"setId":{"anyOf":[{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The question set the interview uses."},{"type":"null"}]},"unchecked":{"anyOf":[{"minItems":0,"maxItems":40,"type":"array","items":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$","description":"The item's id within this subject: letters, numbers, dots, dashes or underscores."},"description":"Questions written for the role by Magic Setup that no person has checked yet: the role can't go live until this is empty. Send [] once they are checked."},{"type":"null"}]},"bands":{"type":"object","properties":{"strong":{"type":"number","minimum":0,"maximum":100},"possible":{"type":"number","minimum":0,"maximum":100}},"required":["strong","possible"],"additionalProperties":false},"humanContact":{"type":"string","minLength":0,"maxLength":300,"description":"Who candidates contact for adjustments or a person instead."},"adjustments":{"type":"string","minLength":5,"maxLength":600},"retentionDays":{"type":"integer","minimum":7,"maximum":1461},"closesOn":{"anyOf":[{"type":"string","maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"timing":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["open","deadline","scheduled"]},"deadlineDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":60},{"type":"null"}]},"earlyMinutes":{"anyOf":[{"type":"integer","minimum":0,"maximum":120},{"type":"null"}]},"lateMinutes":{"anyOf":[{"type":"integer","minimum":1,"maximum":120},{"type":"null"}]}},"required":["mode"],"additionalProperties":false},{"type":"null"}]},"recording":{"anyOf":[{"type":"string","enum":["transcript","audio","audio_video"]},{"type":"null"}]},"cameraOptional":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"openDoor":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"intensity":{"anyOf":[{"type":"string","enum":["relaxed","standard","rigorous"]},{"type":"null"}]},"style":{"anyOf":[{"type":"string","enum":["structured","natural"]},{"type":"null"}]},"bookingUrl":{"anyOf":[{"type":"string","maxLength":500,"pattern":"^https:\\/\\/[^\\s]+\\.[^\\s]+$"},{"type":"null"}]},"hiringFor":{"anyOf":[{"type":"string","minLength":0,"maxLength":120},{"type":"null"}]},"outcomeEmails":{"anyOf":[{"type":"object","properties":{"invite":{"anyOf":[{"type":"string","minLength":0,"maxLength":1200},{"type":"null"}]},"hold":{"anyOf":[{"type":"string","minLength":0,"maxLength":1200},{"type":"null"}]},"decline":{"anyOf":[{"type":"string","minLength":0,"maxLength":1200},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]},"market":{"anyOf":[{"type":"string","enum":["us","uk","eu","US","UK","EU"]},{"type":"null"}]},"usState":{"anyOf":[{"type":"string","maxLength":2,"pattern":"^[A-Z]{2}$"},{"type":"null"}]},"nyc":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"timeZone":{"anyOf":[{"type":"string","minLength":0,"maxLength":60},{"type":"null"}]}},"additionalProperties":false,"description":"A candidate screening role. On a write, the fields sent replace theirs."},"SubjectService":{"type":"object","properties":{"goal":{"type":"string"},"opening":{"type":"string"},"outOfHoursOpening":{"type":"string"},"helpsWith":{"type":"array","items":{"type":"string"}},"capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","company","role","need","budget","timeline","preferred_time","location","reference"]},"description":"The details the avatar may ask a visitor for, with consent."},"captureRules":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"How to ask for each detail, by capture field."},"consent":{"type":"string"},"privacyNoticeUrl":{"type":"string"},"neverCollect":{"type":"array","items":{"type":"string"}},"handoff":{"type":"string"},"handoffRules":{"type":"object","properties":{"offerAfterUnanswered":{"type":"integer"},"alwaysHandoffTopics":{"type":"array","items":{"type":"string"}},"urgentTopics":{"type":"array","items":{"type":"string"}},"emergencyTopics":{"type":"array","items":{"type":"string"}},"staffSummary":{"type":"string"}}},"booking":{"type":"boolean"},"bookingRules":{"type":"string"},"outOfHours":{"type":"string"},"escalateOn":{"type":"array","items":{"type":"string"}},"closedScreen":{"type":"string"},"end":{"type":"object","properties":{"nextSteps":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"ratingPrompt":{"type":"string"},"thanksLine":{"type":"string"}}}},"required":["goal","capture","consent","handoff"],"description":"How a website conversation runs. On a write, the fields sent replace theirs."},"SubjectServiceInput":{"type":"object","properties":{"goal":{"type":"string","minLength":1,"maxLength":300},"opening":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"outOfHoursOpening":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"helpsWith":{"anyOf":[{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},{"type":"null"}]},"capture":{"minItems":0,"maxItems":11,"type":"array","items":{"type":"string","enum":["name","email","phone","company","role","need","budget","timeline","preferred_time","location","reference"]},"description":"The details the avatar may ask a visitor for, with consent."},"captureRules":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","minLength":1,"maxLength":200},"description":"How to ask for each detail, by capture field."},{"type":"null"}]},"consent":{"type":"string","minLength":1,"maxLength":400},"privacyNoticeUrl":{"anyOf":[{"type":"string","maxLength":300,"format":"uri"},{"type":"null"}]},"neverCollect":{"anyOf":[{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},{"type":"null"}]},"handoff":{"type":"string","minLength":1,"maxLength":400},"handoffRules":{"anyOf":[{"type":"object","properties":{"offerAfterUnanswered":{"anyOf":[{"type":"integer","minimum":1,"maximum":10},{"type":"null"}]},"alwaysHandoffTopics":{"anyOf":[{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},{"type":"null"}]},"urgentTopics":{"anyOf":[{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},{"type":"null"}]},"emergencyTopics":{"anyOf":[{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},{"type":"null"}]},"staffSummary":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]},"booking":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"bookingRules":{"anyOf":[{"type":"string","minLength":0,"maxLength":1200},{"type":"null"}]},"outOfHours":{"anyOf":[{"type":"string","minLength":0,"maxLength":500},{"type":"null"}]},"escalateOn":{"anyOf":[{"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},{"type":"null"}]},"closedScreen":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"end":{"anyOf":[{"type":"object","properties":{"nextSteps":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","minLength":1,"maxLength":300}},{"type":"null"}]},"ratingPrompt":{"anyOf":[{"type":"string","minLength":0,"maxLength":80},{"type":"null"}]},"thanksLine":{"anyOf":[{"type":"string","minLength":0,"maxLength":160},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false,"description":"How a website conversation runs. On a write, the fields sent replace theirs."},"SubjectTopic":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"grade":{"type":"array","prefixItems":[{"type":"integer"},{"type":"integer"}],"description":"`[lowest, highest]` grade, 1 to 12."},"skills":{"type":"array","items":{"type":"string","minLength":1},"description":"The skills this topic trains (the rubric and the start screen refer to them). Left out on a write: kept as they are."},"prerequisites":{"type":"array","items":{"type":"string"}},"sourceHint":{"type":"string","description":"Which of the organisation's documents covers it."},"keyPoints":{"type":"array","items":{"type":"string"},"description":"What the avatar teaches first, in plain language."},"checklist":{"type":"array","items":{"type":"string"}},"region":{"type":"string","enum":["uk","us","intl"],"description":"The country the content is written for: `uk` or `us`, or `intl` for a law module's version for everywhere outside the UK; left out = anywhere."}},"required":["id","skills"],"description":"A curriculum topic."},"SubjectTopicInput":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":60},"title":{"anyOf":[{"type":"string","minLength":0,"maxLength":80},{"type":"null"}]},"description":{"anyOf":[{"type":"string","minLength":0,"maxLength":300},{"type":"null"}]},"grade":{"anyOf":[{"type":"array","prefixItems":[{"type":"integer","minimum":1,"maximum":12},{"type":"integer","minimum":1,"maximum":12}],"description":"`[lowest, highest]` grade, 1 to 12."},{"type":"null"}]},"skills":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1},"description":"The skills this topic trains (the rubric and the start screen refer to them). Left out on a write: kept as they are."},"prerequisites":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"sourceHint":{"anyOf":[{"type":"string","minLength":0,"maxLength":200,"description":"Which of the organisation's documents covers it."},{"type":"null"}]},"keyPoints":{"anyOf":[{"maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":400},"description":"What the avatar teaches first, in plain language."},{"type":"null"}]},"checklist":{"anyOf":[{"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"}]},"region":{"anyOf":[{"type":"string","enum":["uk","us","intl"],"description":"The country the content is written for: `uk` or `us`, or `intl` for a law module's version for everywhere outside the UK; left out = anywhere."},{"type":"null"}]}},"additionalProperties":false,"description":"A curriculum topic."},"SubjectVersion":{"type":"object","properties":{"version":{"type":"integer"},"live":{"type":"boolean"},"draft":{"type":"boolean","description":"The pending draft."},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"createdBy":{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key","system"]},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`usr_…` or `key_…`; null for the system."}},"required":["type","id"]}},"required":["version","live","draft","note","createdAt","createdBy"],"description":"A stored version of a subject's content."},"SubjectWidget":{"type":"object","properties":{"email":{"type":"string","description":"Where visitors' requests are emailed."}},"description":"A website widget's subject: set through `PUT /personas/{id}/widget`. Read-only here: a write may only send it back as it is."},"SubjectWidgetInput":{"type":"object","properties":{"email":{"anyOf":[{"type":"string","description":"Where visitors' requests are emailed."},{"type":"null"}]}},"additionalProperties":false,"description":"A website widget's subject: set through `PUT /personas/{id}/widget`. Read-only here: a write may only send it back as it is."},"Transcript":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"pattern":"^sess_.*","description":"Session id (`sess_…`).","examples":["sess_cmfq2b7x10000abcd1234"]},"turns":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptTurn"}},"kept":{"type":"boolean","description":"True when the turns are the whole transcript; false when the session's subject keeps nothing (no turns)."},"aiGenerated":{"type":"boolean","const":true,"description":"Always true: the avatar's video, voice and words are AI-generated (EU AI Act Article 50(2)). Keep this marker with the content when you store or pass it on."}},"required":["sessionId","turns","kept","aiGenerated"],"description":"The turn-by-turn transcript."},"TranscriptFinalData":{"type":"object","properties":{"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string","enum":["user","assistant"]},{"type":"null"}]},"text":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}]},"ts":{"anyOf":[{"type":"number"},{"type":"null"}]}},"description":"One finished turn of a session the API started, with its words. Needs includeConversation."},"TranscriptTurn":{"type":"object","properties":{"role":{"type":"string","description":"user or assistant (the avatar); a duo's turns carry `speaker`.","examples":["user"]},"text":{"type":"string"},"aiGenerated":{"type":"boolean","description":"True for the avatar's turns (AI-generated words, EU AI Act Article 50(2)); false for what the person said."}},"required":["role","text","aiGenerated"],"additionalProperties":{},"description":"One turn as recorded: `ts` (when it was stored), `speaker` for a duo, `words` with timings when speech recognition gave them."},"Unit":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},"parentId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The unit above it; null at the top level."},"name":{"type":"string"},"kind":{"type":"string","description":"class, team, group, department, region, school or club.","examples":["team"]},"gradeBand":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A class's year or grade: the default for learners who join with its code."},"disabled":{"type":"boolean","description":"Switched off (itself or a unit above it): it grants nothing until switched on."},"joinCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The code learners join with, where joining by code is on."},"sortOrder":{"type":"integer"},"counts":{"type":"object","properties":{"members":{"type":"integer"},"learners":{"type":"integer"},"leaders":{"type":"integer"},"waiting":{"type":"integer","description":"Learners whose place waits for a parent's consent."}},"required":["members","learners","leaders","waiting"]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","parentId","name","kind","gradeBand","disabled","joinCode","sortOrder","counts","createdAt","updatedAt"],"description":"A class, team or group in the organisation's tree."},"UnitCreatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leaderUserId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A unit was created."},"UnitDeletedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"movedTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"subTeams":{"anyOf":[{"type":"integer"},{"type":"null"}]},"portals":{"anyOf":[{"type":"integer"},{"type":"null"}]},"subjects":{"anyOf":[{"type":"integer"},{"type":"null"}]},"assignments":{"anyOf":[{"type":"integer"},{"type":"null"}]},"membershipsRemoved":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"description":"A unit was deleted."},"UnitRenamedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"from":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"to":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"duplicateName":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A unit was renamed."},"UnitSwitchData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"unitsBelow":{"anyOf":[{"type":"integer"},{"type":"null"}]},"stillOffBecauseOfAParent":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A unit switched off or on, with everything below it."},"UnitUpdatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"anyOf":[{"type":"number"},{"type":"null"}]},"gradeBand":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]}},"description":"A unit was moved or changed."},"UnitWritten":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},"parentId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The unit above it; null at the top level."},"name":{"type":"string"},"kind":{"type":"string","description":"class, team, group, department, region, school or club.","examples":["team"]},"gradeBand":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A class's year or grade: the default for learners who join with its code."},"disabled":{"type":"boolean","description":"Switched off (itself or a unit above it): it grants nothing until switched on."},"joinCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The code learners join with, where joining by code is on."},"sortOrder":{"type":"integer"},"counts":{"type":"object","properties":{"members":{"type":"integer"},"learners":{"type":"integer"},"leaders":{"type":"integer"},"waiting":{"type":"integer","description":"Learners whose place waits for a parent's consent."}},"required":["members","learners","leaders","waiting"]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"duplicateName":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^unit_.*","description":"Unit id (`unit_…`).","examples":["unit_cmfq2b7x10000abcd1234"]},"name":{"type":"string"}},"required":["id","name"]},{"type":"null"}],"description":"Another unit at the same level already has this name (allowed, flagged)."}},"required":["id","parentId","name","kind","gradeBand","disabled","joinCode","sortOrder","counts","createdAt","updatedAt","duplicateName"],"description":"A unit as created or changed."},"UpdateMembershipInput":{"type":"object","properties":{"role":{"type":"string","enum":["OWNER","ADMIN","AVATAR_BUILDER","WORKSPACE_ADMIN","LEADER","LEARNER","OBSERVER"],"description":"OWNER (never given or changed through the API), ADMIN, AVATAR_BUILDER, WORKSPACE_ADMIN (these four at the organisation level only), LEADER, LEARNER, OBSERVER."},"unitId":{"anyOf":[{"description":"Unit id (`unit_…`).","type":"string"},{"type":"null"}]},"gradeBand":{"anyOf":[{"type":"string","description":"A year or grade: a number (\"5\") or a range (\"7-9\").","examples":["5"]},{"type":"null"}]},"ageBand":{"description":"`\"18+\"` marks an adult learner (a place waiting for consent is switched on); null clears it.","anyOf":[{"type":"string","enum":["18+"],"description":"`\"18+\"` marks a learner as an adult: they start without a parent's or guardian's consent, and a place of theirs waiting for consent is switched on. Only on a learner's place, and only while the organisation has switched on \"Mark learners who are adults (18+)\" (`409 conflict`, `details.reason: \"adult_learners_off\"`).","examples":["18+"]},{"type":"null"}]},"status":{"description":"Switch this place off or on. A place waiting for consent turns active only through guardian consent.","type":"string","enum":["active","disabled"]}}},"UpdateSubjectInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"unitId":{"description":"The unit it belongs to; null: the organisation level.","anyOf":[{"description":"Unit id (`unit_…`).","type":"string"},{"type":"null"}]},"visitorLanguage":{"description":"A website subject only: follow the visitor's language, keep to its `languages` (`listed`), or English only; null goes back to the organisation's own setting.","anyOf":[{"type":"string","enum":["follow","listed","english"]},{"type":"null"}]}}},"UpdateUnitInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"parentId":{"description":"Move it under another unit; null moves it to the top level.","anyOf":[{"description":"Unit id (`unit_…`).","type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer"},"gradeBand":{"description":"null clears it.","anyOf":[{"type":"string","description":"A year or grade: a number (\"5\") or a range (\"7-9\").","examples":["5"]},{"type":"null"}]},"disabled":{"description":"Switch it (and everything below it) off or on. Nothing is deleted.","type":"boolean"}}},"UpgradeRequired":{"type":"object","properties":{"error":{"type":"string","const":"upgrade_required"},"feature":{"type":"string"},"plan":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"},"limit":{"type":"number"},"reason":{"description":"The feature's switch is off because the plan doesn't include it (`plan` names the plan that does).","type":"string","const":"plan_required"}},"required":["error","feature","plan","message"],"description":"A plan refusal for keys on the 2026-07-08 contract. From 2026-10-01 it is an Error with code `upgrade_required` and `details: { feature, plan, limit, reason }`."},"Usage":{"type":"object","properties":{"plan":{"type":"object","properties":{"key":{"type":"string","description":"free, starter, plus, pro, business or enterprise.","examples":["pro"]},"name":{"type":"string"},"interval":{"type":"string","description":"month or year.","examples":["month"]}},"required":["key","name","interval"]},"unlimited":{"type":"boolean","description":"An unlimited account has no minute counts (the minute fields are null)."},"includedMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The plan's minutes this cycle."},"minutesUsed":{"type":"number","description":"Session time in the period, in minutes."},"remainingMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Every minute the account can still spend: plan, minute packs and bonus."},"cycle":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"end":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["start","end"]},"minutes":{"anyOf":[{"type":"object","properties":{"planIncluded":{"type":"integer"},"planUsed":{"type":"integer"},"planLeft":{"type":"integer"},"purchasedLeft":{"type":"integer","description":"Minute packs; they never expire."},"bonusLeft":{"type":"integer"},"totalLeft":{"type":"integer"}},"required":["planIncluded","planUsed","planLeft","purchasedLeft","bonusLeft","totalLeft"]},{"type":"null"}]},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"end":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["start","end"]},"sessionCount":{"type":"integer"},"bySource":{"type":"object","properties":{"portal":{"type":"number"},"api":{"type":"number"}},"required":["portal","api"]},"byDay":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"YYYY-MM-DD (UTC)."},"minutes":{"type":"number"},"sessions":{"type":"integer"}},"required":["date","minutes","sessions"]}},"byPersona":{"type":"array","items":{"type":"object","properties":{"personaId":{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},"personaName":{"type":"string"},"minutes":{"type":"number"},"sessions":{"type":"integer"}},"required":["personaId","personaName","minutes","sessions"]}}},"required":["plan","unlimited","includedMinutes","minutesUsed","remainingMinutes","cycle","minutes","period","sessionCount","bySource","byDay","byPersona"],"description":"Session time for the period, with the plan and minutes from the account's minutes. There is no overage: when minutes run out, new sessions can't start until more are added."},"UsageThresholdData":{"type":"object","properties":{"threshold":{"anyOf":[{"type":"string"},{"type":"null"}]},"minutesLeft":{"anyOf":[{"type":"number"},{"type":"null"}]},"planMinutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"planUsedPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"renewsOn":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:\\d{2})$"},{"type":"null"}]}},"description":"The organisation's minutes crossed a warning level."},"VisitorDetailRemovedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"fields":{"anyOf":[{"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"null"}]}},{"type":"null"}]}},"description":"A website visitor asked for details to be forgotten: which fields to delete from your systems."},"VisitorSessionEndedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workspaceName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"minutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"screening":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"typed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"restarted":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"withdrawn":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"unverified":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"reaped":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"handoff":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"booking":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"resolved":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A website visitor's conversation ended (never a candidate's interview)."},"VisitorsDoor":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The visitor page to hand out (or the custom domain that leads there); null when no subject opens to visitors."},"open":{"type":"boolean","description":"Visitors can come in now."},"readiness":{"anyOf":[{"$ref":"#/components/schemas/DoorReadiness"},{"type":"null"}],"description":"Null when no subject opens to visitors (a website assistant or a screening role)."},"allowedOrigins":{"type":"array","items":{"type":"string"},"description":"The only websites that may show the visitor page in a frame and start conversations from it; [] = any."},"script":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The snippet that puts the visitor page on your website."}},"required":["url","open","readiness","allowedOrigins","script"],"description":"The visitors' door: people come in without signing in."},"VisitorsDoorUpdate":{"type":"object","properties":{"allowedOrigins":{"description":"Website addresses (`https://www.example.com`); [] allows any website again.","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}},"open":{"description":"`true` opens the portal to visitors (needs `portals:publish`; runs the go-live check on a published portal, and lets outside people in); `false` closes it.","type":"boolean"}}},"Voice":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^vo_.*","description":"Voice id (`vo_…`).","examples":["vo_cmfq2b7x10000abcd1234"]},"name":{"type":"string"},"language":{"type":"string","description":"Its default language (a catalogue code).","examples":["en"]},"languages":{"type":"array","items":{"type":"string"},"description":"The languages this voice is promised in, as catalogue codes (GET /languages): every catalogue language for a studio voice, the ten marked for duos for a cloned voice. Set the language on the persona or the session, not by choosing another voice."},"engine":{"type":"string","enum":["premier","global"],"description":"The voice engine a persona speaking with this voice runs on: global for the studio voices, premier for cloned voices."},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"female or male for a studio voice; null when not known."},"kind":{"type":"string","enum":["builtin","custom"],"description":"builtin: a studio voice; custom: your organisation's clone."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","name","language","languages","engine","gender","kind","createdAt"],"description":"A voice. One voice speaks every language in `languages` in its own timbre: choose a voice for how it sounds."},"VoiceCloneCompletedData":{"type":"object","properties":{"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"description":"A cloned voice is ready to use."},"VoiceCloneInput":{"type":"object","properties":{"name":{"description":"Default \"My voice\".","type":"string"},"audioBase64":{"type":"string","description":"10 to 60 seconds of clean speech: base64, or a data:audio/… URI (25 MB at most)."},"format":{"description":"The sample's format when it isn't in the data URI.","examples":["wav"],"type":"string"},"consent":{"$ref":"#/components/schemas/Consent"}},"required":["audioBase64","consent"],"description":"Clone a voice from a short sample, with the consent of the person it belongs to."},"VoiceEngine":{"type":"object","properties":{"name":{"type":"string","examples":["Multilingual Global"]},"languageCount":{"type":"integer","description":"How many catalogue languages this engine's voices are promised in."},"voiceCloning":{"type":"boolean"},"default":{"type":"boolean","description":"The studio voices run on it."},"note":{"type":"string"}},"required":["name","languageCount","voiceCloning","default","note"],"description":"A voice engine. The voice decides which one a persona runs on: see `Voice.engine`."},"Webhook":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^wh_.*","description":"Webhook id (`wh_…`).","examples":["wh_cmfq2b7x10000abcd1234"]},"url":{"type":"string","description":"Where deliveries go: a public https address, checked again before every attempt."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string"},"description":"The event types it receives; [\"*\"] = every type except transcript.final, which must be named."},"includeConversation":{"type":"boolean","description":"Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in `events`), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding `transcripts:read`; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on."},"active":{"type":"boolean","description":"False while switched off, and after three days of failed deliveries (then `pausedAt` says when)."},"pausedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When it was paused after failing every delivery for three days; PATCH { active: true } resumes it."},"apiVersion":{"type":"string","enum":["2026-07-08","2026-10-01"],"description":"The contract its deliveries are written in (the creating key's; PATCH to move it)."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","url","description","events","includeConversation","active","pausedAt","apiVersion","createdAt","updatedAt"],"description":"A signed webhook. Deliveries: `X-Zentiq-Signature: sha256=HMAC(secret, \"<X-Zentiq-Timestamp>.<body>\")`, retried for about two days; never redirected."},"WebhookDeleted":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","minLength":1,"pattern":"^wh_.*","description":"Webhook id (`wh_…`).","examples":["wh_cmfq2b7x10000abcd1234"]}},"required":["deleted","id"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","description":"`whd_…` (sent as X-Zentiq-Delivery-Id). Keys on the 2026-07-08 contract receive the id without its prefix."},"webhookId":{"type":"string","minLength":1,"pattern":"^wh_.*","description":"Webhook id (`wh_…`).","examples":["wh_cmfq2b7x10000abcd1234"]},"eventId":{"anyOf":[{"type":"string","minLength":1,"pattern":"^evt_.*","description":"Event id (`evt_…`).","examples":["evt_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"The event delivered (`evt_…`, the envelope's `id`); null for deliveries logged before the outbox."},"event":{"type":"string","description":"The event's type."},"state":{"type":"string","enum":["pending","retrying","delivered","failed"],"description":"pending (the first attempt is under way), retrying (the next attempt is at `nextAttemptAt`), delivered, failed (no attempt left, or closed: see `errorCode`)."},"attempts":{"type":"integer"},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The HTTP status of the last attempt; null when none was reached."},"ok":{"type":"boolean"},"responseMs":{"anyOf":[{"type":"integer"},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the last attempt failed or the delivery closed: http_status, redirect, timeout, network, address_refused, internal_error, webhook_inactive, webhook_paused, unsubscribed, withdrawn, event_gone."},"nextAttemptAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]}},"required":["id","webhookId","eventId","event","state","attempts","status","ok","responseMs","errorCode","nextAttemptAt","createdAt"],"description":"One event's delivery to one webhook, with its last attempt."},"WebhookEnvelope":{"type":"object","required":["id","type","apiVersion","organizationId","createdAt","data"],"description":"Every webhook's body (2026-10-01). Verify `X-Zentiq-Signature` before trusting it; de-duplicate by `id`.","properties":{"id":{"type":"string","description":"The event's id (`evt_…`), stable across retries."},"type":{"type":"string"},"apiVersion":{"type":"string","enum":["2026-07-08","2026-10-01"]},"organizationId":{"type":"string","description":"`org_…`"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object"},"aiGenerated":{"type":"boolean","const":true,"description":"Present, and true, when `data` carries words an avatar wrote: a summary, a report or an avatar's turn (EU AI Act Article 50(2)). Every contract."}}},"WebhookEvent":{"type":"object","required":["id","type","createdAt","data"],"description":"The JSON body of every webhook delivery (headers X-Zentiq-Signature, X-Zentiq-Timestamp, X-Zentiq-Event). Every event's `data` is an allowlist: ids, statuses, timestamps, counts and the organisation's own short names. Conversation words (transcript.final's text, summaries, report feedback and quotes, a visitor's questions and answers, a rating's comment, knowledge.gap's questions) go only to a webhook with `includeConversation` on, and never from a child's, a candidate's, a practice, a held or a safety-flagged session; without it they are null (transcript.final is not sent). lead.captured, booking.requested and handoff.requested carry the visitor's contact details (`captured`: name, email, phone, company, role, location, preferred time, reference), their `consent` and a booking's `service` and `when`, for your own CRM; what they described in their own words (`captured.need`, `budget`, `timeline`, a lead's `answers`, a hand-off's `reason`) goes only with `includeConversation`. Never sent: safety flags (safety.flagged is not delivered, and reports carry no flags or flag counts), admin notes, a candidate's scores or bands, results that are held for review, kept from the person or voided (score, percent, passed and marks are null), a practice attempt's score, the minor flag, a session's plan, people's names and notes.","properties":{"id":{"type":"string","example":"evt_…"},"type":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}},"WebhookInput":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"A public https address. Private and local addresses are refused; redirects are never followed."},"events":{"description":"Event types, or [\"*\"] (the default). transcript.final needs `includeConversation: true`.","minItems":1,"maxItems":100,"type":"array","items":{"type":"string"}},"description":{"type":"string","maxLength":200},"includeConversation":{"description":"Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in `events`), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding `transcripts:read`; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on.","type":"boolean"}},"required":["url"],"description":"A new webhook."},"WebhookList":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"WebhookPatch":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"events":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"}},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"active":{"description":"true resumes a paused webhook (its failing run starts again); false switches it off.","type":"boolean"},"apiVersion":{"description":"Move its deliveries to another contract.","type":"string","enum":["2026-07-08","2026-10-01"]},"includeConversation":{"description":"Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in `events`), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding `transcripts:read`; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on.","type":"boolean"}},"description":"What to change on a webhook; anything left out stays."},"WebhookTestData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"webhookId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A test ping, sent only to the webhook it was asked for."},"WebhookWithSecret":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^wh_.*","description":"Webhook id (`wh_…`).","examples":["wh_cmfq2b7x10000abcd1234"]},"url":{"type":"string","description":"Where deliveries go: a public https address, checked again before every attempt."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string"},"description":"The event types it receives; [\"*\"] = every type except transcript.final, which must be named."},"includeConversation":{"type":"boolean","description":"Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in `events`), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding `transcripts:read`; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on."},"active":{"type":"boolean","description":"False while switched off, and after three days of failed deliveries (then `pausedAt` says when)."},"pausedAt":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},{"type":"null"}],"description":"When it was paused after failing every delivery for three days; PATCH { active: true } resumes it."},"apiVersion":{"type":"string","enum":["2026-07-08","2026-10-01"],"description":"The contract its deliveries are written in (the creating key's; PATCH to move it)."},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp.","examples":["2026-09-25T12:00:00.000Z"]},"secret":{"type":"string","description":"The signing secret: returned once, at creation."}},"required":["id","url","description","events","includeConversation","active","pausedAt","apiVersion","createdAt","updatedAt","secret"],"description":"A webhook just made, with its signing secret (shown once)."},"Widget":{"type":"object","properties":{"personaId":{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},"exists":{"type":"boolean","description":"The widget has been set up (the first PUT makes it)."},"on":{"type":"boolean","description":"Switched on."},"live":{"type":"boolean","description":"Switched on and showing: its public door is open and it has websites to show on."},"look":{"$ref":"#/components/schemas/WidgetLook"},"label":{"type":"string","description":"The button's words as visitors see them."},"allowedOrigins":{"type":"array","items":{"type":"string"},"description":"The websites that may show it (every other website gets nothing)."},"requestEmail":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Where visitors' messages and requests go."},"template":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What its conversations are set up as: support-agent or receptionist."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WidgetStep"},"description":"What it needs before it goes live, in order."},"documents":{"type":"integer","description":"Documents it answers from (the persona's knowledge)."},"answers":{"type":"integer","description":"Approved answers of its own."},"publicId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The widget's public id (`<organisation>/w-…`): all the snippet names.","examples":["acme/w-3f9a1c2b7d4e"]},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The code to paste into your pages, as the layout needs it."},"configUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Where a website reads the widget's public settings (for your own button)."},"portalId":{"anyOf":[{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"Its hidden website-assistant portal (never listed by GET /portals)."},"subjectId":{"anyOf":[{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"Its subject: edit its answers through /subjects/{id}/content."},"outOfDate":{"type":"boolean","description":"The persona's first line or languages changed since the widget was saved; any PUT brings them over."}},"required":["personaId","exists","on","live","look","label","allowedOrigins","requestEmail","template","steps","documents","answers","publicId","snippet","configUrl","portalId","subjectId","outOfDate"],"description":"A persona's website widget."},"WidgetInput":{"type":"object","properties":{"purpose":{"description":"What its conversations are set up as when it is first made: support (a support agent) or reception (a receptionist).","type":"string","enum":["support","reception"]},"layout":{"enum":["floating","inline"],"description":"floating (a button in a corner) or inline (inside your page).","type":"string"},"initialState":{"enum":["minimized","expanded"],"description":"minimized or expanded (\"minimised\" is read too).","type":"string"},"position":{"enum":["bottom-right","top-right","bottom-left","top-left"],"description":"A floating widget's corner (\"right\" and \"left\" read as the bottom ones).","type":"string"},"label":{"maxLength":40,"description":"The button's words (null or \"\" for \"Talk to <name>\").","anyOf":[{"type":"string"},{"type":"null"}]},"accent":{"description":"The button's colour, #rrggbb.","type":"string"},"start":{"enum":["voice","chat"],"description":"The panel opens ready to talk (voice) or to type (chat).","type":"string"},"allowedOrigins":{"maxItems":20,"description":"Replaces the websites that may show it, such as https://www.example.com (20 at most).","type":"array","items":{"type":"string"}},"requestEmail":{"description":"Where visitors' messages and requests go; null clears it.","anyOf":[{"type":"string"},{"type":"null"}]},"on":{"description":"Switch it on (needs the portals:publish scope and what `steps` lists) or off (its door closes at once).","type":"boolean"}},"description":"What to change; the first PUT makes the widget. What isn't sent stays as it is."},"WidgetLook":{"type":"object","properties":{"layout":{"type":"string","enum":["floating","inline"],"description":"floating: a button in a corner of every page; inline: the panel inside an element of your page."},"initialState":{"type":"string","enum":["minimized","expanded"],"description":"minimized: the button only until a visitor clicks; expanded: the panel opens with the page (nothing listens until a visitor presses Talk)."},"position":{"type":"string","enum":["bottom-right","top-right","bottom-left","top-left"],"description":"The corner a floating widget sits in."},"label":{"type":"string","description":"The button's own words; \"\" for \"Talk to <name>\"."},"accent":{"type":"string","description":"The button's colour, #rrggbb.","examples":["#0f766e"]},"start":{"type":"string","enum":["voice","chat"],"description":"The panel opens ready to talk, or ready to type."}},"required":["layout","initialState","position","label","accent","start"],"description":"How the widget shows on your pages."},"WidgetSaved":{"type":"object","properties":{"personaId":{"type":"string","minLength":1,"pattern":"^pa_.*","description":"Persona id (`pa_…`).","examples":["pa_cmfq2b7x10000abcd1234"]},"exists":{"type":"boolean","description":"The widget has been set up (the first PUT makes it)."},"on":{"type":"boolean","description":"Switched on."},"live":{"type":"boolean","description":"Switched on and showing: its public door is open and it has websites to show on."},"look":{"$ref":"#/components/schemas/WidgetLook"},"label":{"type":"string","description":"The button's words as visitors see them."},"allowedOrigins":{"type":"array","items":{"type":"string"},"description":"The websites that may show it (every other website gets nothing)."},"requestEmail":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Where visitors' messages and requests go."},"template":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What its conversations are set up as: support-agent or receptionist."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WidgetStep"},"description":"What it needs before it goes live, in order."},"documents":{"type":"integer","description":"Documents it answers from (the persona's knowledge)."},"answers":{"type":"integer","description":"Approved answers of its own."},"publicId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The widget's public id (`<organisation>/w-…`): all the snippet names.","examples":["acme/w-3f9a1c2b7d4e"]},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The code to paste into your pages, as the layout needs it."},"configUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Where a website reads the widget's public settings (for your own button)."},"portalId":{"anyOf":[{"type":"string","minLength":1,"description":"Portal id (`portal_…`).","examples":["portal_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"Its hidden website-assistant portal (never listed by GET /portals)."},"subjectId":{"anyOf":[{"type":"string","minLength":1,"description":"Subject id (`sub_…`).","examples":["sub_cmfq2b7x10000abcd1234"]},{"type":"null"}],"description":"Its subject: edit its answers through /subjects/{id}/content."},"outOfDate":{"type":"boolean","description":"The persona's first line or languages changed since the widget was saved; any PUT brings them over."},"said":{"type":"string","description":"What happened, in one sentence."}},"required":["personaId","exists","on","live","look","label","allowedOrigins","requestEmail","template","steps","documents","answers","publicId","snippet","configUrl","portalId","subjectId","outOfDate","said"],"description":"The widget as saved."},"WidgetStep":{"type":"object","properties":{"key":{"type":"string","enum":["websites","email","knowledge","organisation","setup"]},"done":{"type":"boolean"},"title":{"type":"string"},"fix":{"type":"string","description":"What to do, in one sentence; \"\" when done."}},"required":["key","done","title","fix"],"description":"One thing the widget needs before it can go live."},"WidgetUpdatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"personaId":{"anyOf":[{"type":"string"},{"type":"null"}]},"on":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"live":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"description":"A persona's website widget was switched on or off, or changed."},"WorkspaceCreatedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"blueprintKey":{"anyOf":[{"type":"string"},{"type":"null"}]}},"description":"A subject was created."},"WorkspacePublishedData":{"type":"object","properties":{"eventId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspaceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"userId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"blueprintVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"version":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"description":"A subject's version went live."}},"responses":{"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"]}}}}}]}}}},"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"]}}}}}]}}}},"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"]}}}}}]}}}},"ConsentRequired":{"description":"`consent` is missing, unticked or malformed (consent_required / consent_invalid), the wording version is not the current one (consent_outdated), or another field is invalid (invalid_request). Nothing was created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["consent_required","consent_invalid","consent_outdated","invalid_request"]}}}}}]}}}},"ConsentWithdrawn":{"description":"The persona's own face or voice had its consent withdrawn by the organisation, so it can't start new sessions","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["consent_withdrawn"]}}}}}]}}}},"FeatureNotInPlan":{"description":"The session uses something the plan doesn't include (the API, a duo, a cloned voice), or the account is paused","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["feature_not_in_plan","account_paused"]}}}}}]}}}},"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"]}}}}}]}}}},"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"]}}}}}]}}}},"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"]}}}}}]}}}},"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"]}}}}}]}}}},"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"]}}}}}]}}}},"UpgradeRequired":{"description":"The account's plan doesn't include this, or its limit is reached (custom avatars, documents). Not wrapped in the error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeRequired"}}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same request replays the first success for 24 hours.","schema":{"type":"string","maxLength":255}},"ZentiqVersion":{"name":"Zentiq-Version","in":"header","required":false,"description":"The contract to answer in: the key's pinned contract (the default) or a newer one.","schema":{"type":"string","enum":["2026-07-08","2026-10-01"]}}},"headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window for this key (or its organisation, when that is the tighter limit).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-Request-Id":{"description":"This request's id (quote it to support).","schema":{"type":"string","examples":["req_4f1c2e9a7b3d5e6f7a8b9c0d"]}},"Zentiq-Version":{"description":"The contract this answer is in.","schema":{"type":"string","enum":["2026-07-08","2026-10-01"]}}}},"x-zentiq-contracts":["2026-07-08","2026-10-01"],"x-zentiq-error-codes":{"invalid_request":{"status":400,"retryable":false,"description":"The request is malformed or a field is invalid; `param` says which."},"consent_required":{"status":400,"retryable":false,"description":"A likeness, voice or guardian attestation is missing."},"consent_invalid":{"status":400,"retryable":false,"description":"The consent attestation is not valid."},"consent_outdated":{"status":400,"retryable":false,"description":"The consent wording has changed; read it again and confirm the current version."},"unauthorized":{"status":401,"retryable":false,"description":"The API key is missing, invalid or revoked."},"insufficient_minutes":{"status":402,"retryable":false,"description":"No minutes left, or the organisation's own monthly cap is reached."},"forbidden":{"status":403,"retryable":false,"description":"The key lacks a scope (the message names it) or may not take this action."},"upgrade_required":{"status":403,"retryable":false,"description":"The plan lacks a feature or a limit is reached; `details` has `feature`, `plan` and `limit`, and `reason: plan_required` when a feature's switch is off because the plan doesn't include it."},"feature_not_in_plan":{"status":403,"retryable":false,"description":"A session can't start: the plan doesn't include it."},"account_paused":{"status":403,"retryable":false,"description":"A session can't start: the account is paused."},"candidate_interview":{"status":403,"retryable":false,"description":"A job interview is never read as a session: a hiring system reads a candidate's interview with GET /candidates/{id}/interview."},"learner_conversation":{"status":403,"retryable":false,"description":"A young learner's conversation stays in the Zentiq dashboard."},"not_found":{"status":404,"retryable":false,"description":"No such id in this organisation (an id of another kind is not found either)."},"conflict":{"status":409,"retryable":false,"description":"The resource's state doesn't allow this; `details.reason` says why."},"version_conflict":{"status":409,"retryable":false,"description":"`If-Match` or `baseVersion` is not the current version; `details.currentVersion`."},"session_ended":{"status":409,"retryable":false,"description":"The session has ended."},"duo_not_live":{"status":409,"retryable":false,"description":"The duo is not live yet."},"face_not_ready":{"status":409,"retryable":true,"description":"The persona's new or changed face is still being prepared on the live engine (about a minute); retry after `Retry-After`. `details.etaS` is the engine's estimate."},"consent_withdrawn":{"status":409,"retryable":false,"description":"The consent for this face or voice was withdrawn."},"on_hold":{"status":409,"retryable":false,"description":"The record is under a hold and can't change."},"idempotency_conflict":{"status":409,"retryable":false,"description":"The Idempotency-Key was used with a different request."},"idempotency_in_progress":{"status":409,"retryable":true,"description":"A request with this Idempotency-Key is still running; retry after `Retry-After`."},"gone":{"status":410,"retryable":false,"description":"The resource was deleted."},"too_large":{"status":413,"retryable":false,"description":"The body, a file or a field is too large."},"unsupported_media_type":{"status":415,"retryable":false,"description":"The file or content type is not supported."},"go_live_refused":{"status":422,"retryable":false,"description":"The go-live check refused it; `details.problems` lists what to fix."},"rate_limited":{"status":429,"retryable":true,"description":"Too many requests; retry after `Retry-After`."},"concurrency_limit":{"status":429,"retryable":true,"description":"Too many live sessions at once."},"server_error":{"status":500,"retryable":false,"description":"Something went wrong on Zentiq's side."},"upstream_error":{"status":502,"retryable":true,"description":"A service Zentiq relies on failed; retry shortly."},"capacity":{"status":503,"retryable":true,"description":"No capacity right now; retry shortly."},"consent_unverified":{"status":503,"retryable":true,"description":"The consent for this face or voice couldn't be checked just now, so nothing started (it fails closed); retry shortly."},"upstream_timeout":{"status":504,"retryable":true,"description":"A service Zentiq relies on timed out; retry shortly."}}}