Serena API Documentation

Serena is a white-box emotional analysis API that converts raw text into deterministic emotional state representations. It is designed to act as an affective sensor beneath agents, products, simulations, and analytical systems that require transparency, repeatability, and auditability.

Why Serena

Most sentiment APIs provide opaque labels without exposing emotional structure. Serena treats affect as first-class computation: symbolic, deterministic, and explainable. Every output can be inspected, logged, and reasoned about.

Guarantees & Non-Goals

• Identical input always produces identical output
• No sampling, randomness, or probabilistic variation
• No training on user data
• No text storage or conversation memory
• Serena does not generate text or make decisions

Quickstart

import requests

SERENA_URL = "https://www.serenachat.com/api/serena"
API_KEY = "sk_live_your_key_here"

def ask_serena(text: str) -> dict:
    r = requests.post(
        SERENA_URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={"text": text},
        timeout=10
    )
    r.raise_for_status()
    return r.json()

result = ask_serena("Hello Serena")

emotions = result["emotions"]
print("Primary:", emotions["primary"]["label"])
print("Secondary:", emotions["secondary"]["label"])
print("Tertiary:", emotions["tertiary"]["label"])

Authentication

All requests require an API key passed via the Authorization header:

Authorization: Bearer sk_live_...

API keys are scoped per user, usage-tracked per key, and enforced with hard monthly limits.

Usage Limits

Usage is measured in sentences analysed per month. Each response includes live quota metadata.

{
  "api_usage": {
    "remaining": 1987,
    "limit": 2000
  }
}

POST /api/serena

Core emotional analysis endpoint. Accepts raw text and returns structured emotional state.

Response Format

{
  "emotion_vector": [0.42, -0.11, 0.08, 0.91, 0.34, 0.67, 0.12],

  "emotions": {
    "primary": {
      "label": "Calm",
      "distance": 0.083
    },
    "secondary": {
      "label": "Reflective",
      "distance": 0.142
    },
    "tertiary": {
      "label": "Content",
      "distance": 0.198
    }
  },

  "ranked_emotions": [
    ["Calm", 0.083],
    ["Reflective", 0.142],
    ["Content", 0.198],
    ["Hopeful", 0.251],
    ["Neutral", 0.304]
  ],

  "mode": "stable",
  "api_usage": {
    "remaining": 1999,
    "limit": 2000
  }
}

Error Model

• 400 — Invalid request payload
• 401 — Missing or invalid API key
• 429 — Usage limit exceeded
• 500 — Internal engine error

Emotion Model

Serena represents affect as a 7-dimensional continuous vector: Valence, Arousal, Dominance, Predictability, Novelty, Comfort, and Surface Stability.

Design Philosophy

• Serena is a sensor, not a generator
• Vectors drive logic; labels drive UX
• Aggregate emotional state over time
• Explainability over fluency

Failure Modes & Limitations

• Short or ambiguous inputs may yield low-confidence vectors
• Sarcasm without context can flatten valence
• Cultural nuance depends on language coverage

Deployment Patterns

• Backend-only API integration
• Queue-based batch analysis
• Streaming emotional trend tracking

Roadmap

Serena evolves from a battle-tested emotional engine into the affective layer beneath agents, products, and AGI-adjacent research systems.

Changelog

v2.2 — Added tertiary classification, improved determinism, reduced latency.

FAQ

Is Serena deterministic? Yes.

Do you store user text? No.

Is this sentiment analysis? No.

Security

• No text generation
• No training on user data
• CPU-first execution with minimal attack surface