Documentation

Emotion APIs

The Emotion APIs let you analyze text for emotional tone. You can choose between Context-Based (stateful, memory across a session) and Non-Context (stateless, per message) modes.

1. Context-Based Emotion API

Use this API when you need emotional memory across a session or conversation.

Endpoints

Analyse & Store

POST /v1/emotions/:context_id/analyse

⚠ Your draft spec used GET with a body, but best practice is POST.

Retrieve Latest State

GET /v1/emotions/:context_id

Retrieve by Message

GET /v1/emotions/:context_id/message/:external_id

Parameters

Field	Type	Required	Description
context_id	string	✔	Unique ID for the session (≤128 bytes).
external_id	string	✔ (for message lookup)	Unique message ID supplied when analysing.

Request Body (Analyse)

{
  "model": "emotion-v1",
  "params": {},
  "messages": [
    {
      "role": "user",
      "external_id": "msg-1",
      "content": {"text": "You are awesome!"}
    }
  ]
}

Example Response (Analyse)

{
  "object": "emotions.analyse",
  "model": "emotion-v1",
  "metadata": {
    "context_id": "example-123"
  },
  "emotions": {
    "user": {
      "text": "Highly JOY",
      "category": "joy",
      "raw": {
        "joy": 0.99,
        "anger": 0.003,
        "sadness": 0.002,
        "fear": 0.001,
        "surprise": 0.0008,
        "love": 0.0006
      }
    }
  }
}

Example Response (Retrieve Latest)

{
  "object": "emotions.state",
  "model": "emotion-v1",
  "emotions": {
    "system": {
      "text": "Highly JOY",
      "category": "joy",
      "raw": {
        "joy": 0.99,
        "fear": 0.001,
        "love": 0.0006,
        "anger": 0.003,
        "sadness": 0.002,
        "surprise": 0.0008
      }
    }
  },
  "metadata": {
    "context_id": "example-123"
  }
}

Example Response (Retrieve by Message)

{
  "object": "emotions.state",
  "model": "emotion-v1",
  "metadata": {
    "context_id": "example-123",
    "message_id": "msg-1"
  },
  "emotions": {
    "user": {
      "text": "Highly JOY",
      "category": "joy",
      "raw": {
        "joy": 0.99,
        "fear": 0.001,
        "love": 0.0006,
        "anger": 0.003,
        "sadness": 0.002,
        "surprise": 0.0008
      }
    }
  }
}

⚙ Notes

• Use Context-Based API for multi-turn conversations or long-lived agents.
• Each context_id accumulates and updates emotional state until expired.
• Store external_id for message-level lookups.
• Contexts may expire after inactivity (default TTL — document in your system).

2. Non-Context Emotion API

Use this API when you only need to analyze emotions per message and don't want Kaiko to store state.

Endpoint

POST /v1/emotions/analyse

Request Body

{
  "model": "emotion-v1",
  "params": {},
  "messages": [{
    "content": {"text": "I don't know"}
  }]
}

Example Response

{
  "object": "emotions.analyse",
  "model": "emotion-v1",
  "emotions": {
    "_default": {
      "text": "Slightly ANGER",
      "category": "anger",
      "raw": {
        "anger": 0.42,
        "sadness": 0.31,
        "joy": 0.15,
        "fear": 0.09,
        "love": 0.008,
        "surprise": 0.003
      }
    }
  }
}

⚙ Notes

• Stateless: each request is evaluated independently.
• Best for lightweight bots, analytics pipelines, or when your system manages its own memory.
• Faster & lower cost than context-based calls.

3. Batch Analyse Emotion API

Use this API to analyze multiple messages in a single request. Perfect for bulk processing and analytics.

Endpoint

POST /v1/emotions/batch-analyse

Headers

Header	Value
x-api-key	Your Kaiko API key
Content-Type	application/json

Request Body

{
  "model": "emotion-v1",
  "params": {},
  "messages": [{
    "content": {
      "text": "I don't know"
    }
  }]
}

Example Response

{
  "object": "emotions.batch_analyse",
  "model": "emotion-v1",
  "params": {},
  "emotions": [{
    "text": "Slightly ANGER",
    "category": "anger",
    "raw": {
      "anger": 0.4281120002269745,
      "sadness": 0.31644850969314575,
      "joy": 0.15173210203647614,
      "fear": 0.0920100063085556,
      "love": 0.008168447762727737,
      "surprise": 0.0035288953222334385
    }
  }],
  "metadata": {},
  "usage": {}
}

⚙ Notes

• Process multiple messages in a single API call for efficiency.
• Returns an array of emotion results matching the order of input messages.
• Ideal for batch processing, analytics pipelines, and bulk emotion analysis.
• Each message is analyzed independently (stateless).
• Consider rate limits when processing large batches.

4. Error Codes

Code	Meaning	Common causes
400	Bad Request	Missing `messages` field, wrong type
401	Unauthorized	No `x-api-key` header
404	Not Found	Invalid/expired `context_id`
413	Payload Too Large	Too many or too long inputs
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	Non-Context
Multi-turn conversation with memory	Context-Based
Emotional state tied to a session	Context-Based
Analytics pipeline or offline batch	Non-Context or Batch Analyse
Bulk processing of multiple messages	Batch Analyse

Next: see Quickstart for copy-paste examples, or Unified Chat API to combine LLM and emotions in a single call.