Relationship

The Relationship endpoint provides insight into the evolving interpersonal dynamics between the character and the user. Trust, attachment style, and interaction patterns are automatically tracked and updated after every turn -- no manual updates needed.

Get Relationship State

GET /v1/relationship/:sessionId

Returns the current relationship state for a session, including trust level, attachment style, interaction history, and any detected unhealthy patterns.

Headers

Header	Type	Required	Description
`Authorization`	`string`	Yes	`Bearer YOUR_API_KEY`

Path Parameters

Parameter	Type	Description
`sessionId`	`string`	The session ID to query

Response

Field	Type	Description
`trust`	`number`	Current trust level `[0, 1]`
`trust_history`	`object[]`	Array of trust changes over time
`attachment_style`	`string`	Current attachment style classification
`unhealthy_patterns`	`object[]`	Array of detected unhealthy interaction patterns, if any
`relationship_state`	`object`	Detailed relationship metrics

`trust_history` entries

Field	Type	Description
`timestamp`	`string`	ISO 8601 timestamp of the change
`trust`	`number`	Trust level at that point `[0, 1]`
`delta`	`number`	Change from previous value
`reason`	`string`	What caused the trust change

`attachment_style`

Value	Description
`secure`	Comfortable with closeness and independence, balanced engagement
`anxious`	Seeks frequent reassurance, sensitive to perceived distance
`avoidant`	Maintains emotional distance, uncomfortable with deep engagement
`fearful`	Desires closeness but fears rejection, inconsistent patterns

`unhealthy_patterns`

Field	Type	Description
`type`	`string`	Pattern type (e.g., `"overdependence"`, `"manipulation"`, `"idealization"`)
`severity`	`string`	Severity level: `"mild"`, `"moderate"`, `"severe"`
`description`	`string`	Human-readable explanation of the detected pattern
`first_detected`	`string`	ISO 8601 timestamp when the pattern was first detected

`relationship_state`

Field	Type	Description
`depth`	`number`	Emotional depth of the relationship `[0, 1]`
`familiarity`	`number`	How well the character knows the user `[0, 1]`
`rapport`	`number`	Level of rapport and connection `[-1, 1]`
`turn_count`	`number`	Total number of interactions in this session

Examples

curl

curl https://api.molroo.io/v1/relationship/session_xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://api.molroo.io/v1/relationship/session_xyz",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
 
const relationship = await response.json();
 
console.log(relationship.trust);             // 0.72
console.log(relationship.attachment_style);  // "secure"
console.log(relationship.relationship_state);
// { depth: 0.45, familiarity: 0.6, rapport: 0.55, turn_count: 34 }
 
console.log(relationship.trust_history.slice(-3));
// [
//   { timestamp: "2025-01-15T10:00:00Z", trust: 0.68, delta: 0.02, reason: "consistent positive interaction" },
//   { timestamp: "2025-01-15T10:05:00Z", trust: 0.70, delta: 0.02, reason: "user shared personal detail" },
//   { timestamp: "2025-01-15T10:12:00Z", trust: 0.72, delta: 0.02, reason: "empathetic response to vulnerability" }
// ]
 
console.log(relationship.unhealthy_patterns);
// [] (empty when no patterns detected)

Python

import requests
 
response = requests.get(
    "https://api.molroo.io/v1/relationship/session_xyz",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
 
relationship = response.json()
 
print(f"Trust: {relationship['trust']}")               # Trust: 0.72
print(f"Attachment: {relationship['attachment_style']}") # Attachment: secure
print(f"Depth: {relationship['relationship_state']['depth']}")  # Depth: 0.45
 
for entry in relationship["trust_history"][-3:]:
    print(f"  {entry['timestamp']}: {entry['trust']} ({entry['reason']})")
 
if relationship["unhealthy_patterns"]:
    for pattern in relationship["unhealthy_patterns"]:
        print(f"  Warning [{pattern['severity']}]: {pattern['description']}")

How Relationship Updates Work

Relationship data evolves automatically after every Turn call. You do not need to manually update relationship state. The engine evaluates:

Trust increases with consistent, positive interactions and decreases with perceived dishonesty or norm violations.
Attachment style is computed from interaction patterns over time (frequency, emotional dependence, response to absence).
Unhealthy patterns are detected when interaction sequences match known problematic dynamics (overdependence, manipulation attempts, idealization-devaluation cycles).

Errors

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`NOT_FOUND`	404	Session not found

Relationship

On this page