Send a message

POST

/v1/sessions/:session_id/messages

Deliver an end-user message; the character’s reply arrives async on the event log. Returns immediately with the user-message cursor — poll GET .../events?since=<cursor> for the reply (delayed-exposure UX).

Send Idempotency-Key: <unique-per-message> to make retries safe (common on serverless/Vercel): a same-key re-call returns the original cursor + turn index (idempotent_replay: true) instead of creating a duplicate turn/reply.

Deliver an end-user message; the character's reply arrives async on the event log. Returns immediately with the user-message cursor — poll ``GET .../events?since=<cursor>`` for the reply (delayed-exposure UX). Send ``Idempotency-Key: <unique-per-message>`` to make retries safe (common on serverless/Vercel): a same-key re-call returns the original cursor + turn index (``idempotent_replay: true``) instead of creating a duplicate turn/reply.

Authentication

AuthorizationBearer

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

Path parameters

session_idstringRequired

Request

This endpoint expects an object.

textstringRequired1-4000 characters

reply_modeenum or nullOptional

context_eventslist of objects or nullOptional

active_addressee_actor_idslist of strings or nullOptional

audience_actor_idslist of strings 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

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

$	curl -X POST https://api.loreos.app/v1/sessions/00000000-0000-0000-0000-000000000000/messages \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"text": "Give me one short line proving this chat works."
>	}'

1	{
2	"schema_version": "v0",
3	"data": {
4	"accepted": true,
5	"cursor": 2,
6	"sent_turn_index": 1,
7	"run_ref": "trace_0000000000000000",
8	"reply_mode": "fast"
9	},
10	"next_actions": [
11	{
12	"command": "GET /v1/sessions/00000000-0000-0000-0000-000000000000/events?since=2",
13	"description": "Poll for the character's reply"
14	}
15	]
16	}

Authentication

Path parameters

Headers

Request

Response

Errors