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"
}'

{
  "schema_version": "v0",
  "data": {
    "stored_event_ids": [
      "00000000-0000-0000-0000-000000000001"
    ],
    "count": 1,
    "write_semantics": {
      "scope": "session",
      "ttl_seconds": 3600,
      "overwrites_canon": false,
      "overwrites_persona": false,
      "overwrites_relational_scores": false,
      "planning_guarded": true
    }
  },
  "next_actions": [
    {
      "command": "POST /v1/sessions/00000000-0000-0000-0000-000000000000/messages {\"text\": \"...\"}",
      "description": "Send the next user message; active relationship context can shape it"
    }
  ]
}

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.

Allowed values:

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