Made in 10Docs
GuidesAPI
ReferenceCharacters

Create a character

Makes a character.

POST
/characters

Authorization

secretKey
headerAuthorizationBearer <sk_live_… or sk_test_… (a prefix and 40 base62 characters)>

A secret key from the dashboard, sent as Authorization: Bearer sk_live_…. Live keys run real, charged calls; test keys (sk_test_…) run calls of at most 60 seconds, 20 a day per organization, never charged. Each key sees only its own env's calls, meetings, webhooks, memories and analytics. Publishable keys (pk_…) are refused.

Request Body

application/json
  1. body

A new character. Only name is required. Defaults: role blank, language auto, no face, the face's voice, tier standard, 300 seconds, recorded, a quiet call checked after 10 seconds and ended 20 seconds later, sees nothing, no notes about people; a role's template fills instructions and greeting you leave out.

Example
{  "name": "Sam",  "role": "sales",  "face_id": "red-office",  "language": "en",  "max_call_seconds": 600}
name*string
Length1 <= length <= 80
role?Role

What the character is for. A new character with a role and no words of its own starts from that role's template. interviewer takes no success criteria (see updateAnalysisSettings). On a character that uses one of your organization's custom roles (custom_role), this is set for you and can't be changed: interviewer when the custom role is protected, blank when it isn't.

Value in"blank""support""sales""interviewer""receptionist"
custom_role_id?|

One of your organization's custom roles (GET /roles), or null for none. With one, role in the same request is ignored and set from the custom role (interviewer when it is protected, else blank), and a new character with no instructions or greeting of its own starts from the role's. Null takes the role off and leaves role as it is, unless you send role too. An id that isn't one of your organization's roles is 422 role_not_found.

instructions?string
Lengthlength <= 20000
greeting?string
Lengthlength <= 500
knowledge?string
Lengthlength <= 120000
language?Language

The language the character speaks. auto answers in whatever language the person speaks.

Value in"auto""en""fa""ar""tr""de""fr""es""it""pt""nl""ru""zh""ja""ko""hi"
face_id?|

One of our faces' ids; null or "" for voice only.

voice_id?|

A voice id (letters, digits, - and _, at most 64); null or "" for the face's own voice.

tier?string

One of the catalog's tiers.

max_call_seconds?integer
Range30 <= value <= 1800
record?boolean

Record its calls' voices (see Recordings).

silence_check_seconds?integer

0 (never ask) or 5 to 120 seconds of quiet before it asks if they're still there.

Range0 <= value <= 120
silence_end_seconds?integer

Seconds after asking before it says goodbye and ends the call.

Range5 <= value <= 120
sees?Sees

What the character sees on a call: nothing (the default), a screen the person shares, their camera, or both. It describes what it sees and never infers feelings, intentions, age, ethnicity, religion or health; a face is never matched to a person.

Value in"off""screen""camera""both"
people_notes?boolean

Plain notes about a person it sees (false by default). true on an interviewer, or with role: interviewer in the same request, is 422 people_notes_not_allowed; making a character an interviewer turns it off.

Response Body

The new character.

application/json
  1. response

A customer's AI person.

Example
{  "id": "chr_4fT9kQ2mXw7LbN3pZs8V",  "name": "Alex",  "role": "support",  "instructions": "You help customers with questions about our product. Answer only from what you know below.",  "greeting": "Hi, I'm Alex, an AI assistant for the support team. What can I help you with?",  "knowledge": "We open at nine and close at five, Monday to Friday.",  "language": "auto",  "face_id": "red-office",  "voice_id": null,  "tier": "standard",  "max_call_seconds": 300,  "created_unix": 1793300000,  "updated_unix": 1793300000,  "document_ids": [    "doc_1Qm6Tx3KcW8vRp5ZbN2h"  ],  "guardrail_ids": [    "grd_8Vb3Np6XqL1sKw9TfM4c"  ],  "pronunciation_ids": [],  "tool_ids": [    "tool_6Mx1Rb8QwT3kNv5LcZ9p"  ],  "record": true,  "silence_check_seconds": 10,  "silence_end_seconds": 20,  "sees": "off",  "people_notes": false,  "people_notes_allowed": true,  "version": 7,  "draft_pending": false,  "custom_role": null}
id*CharacterId

A character's id.

Match^chr_[0-9A-Za-z]{20}$
Example"chr_4fT9kQ2mXw7LbN3pZs8V"
name*string
Length1 <= length <= 80
role*Role

What the character is for. A new character with a role and no words of its own starts from that role's template. interviewer takes no success criteria (see updateAnalysisSettings). On a character that uses one of your organization's custom roles (custom_role), this is set for you and can't be changed: interviewer when the custom role is protected, blank when it isn't.

Value in"blank""support""sales""interviewer""receptionist"
custom_role*|

The custom role of your organization it uses (GET /roles), or null. Set it with custom_role_id.

instructions*string

Your instructions for the mind, in your words.

Lengthlength <= 20000
greeting*string

The line it opens the call with.

Lengthlength <= 500
knowledge*string

What it knows, straight into the prompt (with its documents, at most 120,000 characters).

Lengthlength <= 120000
language*Language

The language the character speaks. auto answers in whatever language the person speaks.

Value in"auto""en""fa""ar""tr""de""fr""es""it""pt""nl""ru""zh""ja""ko""hi"
face_id*|

One of our faces (GET /catalog), or null for voice only.

voice_id*|

A voice id from the catalog, or null for the face's own voice.

tier*string

The tier it runs on (GET /catalog lists the tiers on offer and their prices).

max_call_seconds*integer

The longest a call with it may run.

Range30 <= value <= 1800
created_unix*Unix

Unix seconds, UTC.

Formatint64
Example1793300000
updated_unix*Unix

Unix seconds, UTC.

Formatint64
Example1793300000
document_ids*array<>

The documents it takes, in order.

guardrail_ids*array<>

The guardrail sets it takes, in order.

pronunciation_ids*array<>

The pronunciation dictionaries it takes, in order.

tool_ids*array<>

The tools it may call, in order.

record*boolean

Whether its calls are recorded (see Recordings). True unless you switch it off.

silence_check_seconds*integer

On a quiet call: after this many seconds with nobody speaking it asks once if they're still there. 0 for never; otherwise 5 to 120. Meetings don't use it.

Example10
silence_end_seconds*integer

This many seconds after asking, with still nobody speaking, it says goodbye and ends the call (its end_reason is silence).

Range5 <= value <= 120
Example20
sees*Sees

What the character sees on a call: nothing (the default), a screen the person shares, their camera, or both. It describes what it sees and never infers feelings, intentions, age, ethnicity, religion or health; a face is never matched to a person.

Value in"off""screen""camera""both"
people_notes*boolean

Whether what it sees may include plain notes about a person (what they wear or hold, a smile as seen), never anything inferred. False by default; never true for an interviewer.

people_notes_allowed*boolean

Whether its role allows people_notes at all: false for an interviewer, whose calls describe the screen and objects only (EU AI Act Art. 5(1)(f); candidates count as a workplace).

version*integer

The published version these fields are (GET /characters/{character_id}/versions).

Range1 <= value
Example7
draft_pending*boolean

Changes made in the dashboard wait in a draft for Update; a PATCH is then 409 draft_pending unless ?force=true. This api always answers the published character, never the draft.

Example Request
curl -X POST 'https://api.daxov.com/v1/characters' \  -H 'Content-Type: application/json' \  -d '{  "name": "Sam",  "role": "sales",  "face_id": "red-office",  "language": "en",  "max_call_seconds": 600}'
Example Response
{  "id": "chr_4fT9kQ2mXw7LbN3pZs8V",  "name": "Alex",  "role": "support",  "instructions": "You help customers with questions about our product. Answer only from what you know below.",  "greeting": "Hi, I'm Alex, an AI assistant for the support team. What can I help you with?",  "knowledge": "We open at nine and close at five, Monday to Friday.",  "language": "auto",  "face_id": "red-office",  "voice_id": null,  "tier": "standard",  "max_call_seconds": 300,  "created_unix": 1793300000,  "updated_unix": 1793300000,  "document_ids": [    "doc_1Qm6Tx3KcW8vRp5ZbN2h"  ],  "guardrail_ids": [    "grd_8Vb3Np6XqL1sKw9TfM4c"  ],  "pronunciation_ids": [],  "tool_ids": [    "tool_6Mx1Rb8QwT3kNv5LcZ9p"  ],  "record": true,  "silence_check_seconds": 10,  "silence_end_seconds": 20,  "sees": "off",  "people_notes": false,  "people_notes_allowed": true,  "version": 7,  "draft_pending": false,  "custom_role": null}