Personas
Personas: a face, a voice and what they know and say.
/v1/personasList personas
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.
Query parameters
limitintegerPage size, 1-200 (default 50).
cursorstringThe
nextCursorof the previous page.kind"single" | "duo"single: one person; duo: two people in one conversation.
Returns
200 A page of personas. A page: data is a list of Persona, and nextCursor fetches the next page.
Fields of data
idstringrequiredPersona id (
pa_…).pattern `^pa_.*`
namestringrequiredsystemPromptstringrequiredgreetingstring | nullrequiredavatarIdstring | nullrequiredvoiceIdstring | nullrequiredBehaviour settings.
knowledgePersonaKnowledge | nullrequiredcastobjectrequiredWho the avatar is: one person, or a duo (two people in one conversation).
kind"single" | "duo"requiredpeopleobject[]requiredOne person, or a duo's two, by name.
namestringrequired
duoIdstring | nullrequiredThe duo (GET /duos/{id}) when it is one made from /duos; null otherwise.
avatarAvatar | nullrequiredvoiceVoice | nullrequiredcreatedAtstring (date-time)requiredISO 8601 UTC timestamp.
updatedAtstring (date-time)requiredISO 8601 UTC timestamp.
Errors
invalid_requestunauthorizedforbiddenupgrade_requiredrate_limitedserver_error
Request
curl "https://app.zentiqai.com/v1/personas?limit=20" \
-H "Authorization: Bearer $ZENTIQ_API_KEY"import { Zentiq } from "@zentiq/node";
const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const page = await zentiq.listPersonas({
limit: 20,
});import os
from zentiq import Zentiq
zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
page = zentiq.list_personas(limit=20)Example answer
{
"data": [
{
"id": "pa_cmfq2b7x10000abcd1234",
"name": "Zoe",
"systemPrompt": "…",
"greeting": "…",
"avatarId": "av_cmfq2b7x10000abcd1234",
"voiceId": "vo_cmfq2b7x10000abcd1234"
}
],
"error": null,
"requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d",
"nextCursor": null
}/v1/personasCreate a persona
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.
Body
namestringrequiredat most 200 characters
systemPromptstringrequiredThe character: who they are, what they help with, how they behave.
at most 16,000 characters
greetingstring | nullThe first thing they say.
at most 2,000 characters
avatarIdstringAvatar id (
av_…).voiceIdstringVoice id (
vo_…).voiceProfileIdstringdeprecatedDeprecated: use
voiceId.settingsPersonaSettingsInputBehaviour settings to set (see PersonaSettings).
Deprecated: use
settings.knowledgeobject | nullbaseIdsstring[]requiredKnowledge base ids (
kb_…), 1 to 20.topKnumberminScorenumbermaxCharsnumber
Returns
201 The new persona. data is Persona.
Fields of data
idstringrequiredPersona id (
pa_…).pattern `^pa_.*`
namestringrequiredsystemPromptstringrequiredgreetingstring | nullrequiredavatarIdstring | nullrequiredvoiceIdstring | nullrequiredBehaviour settings.
knowledgePersonaKnowledge | nullrequiredcastobjectrequiredWho the avatar is: one person, or a duo (two people in one conversation).
kind"single" | "duo"requiredpeopleobject[]requiredOne person, or a duo's two, by name.
namestringrequired
duoIdstring | nullrequiredThe duo (GET /duos/{id}) when it is one made from /duos; null otherwise.
avatarAvatar | nullrequiredvoiceVoice | nullrequiredcreatedAtstring (date-time)requiredISO 8601 UTC timestamp.
updatedAtstring (date-time)requiredISO 8601 UTC timestamp.
Errors
invalid_requestunauthorizedforbiddenupgrade_requiredconflictidempotency_conflictidempotency_in_progresstoo_largerate_limitedserver_error
Request
curl -X POST "https://app.zentiqai.com/v1/personas" \
-H "Authorization: Bearer $ZENTIQ_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "Zoe",
"systemPrompt": "…"
}'import { Zentiq } from "@zentiq/node";
const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.createPersona({
name: "Zoe",
systemPrompt: "…",
});import os
from zentiq import Zentiq
zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.create_persona({
"name": "Zoe",
"systemPrompt": "…",
})Example answer
{
"data": {
"id": "pa_cmfq2b7x10000abcd1234",
"name": "Zoe",
"systemPrompt": "…",
"greeting": "…",
"avatarId": "av_cmfq2b7x10000abcd1234",
"voiceId": "vo_cmfq2b7x10000abcd1234"
},
"error": null,
"requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}/v1/personas/{id}Get a persona
One of the organisation's own personas. A portal's persona is 404 here (as for PATCH and DELETE): use /portals/{id}/persona.
Path parameters
idstringrequiredPersona id (
pa_…); the id without its prefix is accepted too.
Returns
200 The persona. data is Persona.
Fields of data
idstringrequiredPersona id (
pa_…).pattern `^pa_.*`
namestringrequiredsystemPromptstringrequiredgreetingstring | nullrequiredavatarIdstring | nullrequiredvoiceIdstring | nullrequiredBehaviour settings.
knowledgePersonaKnowledge | nullrequiredcastobjectrequiredWho the avatar is: one person, or a duo (two people in one conversation).
kind"single" | "duo"requiredpeopleobject[]requiredOne person, or a duo's two, by name.
namestringrequired
duoIdstring | nullrequiredThe duo (GET /duos/{id}) when it is one made from /duos; null otherwise.
avatarAvatar | nullrequiredvoiceVoice | nullrequiredcreatedAtstring (date-time)requiredISO 8601 UTC timestamp.
updatedAtstring (date-time)requiredISO 8601 UTC timestamp.
Errors
invalid_requestunauthorizedforbiddenupgrade_requirednot_foundgonerate_limitedserver_error
Request
curl "https://app.zentiqai.com/v1/personas/pa_123" \
-H "Authorization: Bearer $ZENTIQ_API_KEY"import { Zentiq } from "@zentiq/node";
const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.getPersona("pa_123");import os
from zentiq import Zentiq
zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.get_persona("pa_123")Example answer
{
"data": {
"id": "pa_cmfq2b7x10000abcd1234",
"name": "Zoe",
"systemPrompt": "…",
"greeting": "…",
"avatarId": "av_cmfq2b7x10000abcd1234",
"voiceId": "vo_cmfq2b7x10000abcd1234"
},
"error": null,
"requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}/v1/personas/{id}Update a persona
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.
Path parameters
idstringrequiredPersona id (
pa_…); the id without its prefix is accepted too.
Body (optional)
namestringat most 200 characters
systemPromptstringThe character: who they are, what they help with, how they behave.
at most 16,000 characters
greetingstring | nullThe first thing they say.
at most 2,000 characters
avatarIdstringAvatar id (
av_…).voiceIdstringVoice id (
vo_…).voiceProfileIdstringdeprecatedDeprecated: use
voiceId.settingsPersonaSettingsInputBehaviour settings to set (see PersonaSettings).
Deprecated: use
settings.knowledgeobject | nullbaseIdsstring[]requiredKnowledge base ids (
kb_…), 1 to 20.topKnumberminScorenumbermaxCharsnumber
Returns
200 The persona. data is Persona.
Fields of data
idstringrequiredPersona id (
pa_…).pattern `^pa_.*`
namestringrequiredsystemPromptstringrequiredgreetingstring | nullrequiredavatarIdstring | nullrequiredvoiceIdstring | nullrequiredBehaviour settings.
knowledgePersonaKnowledge | nullrequiredcastobjectrequiredWho the avatar is: one person, or a duo (two people in one conversation).
kind"single" | "duo"requiredpeopleobject[]requiredOne person, or a duo's two, by name.
namestringrequired
duoIdstring | nullrequiredThe duo (GET /duos/{id}) when it is one made from /duos; null otherwise.
avatarAvatar | nullrequiredvoiceVoice | nullrequiredcreatedAtstring (date-time)requiredISO 8601 UTC timestamp.
updatedAtstring (date-time)requiredISO 8601 UTC timestamp.
Errors
invalid_requestunauthorizedforbiddenupgrade_requirednot_foundconflictgonetoo_largerate_limitedserver_error
Request
curl -X PATCH "https://app.zentiqai.com/v1/personas/pa_123" \
-H "Authorization: Bearer $ZENTIQ_API_KEY"import { Zentiq } from "@zentiq/node";
const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.updatePersona("pa_123");import os
from zentiq import Zentiq
zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.update_persona("pa_123")Example answer
{
"data": {
"id": "pa_cmfq2b7x10000abcd1234",
"name": "Zoe",
"systemPrompt": "…",
"greeting": "…",
"avatarId": "av_cmfq2b7x10000abcd1234",
"voiceId": "vo_cmfq2b7x10000abcd1234"
},
"error": null,
"requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}/v1/personas/{id}Delete a persona
Its own picture goes too when no other persona wears it. A duo is refused (409) while a portal uses it.
Path parameters
idstringrequiredPersona id (
pa_…); the id without its prefix is accepted too.
Returns
200 Deleted. data is object.
Fields of data
deletedtruerequiredidstringrequiredPersona id (
pa_…).pattern `^pa_.*`
Errors
invalid_requestunauthorizedforbiddenupgrade_requirednot_foundconflictrate_limitedserver_error
Request
curl -X DELETE "https://app.zentiqai.com/v1/personas/pa_123" \
-H "Authorization: Bearer $ZENTIQ_API_KEY"import { Zentiq } from "@zentiq/node";
const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.deletePersona("pa_123");import os
from zentiq import Zentiq
zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.delete_persona("pa_123")Example answer
{
"data": {
"deleted": true,
"id": "pa_cmfq2b7x10000abcd1234"
},
"error": null,
"requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}