API ReferenceImports

Create a character import

Stage a character bundle import.

Fresh-start apps use mode=authoring_only with just character. Migration apps use mode=hybrid or transcript_migration with the same authored bundle plus a canonical transcript; LoreOS stages the transcript into a sandbox session, then extracts relationship memory in the background.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
characterobjectRequired
The authored character bundle to publish on commit.
modeenumOptionalDefaults to authoring_only

Use authoring_only for fresh characters with no prior chat history. Use hybrid for an authored bundle plus an imported transcript. transcript_migration is accepted for migration-only clients.

transcriptobject or nullOptional

Canonical prior conversation export. Required for hybrid and transcript_migration. The raw transcript is replayed into a sandbox staging session and is not stored in the import row.

external_user_refstring or nullOptional1-200 characters

Your stable end-user id. Required for transcript imports so committed relationship memory attaches to the correct user.

external_user_display_namestring or nullOptional<=120 characters
Optional display name for the imported relationship's human side.
identity_imageobject or nullOptional
Optional public URL for the character's primary identity image.
extraction_modeenumOptionalDefaults to background

background starts a Temporal CharacterImportExtractionWorkflow and returns temporal_workflow_id for polling. none stages the transcript without extractor work for tests or custom review flows.

Response

Successful Response

Errors

422
Unprocessable Entity Error