Documentation

Emotion APIs

The Emotion APIs let you analyze text for emotional tone with V2 EQ dimensions. Choose between Context-Based (stateful with trajectory tracking) and Stateless (per-message) analysis modes.

V2 Endpoints Summary

Method	Endpoint	Description
POST	/v2/emotions/analysis	Stateless emotion analysis
POST	/v2/emotions/{contextId}/analysis	Context-based analysis with trajectory
GET	/v2/emotions/{contextId}	Get stored emotional state
GET	/v2/emotions/{contextId}/message/{messageId}	Get message-specific emotions
POST	/v2/emotions/batch-analysis	Batch analysis for multiple texts

1. Context-Based Emotion API

Use this API when you need emotional memory, trajectory tracking, and advanced V2 features across a session.

Endpoints

Analyse & Store

POST /v2/emotions/:context_id/analysis

Retrieve Latest State

GET /v2/emotions/:context_id

Retrieve by Message

GET /v2/emotions/:context_id/message/:external_id

Request Body (Analyse)

{
  "model": "emotion-v2",
  "messages": [
    {
      "role": "user",
      "externalId": "msg-1",
      "content": {"text": "I'm really excited about this opportunity!"},
      "timestamp": "2025-01-15T10:30:00Z"
    }
  ]
}

Example Response (Analyse V2)

{
  "object": "emotions.analysis",
  "model": "emotion-v2",
  "metadata": {
    "context_id": "example-123"
  },
  "emotions": {
    "user": {
      "text": "I'm really excited about this opportunity!",
      "category": "joy",
      "intensity": 0.85,
      "intensityLevel": "high",
      "valence": 0.78,
      "arousal": 0.82,
      "complexity": "simple",
      "wonderIndex": 0.55,
      "discoveryLevel": "significant",
      "raw": {
        "joy": 0.85,
        "love": 0.25,
        "surprise": 0.30,
        "sadness": 0.02,
        "anger": 0.01,
        "fear": 0.05
      }
    }
  },
  "trajectory": {
    "trend": {
      "direction": "improving",
      "valenceTrend": 0.08
    }
  }
}

Example Response (Retrieve Latest)

{
  "object": "emotions.state",
  "model": "emotion-v2",
  "emotions": {
    "system": {
      "category": "joy",
      "intensity": 0.85,
      "valence": 0.78,
      "arousal": 0.82
    }
  },
  "trajectory": {
    "baseline": {
      "averageIntensity": 0.65,
      "baselineValence": 0.45
    },
    "trend": {
      "direction": "improving"
    }
  },
  "metadata": {
    "context_id": "example-123"
  }
}

V2 Context Features

Trajectory tracking with baseline comparison and trend detection.
Breakthrough detection for significant emotional shifts.
Growth tracking for emotional intelligence development over time.
Pattern detection for temporal, cyclical, and trigger-based patterns.
Store externalId for message-level lookups.

2. Stateless Emotion API

Use this API for per-message analysis without storing state. Still includes all V2 EQ dimensions.

Endpoint

POST /v2/emotions/analysis

Request Body

{
  "model": "emotion-v2",
  "messages": [{
    "content": {"text": "I don't know how to feel about this"}
  }]
}

Example Response (V2)

{
  "object": "emotions.analysis",
  "model": "emotion-v2",
  "emotions": {
    "_default": {
      "text": "I don't know how to feel about this",
      "category": "fear",
      "intensity": 0.45,
      "intensityLevel": "subtle",
      "valence": -0.25,
      "arousal": 0.40,
      "complexity": "layered",
      "wonderIndex": 0.35,
      "discoveryLevel": "normal",
      "raw": {
        "fear": 0.45,
        "sadness": 0.35,
        "surprise": 0.20,
        "joy": 0.10,
        "love": 0.05,
        "anger": 0.08
      }
    }
  }
}

Notes

Stateless: each request is evaluated independently with full V2 EQ dimensions.
Best for lightweight bots, analytics pipelines, or when managing state externally.
Faster and lower cost than context-based calls.
No trajectory or growth tracking (requires context).

3. Batch Analysis API

Analyze multiple texts in a single request. Perfect for social media monitoring, customer feedback, and content moderation.

Endpoint

POST /v2/emotions/batch-analysis

Request Body

{
  "model": "emotion-v2",
  "messages": [
    {"content": {"text": "I love this product!"}},
    {"content": {"text": "This is frustrating."}},
    {"content": {"text": "I'm worried about the deadline."}}
  ]
}

Example Response

{
  "object": "emotions.batch_analysis",
  "model": "emotion-v2",
  "emotions": [
    {
      "category": "love",
      "intensity": 0.88,
      "valence": 0.85,
      "arousal": 0.72
    },
    {
      "category": "anger",
      "intensity": 0.65,
      "valence": -0.60,
      "arousal": 0.68
    },
    {
      "category": "fear",
      "intensity": 0.58,
      "valence": -0.45,
      "arousal": 0.55
    }
  ],
  "usage": {
    "total_tokens": 45,
    "analyse_tokens": 45
  }
}

Batch Use Cases

Social Media Monitoring: Process multiple posts or comments in bulk.
Customer Feedback: Batch process reviews or survey responses.
Content Moderation: Efficiently analyze user-generated content.
Sentiment Tracking: Monitor emotional trends across data points.

4. Error Codes

Code	Meaning	Common causes
400	Bad Request	Missing `messages` field, invalid model
401	Unauthorized	Missing `x-api-key` header
404	Not Found	Invalid/expired `context_id`
429	Rate Limited	Retry with exponential backoff
500	Server Error	Retry or contact support

5. Choosing the Right API

Use Case	Recommended API
Single-turn emotion analysis	Stateless Analysis
Multi-turn conversation with trajectory	Context-Based
Emotional growth tracking	Context-Based
Analytics pipeline or batch processing	Stateless or Batch Analysis
Social media sentiment at scale	Batch Analysis

Next: see V2 EQ Dimensions for detailed explanations, or Unified Chat API to combine LLM and emotions in a single call.