API reference / Personas
Personas
A Persona combines a name, instructions, avatar, voice and conversation settings. Edit a private draft, then publish a version for visitors. Saving a draft does not change the published version.
Authentication
These owner routes require your signed-in portal account. They are not general SDK API-key routes. Resources belonging to another account are not returned. Use the Personas workspace to manage them in the portal.
Owner endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /auth/personas | List a page of your Personas |
| POST | /auth/personas | Create a private draft |
| GET | /auth/personas/options | Supported model choices and configured session limits |
| GET | /auth/personas/availability | Current conversation availability |
| GET | /auth/personas/{personaId} | Read a Persona and its draft |
| PATCH | /auth/personas/{personaId} | Save draft changes |
| DELETE | /auth/personas/{personaId} | Archive the Persona |
| POST | /auth/personas/{personaId}/publish | Publish the draft as a version |
| GET | /auth/personas/{personaId}/versions | List published versions |
| POST | /auth/personas/{personaId}/rollback | Restore a previously published version |
| GET | /auth/personas/{personaId}/sessions | List visitor sessions |
Drafts and publishing
Create with name, optional description, and draft. The draft includes system_prompt, greeting, avatar, voice, model, language, tools and session settings. Available providers and models depend on your account and the deployment; use the options and voice catalogues rather than hardcoding choices.
Updates include expected_updated_at from the current record. A stale edit returns 409 persona_conflict; reload before retrying so another edit is not overwritten. Publishing revalidates the configuration, including access to the selected avatar and voice provider. Never put provider keys into the draft.
Published status is separate from conversation availability. A published Persona can have a valid link while conversations are temporarily unavailable. The visitor page reports availability before starting a session.
Share and embed
Manage links from the Persona's Share tab or its owner link endpoints. Links can follow the latest published version or pin a version. See Share links and Embed a Persona.
For default SDK session configuration, see Session settings.