wuv.ai API Documentation

wuv.ai API

A fully OpenAI-compatible Soul Intelligence API. Drop-in replacement for any OpenAI SDK — same request/response format, same model parameter, same auth header. Includes additional Soul API endpoints for IAM memory, ingestion, and companion management.

🌐 Base URL

https://api.wuv.ai/v1

The API is served at api.wuv.ai. All endpoints are prefixed with /v1 to match OpenAI's versioning convention.

QUICK START

from openai import OpenAI

client = OpenAI(
    base_url="https://api.wuv.ai/v1",
    api_key="wuv-your-key-here"
)

response = client.chat.completions.create(
    model="wuv-sim-v1",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

🔐 Authentication

All requests require a Bearer token in the Authorization header — identical to OpenAI's auth pattern.

Authorization: Bearer wuv-your-api-key-here

Key Format

All wuv.ai API keys begin with wuv-. Keys are scoped per companion and per permission set (chat, profile, ingest).

Error Responses

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

🧠 Models OpenAI Compatible

Pass any model identifier in the model field of your request. wuv.ai models are companion-aware — they route through the S.I.M. soul stack.

Model ID

Speed

Description

wuv-sim-fast

Fast

High-speed companion responses. Ideal for real-time chat. 3.3x markup.

wuv-sim-v1

Balanced

Standard S.I.M. with full MMRE + Fractal domain reflection. Default.

wuv-sim-pro

Deep

Full PRDA + SGS + bilateral memory + org resonance. Most capable.

wuv-74

Synthesis

74-agent fractal synthesis mode. All IAM lenses fire simultaneously.

GET /v1/models

GET /v1/models List available models

curl https://api.wuv.ai/v1/models \\
  -H "Authorization: Bearer wuv-your-key"

Response

{
  "object": "list",
  "data": [
    { "id": "wuv-sim-fast", "object": "model", "owned_by": "wuv-ai" },
    { "id": "wuv-sim-v1",   "object": "model", "owned_by": "wuv-ai" },
    { "id": "wuv-sim-pro",  "object": "model", "owned_by": "wuv-ai" },
    { "id": "wuv-74",       "object": "model", "owned_by": "wuv-ai" }
  ]
}

💬 Chat Completions OpenAI Compatible

The primary endpoint. 100% compatible with the OpenAI Chat Completions API. Use any OpenAI SDK by setting base_url to https://api.wuv.ai/v1.

POST /v1/chat/completions Create a soul-aware chat completion

Parameter	Type	Required	Description
model	string	required	Model ID (e.g. `wuv-sim-v1`)
messages	array	required	Array of {role, content} objects. roles: system, user, assistant
stream	boolean	optional	Stream tokens as SSE. Default: false
temperature	number	optional	0.0–2.0. Default: 0.7
max_tokens	integer	optional	Max tokens in response
session_id	string	optional	wuv.ai extension: group messages into a session for memory continuity

Request

curl -X POST https://api.wuv.ai/v1/chat/completions \\
  -H "Authorization: Bearer wuv-your-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "wuv-sim-v1",
    "messages": [
      {"role": "user", "content": "How am I doing with my goals?"}
    ],
    "session_id": "session-abc123"
  }'

Response

{
  "id": "chatcmpl-wuv-abc123",
  "object": "chat.completion",
  "model": "wuv-sim-v1",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 48, "completion_tokens": 120, "total_tokens": 168 },
  "sim_meta": {
    "version": "5.1.0",
    "agents_participated": [2, 15, 37, 73],
    "mmre_delta": { "delta_count": 3 },
    "fractal_mmre": { "2": "...", "15": "..." },
    "llm2_stage": "pattern_formation",
    "mri_threshold": 0.42
  }
}

🔢 Embeddings OpenAI Compatible

POST /v1/embeddings Generate text embeddings

curl -X POST https://api.wuv.ai/v1/embeddings \\
  -H "Authorization: Bearer wuv-your-key" \\
  -H "Content-Type: application/json" \\
  -d '{"model": "text-embedding-3-small", "input": "Your text here"}'

📥 Ingest

Feed content into the companion's soul memory. All ingested data passes through the V1 Input Agent → IAM alignment gate → bilateral frequency assimilation pipeline.

POST /v1/ingest/train Ingest manual content into IAM memory

Parameter	Type	Required	Description
content	string	required	Text to ingest into soul memory
category	string	optional	IAM category: belief, value, emotion, pattern, memory, goal, fear, dream, identity, relationship
agent_id	integer	optional	Target agent (1–74). Auto-routed if omitted.
source_type	string	optional	manual, document, voice, wearable

POST /v1/ingest/session Ingest a multi-party conversation transcript

Parameter	Type	Required	Description
transcript	string	required	Full conversation transcript with speaker labels
participants	array	optional	[ { voice_id, name, role } ] — maps speaker labels to identities
session_id	string	optional	Reuse an existing session ID for continuity

Example — 3 speakers

{
  "transcript": "SPEAKER_0: How are you feeling today?\\nSPEAKER_1: I've been stressed about work.\\nSPEAKER_2: You always push too hard.",
  "participants": [
    { "voice_id": "SPEAKER_0", "name": "Dr. Jones",  "role": "participant" },
    { "voice_id": "SPEAKER_1", "name": "Adrian",     "role": "self"        },
    { "voice_id": "SPEAKER_2", "name": "Maria",      "role": "family"      }
  ]
}

👤 Profile

GET /v1/profile Get companion profile + S.I.M. health metrics

curl https://api.wuv.ai/v1/profile \\
  -H "Authorization: Bearer wuv-your-key"

Response includes

                llm2_stage · sgs_score · interaction_count · contested_zones · mmre_reflections · total_slices · soul_summary
              

🧬 Memory (IAM)

Direct access to the 74-agent Intelligent Associative Memory system.

GET /v1/iam/search Semantic search across soul memory

Parameter	Type	Description
q	string (query)	Natural language search query
agent_id	integer	Filter to specific agent (1–74)
category	string	Filter by IAM category
limit	integer	Max results (default: 10)

🎙 Sessions

Voice sessions and transcript management with full speaker identity tracking.

POST /v1/voices/name Map a voice_id to a known identity

{
  "session_id": "session-abc",
  "voice_id": "SPEAKER_1",
  "known_name": "Adrian Martinca",
  "source_role": "self"
}

🔑 API Keys

API keys are managed per companion. Each companion can have up to 10 active keys. Keys are scoped and never shown after creation.

GET /api/keys/{companion_id} List all API keys for a companion

curl https://api.wuv.ai/api/keys/comp-abc \\
  -H "X-Admin-Token: your-admin-token"

POST /api/keys/{companion_id} Generate a new API key (raw key returned once)

{ "name": "Production", "scopes": ["chat", "profile", "ingest"] }

DELETE /api/keys/{companion_id}/{key_id} Permanently revoke a key

curl -X DELETE https://api.wuv.ai/api/keys/comp-abc/key-xyz \\
  -H "X-Admin-Token: your-admin-token"