Skip to main content
Use platform authentication for these endpoints. Browser requests name projectId. A project API key already fixes the acting project. Custom definitions are available only in their owning project. Predefined definitions are shared; their model settings belong to the acting project.

​
Use and save model settings

POST /v1/personas/{personaId}/use accepts projectId and an optional complete models object. Omit models to save the current core’s declared defaults. Repeated Use returns the existing settings. To change them, send PATCH with models:
Every supplied models object must be complete. Unknown fields, unsupported provider/model pairs, empty voice IDs, invalid types, and out-of-range speeds receive 422. Custom nonempty voice IDs are accepted without a provider lookup. Model settings contain no credentials. A current response includes parameterContract for the core and a separate settings object with id, models, createdAt, and updatedAt. settings is null before first use. A read does not create an association. Test selection creates it with defaults when needed. Settings changes create no core version.

​
Create and edit behavior

Creation requires name, identityName, personality, and language. description and a complete models selection are optional. Omitted models use the release’s complete recommended selection. All three records commit together. For a core edit, first read the current versionId, then send it as expectedVersionId with the changed behavior:
Use the ID returned by your current read. A stale base receives 409 version_conflict; a behavior edit without a base receives 422. The server locks the current definition so concurrent edits cannot overwrite a newer core. An unchanged core creates no version. Name and description remain live metadata and need no core base. Predefined cores cannot be edited by customers. The /fork endpoint takes an optional projectId body and returns a new project-owned definition at version
  1. It copies the current core and effective settings, without changing any test selection.
History responses carry identity name, personality, language, parameter contract, version identity, and creation time. They never contain today’s project model values. History is read-only; there is no restoration operation. Compatible shared core updates become current automatically. Current reads then return that core with the same saved project settings. Incompatible parameter changes are refused before publication. Clones receive no source updates, and historical reads remain separate from today’s settings. Runs freeze the persona version and settings at creation. Queued simulations and retries keep that selection after later settings or core updates. See Runs and persona concepts.