RelationshipOS API Documentation

Quick Start

Get your first AI character response in under 2 minutes.

1. Get Your API Key

Register for a free account to get your API key:

curl -X POST https://api.relationshipos.net/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}'

2. Send Your First Message

curl -X POST https://api.relationshipos.net/v1/message \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ros_live_YOUR_KEY" \
  -d '{
    "characterId": "mia_001",
    "userId": "user_123",
    "content": "Hey, how are you?",
    "contentTier": "sfw",
    "character": {
      "name": "Mia",
      "archetype": "playful_tease",
      "relationshipContext": {
        "currentStage": "stranger"
      }
    }
  }'

3. Receive Intelligent Response

{
  "message": {
    "role": "assistant",
    "content": "Hey! Pretty good, just got off work. What about you?"
  },
  "state": {
    "bond": 31.2,
    "trust": 40.5,
    "attraction": 30.0,
    "stage": "stranger"
  },
  "timing": {
    "suggestedDelay": 3500,
    "delayReason": "just got home"
  }
}

Authentication

All API requests (except registration and health) require an API key.

Include your key in the X-API-Key header:

X-API-Key: ros_live_YOUR_API_KEY_HERE

API keys are generated during registration. Save your key immediately — it won't be shown again.

Endpoints

GET /v1/health

Check API status. No authentication required.

Response

{
  "status": "ok",
  "timestamp": "2026-01-20T14:30:00Z",
  "version": "2.0.0"
}

POST /v1/message

Send a message to a character and receive a contextually appropriate response based on relationship state, psychology, and personality.

Request Body

Field	Type	Required	Description
`characterId`	string	Yes	Unique character identifier
`userId`	string	Yes	Unique user identifier
`content`	string	Yes	User's message
`contentTier`	string	No	`sfw` \| `mature` \| `nsfw`
`demoMode`	boolean	No	Skip delays for testing
`character`	object	No	Character configuration (see below)

Character Object

Field	Type	Description
`name`	string	Character's display name
`archetype`	string	Personality type (see Archetypes)
`age`	integer	Character's age (18+)
`relationshipContext.currentStage`	string	Initial relationship stage (see Stages)

Example Request

{
  "characterId": "mia_001",
  "userId": "user_123",
  "content": "I missed you today",
  "contentTier": "sfw",
  "character": {
    "name": "Mia",
    "archetype": "playful_tease",
    "relationshipContext": {
      "currentStage": "dating"
    }
  }
}

Response

{
  "message": {
    "role": "assistant",
    "content": "Aww I missed you too 💕 How was your day?"
  },
  "state": {
    "bond": 55.2,
    "trust": 60.0,
    "attraction": 52.5,
    "stage": "dating",
    "messageCount": 47,
    "hoursKnown": 336,
    "daysKnown": 14
  },
  "timing": {
    "suggestedDelay": 2500,
    "delayReason": "available",
    "availability": "available"
  },
  "meta": {
    "processingTime": 1250,
    "llmProvider": "workers-ai"
  }
}

POST /v1/auth/register

Create a developer account and receive your API key. No authentication required.

Request Body

Field	Type	Required
`email`	string	Yes
`password`	string	Yes (8+ chars)
`company_name`	string	No

Response

{
  "tenant_id": "tenant_abc123",
  "email": "you@example.com",
  "tier": "free",
  "api_key": "ros_live_SAVE_THIS_KEY",
  "message": "Account created. Save your API key - it will not be shown again."
}

Character Archetypes

10 distinct personality types grouped by emotional function. Each archetype evolves its behavior based on relationship stage.

Tier 1: Attraction & Energy

Archetype	Description	Core Traits
`playful_tease`Attraction	Flirty, fun, uses humor and light teasing. Thrives on banter.	Witty, spontaneous, teasing
`seductive_confident`Attraction	Calm sexual confidence. Minimal humor, controlled tension. Never needy.	Confident, sensual, patient
`edgy_bold`Attraction	Direct, assertive, challenges the user. Enforces boundaries sharply.	Assertive, challenging, direct

Tier 2: Emotional Safety

Archetype	Description	Core Traits
`warm_supportive`Safety	Empathetic, validating, emotionally available. Avoids intensity spikes.	Empathetic, patient, stable
`caring_nurturing`Safety	Protective, soft reassurance. Attachment-safe, slower escalation.	Protective, gentle, devoted
`emotionally_attuned`Safety	Reads emotional subtext, responds to mood shifts, mirrors energy subtly.	Perceptive, adaptive, intuitive

Tier 3: Depth & Mystery

Archetype	Description	Core Traits
`mysterious_intriguing`Depth	Withholds information early, slow emotional reveal. Poetic restraint.	Enigmatic, thoughtful, selective
`introspective_poetic`Depth	Reflective, emotionally articulate. Uses metaphor sparingly.	Reflective, deep, romantic
`intellectual_witty`Depth	Sharp wordplay, abstract discussion. Mental connection first.	Clever, analytical, curious

Tier 4: Stability & Realism

Archetype	Description	Core Traits
`grounded_realist`Stability	Honest, practical, no fantasy inflation. Stabilizes emotional extremes.	Honest, practical, reliable

Archetype Evolution

Each archetype changes behavior as the relationship progresses. For example, mysterious_intriguing:

Stage	Behavior
`stranger`	Distant, observant, intriguing hints
`familiar`	Selective openings, careful reveals
`dating`	Selective vulnerability, meaningful shares
`committed`	Full depth revealed, still maintains mystique

Relationship Stages

6 stages of relationship progression. Each stage unlocks different behaviors and has both bond level and time requirements.

Stage	Bond Range	Time Required	Behaviors Unlocked
`stranger`	30-36	0 days	Basic greetings, light curiosity, neutral toneNo pet names, no emotional reliance
`familiar`	37-43	1+ days	Inside references, friendly teasing, light personal questionsRemoves awkward stiffness
`acquaintance`	44-52	3+ days	Personal opinions, mild affection, casual complimentsNo "I miss you" yet
`dating`	53-64	14+ days	Flirting, emotional sharing, making plans, light pet namesNo "I love you" or forever language
`exclusive`	65-74	21+ days	Exclusivity acknowledgment, jealousy boundaries, "I miss you" freelyCommitment signals before "I love you"
`committed`	75+	30+ days	"I love you", long-term planning, deep vulnerability, full intimacySecure attachment

Stage Progression

Relationships progress naturally based on:

Bond level — Increases with positive interactions
Time — Days since first interaction (prevents instant progression)
Message count — Number of exchanges

Content Tiers

Tier	Description
`sfw`	Safe for work, no explicit content
`mature`	Adult themes, suggestive content
`nsfw`	Explicit adult content (uses Ollama 70B)

Error Handling

Code	Status	Description
`MISSING_API_KEY`	401	No X-API-Key header provided
`INVALID_API_KEY`	401	API key not found or invalid
`INVALID_REQUEST`	400	Missing required fields
`NOT_FOUND`	404	Character not found
`RATE_LIMITED`	429	Too many requests