API ReferenceCharacters

Create a character

Create (or re-publish) a character owned by the caller’s app.

JSON-native authoring → the Gate-0 characters/character_versions entity. Idempotent on content: re-sending identical content reuses the version. A slug already owned by a DIFFERENT app is rejected 409.

Authentication

AuthorizationBearer

LoreOS API key, sent as Authorization: Bearer <key>.

Request

This endpoint expects an object.
slugstringRequired1-128 characters
display_namestringRequired1-120 characters
localestringOptional2-16 charactersDefaults to ko-KR
default_localestring or nullOptional2-16 characters

Default authored localization. When localizations is provided, the top-level display_name/profile/greeting/voice/example fields are the backward-compatible view of this locale.

primary_reply_languageenumOptionalDefaults to en-US

Creation-time source of truth for visible character speech. Choose the language users should normally see in character replies, not the character’s region or the latest user’s message language. Use voice_samples, example_dialogues, and greeting text in this language unless stable code-switching is intentionally authored. Supported: en-US (English, default), ko-KR (Korean), ja-JP (Japanese), zh-CN (Simplified Chinese), zh-TW (Traditional Chinese). locale remains regional/provider metadata and does not control speech.

supported_input_languageslist of strings or nullOptional

Optional runtime guard for end-user input locales. When omitted, LoreOS accepts sessions in the character’s primary_reply_language only. Use this when a character is intentionally multilingual; otherwise a KO-only character will reject an EN/JA session instead of serving the wrong locale by accident.

input_language_policyenumOptionalDefaults to enforce_supported_input

enforce_supported_input rejects /v1/sessions when request.locale is not in supported_input_languages. allow_cross_language records the metadata but lets the customer app own catalog routing.

profileobjectOptional

Visible profile facts and style anchors.

extra="allow" preserves forward compatibility, but readiness warns on unknown keys so typos do not silently become invisible runtime state.

voice_sampleslist of objectsOptional
example_dialogueslist of objectsOptional
localizationsmap from strings to objects or nullOptional

Per-locale authored runtime packs keyed by BCP-47 locale. Each session selects exactly one localization; voice_samples, example_dialogues, greeting, and localized profile from other locales are not injected into that session’s context window.

greetingobject or nullOptional

Authored first character message emitted as-is on session start.

onboardinglist of objectsOptional
character_directionobject or nullOptional
life_templateobject or nullOptional
story_engineobject or nullOptional
arc_seedslist of objectsOptional
relationship_seedobject or nullOptional
emotion_baselineobject or nullOptional
forbidden_stylelist of maps from strings to anyOptional
handoff_triggerslist of maps from strings to anyOptional
world_model_seedlist of objectsOptional
inherits_style_anchorslist of stringsOptional
shared_style_anchorslist of maps from strings to anyOptional

Resolved negative style examples used by runtime quality prompts. For migrated internal fixtures, send this alongside inherits_style_anchors so DB-backed character content stays self-contained.

raw_sourceslist of objectsOptional
behavioral_thresholdsobject or nullOptional
affordance_schemastring or map from strings to any or nullOptional

Response

Successful Response

Errors

422
Unprocessable Entity Error