Start a session

POST

/v1/sessions

POST

/v1/sessions

$ curl -X POST https://api.loreos.app/v1/sessions \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "character": "mira-demo",
>   "external_user_ref": "user_123"
> }'

1 {
2   "schema_version": "v0",
3   "data": {
4     "session_id": "00000000-0000-0000-0000-000000000000",
5     "character": "mira-demo",
6     "characters": [
7       {
8         "character": "mira-demo",
9         "actor_id": "11111111-1111-1111-1111-111111111111",
10         "primary": true
11       }
12     ],
13     "canonical_character": "mira-demo",
14     "external_user_ref": "user_123",
15     "initial_event_cursor": 1,
16     "language_guard": {
17       "effective_reply_language": "en-US",
18       "supported_input_languages": [
19         "en-US"
20       ]
21     },
22     "actor_scope": {
23       "interaction_id": "22222222-2222-2222-2222-222222222222",
24       "external_user_actor_id": "33333333-3333-3333-3333-333333333333",
25       "participant_actor_ids": [
26         "11111111-1111-1111-1111-111111111111",
27         "33333333-3333-3333-3333-333333333333"
28       ],
29       "requires_explicit_message_scope": false
30     }
31   },
32   "next_actions": [
33     {
34       "command": "POST /v1/sessions/00000000-0000-0000-0000-000000000000/messages {\"text\": \"안녕!\"}",
35       "description": "Send the end-user's first message"
36     },
37     {
38       "command": "GET /v1/sessions/00000000-0000-0000-0000-000000000000/events?since=0",
39       "description": "Poll the event log for the character's replies"
40     }
41   ]
42 }

Start a native interaction between app-owned characters and an end-user.

The end-user is BYO auth (an opaque ref the developer controls), never an operator identity. Send one stable Idempotency-Key per intended session so a timeout or retry returns the original session instead of creating a duplicate.

Authentication

AuthorizationBearer

LoreOS runtime API key (ck_...), sent as Authorization: Bearer <key>.

Request

This endpoint expects an object.

characterstringRequired1-128 characters

character slug

external_user_refstringRequired1-200 characters

additional_characterslist of stringsOptionalDefaults to []

Additional app-owned character slugs participating in this interaction.

external_user_display_namestring or nullOptional<=120 characters

localeenumOptional

End-user input locale for this session. LoreOS validates it against the character’s supported_input_languages unless the character was authored with input_language_policy=allow_cross_language.

proactive_enabledboolean or nullOptional

Response

Successful Response

schema_version"v0"

LoreOS success-envelope version.

dataobject

next_actionslist of objects

Concrete follow-up API actions; empty when no action is required.

Errors

422

Unprocessable Entity Error

Authentication

Headers

Request

Response

Errors