Skip to main content
POST
Create a role-play — coaching persona or interview-portal role-play (choose with `portal`)

Authorizations

Authorization
string
header
required

Supabase JWT — Authorization: Bearer <token>.

Body

application/json
name
string
required

Persona / session name.

Minimum string length: 1
Example:

"Difficult customer role-play"

interview_template_id
string<uuid>
required

Id of the interview template (avatar) the persona uses.

Minimum string length: 1
Example:

"baa3bf7c-6926-46fd-9005-16738a31f72d"

mojito_language_code
enum<string>
required

Platform language code used for the conversation. Must be one of the platform-languages.json codes.

Available options:
ar,
bg,
zh,
hr,
cs,
da,
nl,
en,
fil,
fi,
fr,
de,
el,
hi,
hu,
id,
it,
ja,
ko,
ms,
no,
pl,
pt,
br,
ro,
ru,
sk,
es,
sv,
ta,
th,
tr,
uk,
vi
Example:

"en"

status
enum<string>
required

Lifecycle status of the interview. Options — draft: Created but not published — not visible to candidates and cannot be run yet. Use to stage an interview before going live. | active: Published and live — candidates can run it..

Available options:
draft,
active
Example:

"active"

visibility
enum<string>
required

Who can discover and access the interview. Options — merchant_public: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. | merchant_invite: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. | merchant_unlisted: Reachable only via a direct link — not listed anywhere; share the link manually..

Available options:
merchant_public,
merchant_invite,
merchant_unlisted
Example:

"merchant_public"

persona_role_avatar
string
required

The role the AI avatar plays. Example: 'is to act as a happy customer responding to questions'.

Minimum string length: 1
Example:

"is to act as a happy customer responding to questions"

persona_role_user
string
required

The role the candidate (mentee) plays. Example: 'is to be a sales person trying to sell an additional product to the customer'.

Minimum string length: 1
Example:

"is to be a sales person trying to sell an additional product to the customer"

persona_avatar_who_is
string | null

Who the avatar represents (background/identity of the persona).

persona_avatar_knowledge
string | null

What the avatar knows — facts/context the avatar can draw on during the conversation.

persona_avatar_end_conditions
string | null

Conditions under which the avatar should end the session.

opening_line
string | null

The avatar's opening line — the FIRST thing it says out loud when the session starts, before the candidate has said anything. This is a literal spoken line, NOT a description: write the exact words the avatar should say, in character and consistent with persona_role_avatar. For an escalated scenario it should already convey that state (e.g. an angry customer opens angrily). If omitted, the platform inserts a generic default ("Hello"), which is usually a weak opener — set this for anything other than a neutral greeting.

Example:

"Oh, finally — someone actually comes over! I've been waiting for ages. Are you going to help me or not?"

candidate_expectations
string | null

Mentee assessment goals — free-text describing what the candidate is expected to achieve (max 2100 chars).

Maximum string length: 2100
recording
enum<string> | null

Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — audio_first_5_answers: Audio-only cheating detection, first 5 answers only. | audio_all: Audio-only cheating detection on every answer. | video_all: Audio + video cheating detection on every answer (candidate is recorded for all answers). | video_first_5_answers: Audio + video cheating detection, first 5 answers only..

Available options:
audio_first_5_answers,
audio_all,
video_all,
video_first_5_answers
Example:

"video_all"

recording_full_session
enum<string> | null

Full interview-session recording (includes the avatar and voice) produced as a single file. Independent of recording. Omit/null to disable. Options — audio_all: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. | video_all: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits..

Available options:
audio_all,
video_all
Example:

"video_all"

result_view
enum<string> | null

Result screen shown to the candidate after finishing. With any value other than none, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — none: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). | minimal: Minimal results layout, no score shown. | minimal_with_score: Minimal results layout including the overall score. | advanced: Advanced results layout with more detail. | full: Full results layout with all sections. | full_expand_scores: Full results with every score breakdown expanded..

Available options:
none,
minimal,
minimal_with_score,
advanced,
full,
full_expand_scores
Example:

"full"

interview_conversation_speed
enum<string> | null

Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — slower: The avatar speaks more slowly — easier to follow for non-native speakers. | normal: Default speaking pace. | faster: The avatar speaks more quickly for a snappier conversation..

Available options:
slower,
normal,
faster
Example:

"normal"

candidate_video_introduction
enum<string> | null

Whether a candidate video introduction is optional or required.

Available options:
optional,
required
Example:

"optional"

max_duration
number | null

Maximum conversation duration in seconds. Defaults to 1200 (20 min) when omitted.

Example:

1200

code
string | null

Optional external code/reference for the persona.

Example:

"my code"

cover_image_url
string | null

Cover image URL.

Example:

"https://example.com/cover.png"

interview_location
string | null

Optional location label shown for the session.

Example:

"remote"

merchant_id
string | null

Merchant id. Admin / sub-merchant callers only; otherwise taken from your token.

Example:

"28106cba-1c27-4e53-b149-32113e5e8e31"

recruiter_profile_id
string | null

Profile id of the recruiter owning this persona. Must be a merchant/merchant_owner/admin profile of the same merchant.

welcome_message
string | null

Custom welcome message spoken to the candidate before the role-play starts — set it; omitting it leaves a generic platform default. This is the scene-setting message; the avatar's first in-character line is opening_line, which comes after it.

Example:

"Welcome! You are about to speak with a customer who is unhappy about a recent price increase."

thank_you_message
string | null

Custom thank-you message shown after the session — set it; omitting it leaves a generic platform default.

Example:

"Thanks — your role-play has been recorded and will be reviewed by the hiring team."

tags
string[] | null

Free-form tags stored on the persona.

Example:
portal
enum<string> | null

REQUIRED IN PRACTICE — pick deliberately; the default is the coaching product, not the recruiting one. interview: an interview role-play. Choose this for ANY recruiting or assessment use case (screening candidates, hiring, sales role-plays for applicants). Candidates are invited through the normal invitation flow, results are visible to the recruiter alongside ordinary interview results, it is billed against your merchant credits on the same basis as an interview, and attempts are capped (see interview_attempts). | coaching (DEFAULT when omitted): the classic coaching persona for practice/training. Runs on the coaching portal, is consumed against the mentee's own coaching credits, is started by the mentee from the catalogue or a shared link, and its results are NOT visible to recruiters. The conversation itself behaves identically in both cases — only the portal, billing, visibility and attempt limits differ.

Available options:
coaching,
interview
Example:

"interview"

interview_attempts
number | null

Allowed candidate attempts (1-20), defaulting to 3. Only meaningful when portal is interview; coaching personas are unlimited. A recruiter can still grant an extra attempt afterwards.

Required range: 1 <= x <= 20
Example:

3

is_embedded
boolean | null

Set true when the persona will be embedded as an iframe on an external page. Provisions an embed key and returns embed_id / embed_signing_key.

Example:

false

Response

Persona created.

Id of the created persona. Includes embed_id/embed_signing_key when is_embedded=true.

interview_def_set_id
string
required

Id of the newly created persona definition set.

Example:

"00000000-0000-0000-0000-000000000000"

embed_id
string

Embed id, present only when is_embedded=true.

embed_signing_key
string

Embed signing key, present only when is_embedded=true.