--- title: "Create a persona" description: "Create a custom persona for the authenticated user." --- > Documentation Index > Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt > Use this file to discover all available pages before exploring further. Path: AI Gateway API › Personas `POST /personas` Create a custom persona for the authenticated user. ## Authentication - `HTTPBearer`, http, header `Authorization` ## Header parameters - `X-On-Behalf-Of` (`create_persona.header.X-On-Behalf-Of`; any of, optional) - any of: `string`, `null` - `X-External-User-Id` (`create_persona.header.X-External-User-Id`; any of, optional) - any of: `string`, `null` - `X-App-Id` (`create_persona.header.X-App-Id`; any of, optional) - any of: `string`, `null` ## Request body _Required._ - `name` (`create_persona.name`; string, required) — Display name for the persona. - minLength 1; maxLength 255 - `system_prompt` (`create_persona.system_prompt`; string, required) — System prompt injected at the start of every conversation when this persona is active. - minLength 1 - `description` (`create_persona.description`; any of, optional) — Short human-readable description of the persona's purpose. - any of: `string`, `null` - `visibility` (`create_persona.visibility`; string, optional) — private = creator only; public = available to users in every app. - one of `"private"`, `"public"`; default `"private"` - `archetype` (`create_persona.archetype`; any of, optional) — App-defined archetype identifier (e.g. SAGE, EXPLORER). Shared across apps. - any of: `string`, `null` - `soul_document` (`create_persona.soul_document`; any of, optional) — Structured personality document (JSON). Keys: voiceAndStyle, antiPatterns, learnedAdaptations, boundaries, customInstructions. - any of: `object`, `null` - `human_profile` (`create_persona.human_profile`; any of, optional) — Creator-specific profile data. Never shared with public persona consumers. - any of: `string`, `null` - `avatar` (`create_persona.avatar`; any of, optional) — URL of the persona's avatar image. - any of: `string`, `null` - `avatar_config` (`create_persona.avatar_config`; any of, optional) — App-defined dynamic avatar settings (a JSON object, 64 KB max). Truememory stores and returns it unchanged and never puts it in a prompt. - any of: `object`, `null` ## Example request ```json { "name": "Friendly Coach", "description": "A warm, encouraging coaching persona", "system_prompt": "You are a friendly life coach. Respond with empathy and encouragement.", "visibility": "private", "archetype": "string", "soul_document": {}, "human_profile": "string", "avatar": "string", "avatar_config": {} } ``` ## Code samples ### cURL ```bash curl --request POST \ --url https://truememory-api.mvstg.com/personas \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "name": "Friendly Coach", "description": "A warm, encouraging coaching persona", "system_prompt": "You are a friendly life coach. Respond with empathy and encouragement.", "visibility": "private", "archetype": "string", "soul_document": {}, "human_profile": "string", "avatar": "string", "avatar_config": {} } ' ``` ### TypeScript ```typescript const url = 'https://truememory-api.mvstg.com/personas'; const options = { method: 'POST', headers: {'Content-Type': 'application/json', Authorization: 'Bearer '}, body: JSON.stringify({ name: 'Friendly Coach', description: 'A warm, encouraging coaching persona', system_prompt: 'You are a friendly life coach. Respond with empathy and encouragement.', visibility: 'private', archetype: 'string', soul_document: {}, human_profile: 'string', avatar: 'string', avatar_config: {} }) }; fetch(url, options) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err)); ``` ### Python ```python import requests url = "https://truememory-api.mvstg.com/personas" payload = { "name": "Friendly Coach", "description": "A warm, encouraging coaching persona", "system_prompt": "You are a friendly life coach. Respond with empathy and encouragement.", "visibility": "private", "archetype": "string", "soul_document": {}, "human_profile": "string", "avatar": "string", "avatar_config": {} } headers = { "Content-Type": "application/json", "Authorization": "Bearer " } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## Responses ### 201 Successful Response #### Example ```json { "id": "string", "user_id": "string", "name": "string", "description": "string", "system_prompt": "string", "is_preset": true, "visibility": "private", "is_active": false, "archetype": "string", "soul_document": {}, "human_profile": "string", "avatar": "string", "avatar_config": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` - `id` (`create_persona.response.201.id`; string, required) - `user_id` (`create_persona.response.201.user_id`; any of, required) — Owner user_id, NULL for presets. - any of: `string`, `null` - `name` (`create_persona.response.201.name`; string, required) - `description` (`create_persona.response.201.description`; any of, required) - any of: `string`, `null` - `system_prompt` (`create_persona.response.201.system_prompt`; string, required) - `is_preset` (`create_persona.response.201.is_preset`; boolean, required) - `created_at` (`create_persona.response.201.created_at`; string, required) - format `date-time` - `updated_at` (`create_persona.response.201.updated_at`; string, required) - format `date-time` - `visibility` (`create_persona.response.201.visibility`; string, optional) - one of `"private"`, `"public"`; default `"private"` - `is_active` (`create_persona.response.201.is_active`; boolean, optional) - default `false` - `archetype` (`create_persona.response.201.archetype`; any of, optional) — App-defined archetype identifier (e.g. SAGE, EXPLORER). Each app renders its own visual for this. - any of: `string`, `null` - `soul_document` (`create_persona.response.201.soul_document`; any of, optional) — Structured personality document: voice style, anti-patterns, learned adaptations, boundaries, custom instructions. - any of: `object`, `null` - `human_profile` (`create_persona.response.201.human_profile`; any of, optional) — Creator-specific profile data. Hidden from other users when the persona is public. - any of: `string`, `null` - `avatar` (`create_persona.response.201.avatar`; any of, optional) — URL of the persona's avatar image. - any of: `string`, `null` - `avatar_config` (`create_persona.response.201.avatar_config`; any of, optional) — App-defined dynamic avatar settings (a JSON object, 64 KB max). Truememory stores and returns it unchanged and never puts it in a prompt. - any of: `object`, `null` ### 422 Validation Error #### Example ```json { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string", "input": null, "ctx": {} } ] } ``` - `detail` (`create_persona.response.422.detail`; array, optional) - `loc` (`create_persona.response.422.detail.loc`; array, required) - any of: `string`, `integer` - `msg` (`create_persona.response.422.detail.msg`; string, required) - `type` (`create_persona.response.422.detail.type`; string, required) - `input` (`create_persona.response.422.detail.input`; unknown, optional) - `ctx` (`create_persona.response.422.detail.ctx`; object, optional) Source: https://truememory-docs.mvstg.com/api/personas/create/index.md