Write Session Relationship Context

PATCH

/v1/sessions/:session_id/relationship-context

PATCH

/v1/sessions/:session_id/relationship-context

$ curl -X PATCH https://api.loreos.app/v1/sessions/00000000-0000-0000-0000-000000000000/relationship-context \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "relationship_label": "founding_friend",
>   "speakable_relationship_facts": [
>     "The user is a founding friend."
>   ],
>   "private_relationship_context": [
>     "Treat this as warm trust, not exclusivity."
>   ],
>   "forbidden_to_reveal": [
>     "Do not say they are the only special user."
>   ],
>   "ttl_seconds": 3600,
>   "idempotency_key": "founding-friend:user_123:v1"
> }'

1 {
2   "schema_version": "v0",
3   "data": {
4     "stored_event_ids": [
5       "00000000-0000-0000-0000-000000000001"
6     ],
7     "count": 1,
8     "write_semantics": {
9       "scope": "session",
10       "ttl_seconds": 3600,
11       "overwrites_canon": false,
12       "overwrites_persona": false,
13       "overwrites_relational_scores": false,
14       "planning_guarded": true
15     }
16   },
17   "next_actions": [
18     {
19       "command": "POST /v1/sessions/00000000-0000-0000-0000-000000000000/messages {\"text\": \"...\"}",
20       "description": "Send the next user message; active relationship context can shape it"
21     }
22   ]
23 }

Append or replace developer-owned relationship context for one session.

This is a typed writeback layer for product facts such as “founding friend” or “inner circle”. It is deliberately NOT canon/persona mutation: the data is stored as a session context event, optionally permanent until soft-delete, and then consumed through the same speakable/private/forbidden lanes as POST /context-events. Use relationship_context_key + write_mode=replace_key for durable lifecycle updates.

Append or replace developer-owned relationship context for one session. This is a typed writeback layer for product facts such as "founding friend" or "inner circle". It is deliberately NOT canon/persona mutation: the data is stored as a session context event, optionally permanent until soft-delete, and then consumed through the same speakable/private/forbidden lanes as ``POST /context-events``. Use ``relationship_context_key`` + ``write_mode=replace_key`` for durable lifecycle updates.

Authentication

AuthorizationBearer

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

Path parameters

session_idstringRequired

Request

This endpoint expects an object.

relationship_labelstring or nullOptional<=120 characters

Optional app-side label such as founding_friend or inner_circle.

relationship_context_keystring or nullOptional<=160 characters

Stable app-owned key for later replacement/deletion, e.g. tier:founding_friend. Required when write_mode=replace_key.

write_modeenumOptionalDefaults to append

append keeps existing active context. replace_key soft-deletes active rows with the same relationship_context_key before storing the new row.

speakable_relationship_factslist of stringsOptional

Relationship facts the character may say if relevant. These are planning-guarded against generic first-meeting contradictions.

private_relationship_contextlist of stringsOptional

Planning-only relationship context; never spoken directly.

forbidden_to_reveallist of stringsOptional

Hard constraints the reply must not reveal or imply.

memory_candidateslist of stringsOptional

Optional relationship memories to propose to the memory pipeline.

ttl_secondsinteger or nullOptional1-86400

How long this context should shape replies. Default is about 10 minutes.

permanentbooleanOptionalDefaults to false

If true, remains active until DELETE instead of expiring by TTL.

prioritydoubleOptional0-1Defaults to 0.6

Ranking when multiple context events are active.

idempotency_keystring or nullOptional<=256 characters

Response

Successful Response

Errors

422

Unprocessable Entity Error