Portals and subjects
A portal (portal_…) is a ready-made experience people sign in to: a sales trainer, a maths tutor, a website receptionist, candidate screening. You build one from templates: GET /v1/portals/templates lists them, with whether the organisation's plan includes each.
Each template becomes a subject (sub_…) on the portal: what is practised, taught, answered or screened, with its own content (the facts, the scenarios, the questions, the FAQs). A subject can sit on more than one portal. Who speaks is the portal's persona.
Drafts and going live#
Nothing reaches people until you publish it.
- A new portal is a draft. Its subjects start from the template's example content, which is never allowed live.
- Subject content is edited as draft versions:
GET /v1/subjects/{id}/content, thenPATCH /v1/subjects/{id}/content. Each save is a new version;baseVersionstops you overwriting someone else's newer draft (409 version_conflict). - The go-live check says what is still missing, in plain words:
GET /v1/subjects/{id}/go-liveandGET /v1/portals/{id}/go-liveanswer{ ready, problems, warnings }. - Publishing makes the draft live:
POST /v1/subjects/{id}/publish, thenPOST /v1/portals/{id}/publish. A publish the check refuses is422 go_live_refused, withdetails.problems; nothing changes.
On the 2026-07-08 contract, a refused portal publish still answers 200 with the draft unchanged and a publishRefused message. Creating a portal with publish: true answers 201 on every contract: check its status (and publishRefused) before you send anyone to it.
Doors: how people come in#
| Door | Who | How |
|---|---|---|
| Members | The organisation's own people | The portal's address, https://app.zentiqai.com/d/<organisation>/<portal>, with the sign-in methods you chose (loginMethods). |
| Visitors | Anyone on your website (receptionist, support, leads, bookings) | The visitor page https://app.zentiqai.com/v/<organisation>/<portal>, as a frame, a button or a link; opened with PUT /v1/portals/{id}/doors/visitors, for the websites you list. |
| Embed | The people already signed in to your app | Your server asks for a five-minute, single-use embed token for each person (POST /v1/portals/{id}/embed-tokens), and your page mounts the portal with it. |
| Your domain | Everyone | A subdomain of yours pointing at the portal's sign-in, set up in the console. |
GET /v1/portals/{id}/doors shows which are open. An embed token works only on a published portal.
The website widget#
A persona's widget puts it in a corner of every page of your website with one line of code (GET and PUT /v1/personas/{id}/widget). Behind it is a small portal of its own, kept out of GET /v1/portals: the widget is managed through the persona. See An avatar on your website.
Who speaks#
GET /v1/portals/{id}/persona and PUT /v1/portals/{id}/persona read and change who speaks on a portal: the face and the voice by id (avatarId, voiceId), their character and greeting. A portal can also use one of your personas, a duo among them, given as personaId when you create it. That persona speaks elsewhere too, so using it, or changing it from the portal, needs personas:write as well as portals:write; a portal's own persona needs portals:write only.