Documentation

Quickstart

Welcome to the Kaiko API! This guide will get you making your first requests in minutes.

1. Get an API Key

All requests must include:

x-api-key: YOUR_API_KEY

2. Base URL

All endpoints are prefixed with:

https://api.kaiko.ai/v1

3. Make Your First Calls

Example 1: Stateless Emotion Analysis

Use the Non-Context API to analyze a single message.

curl https://api.kaiko.ai/v1/emotions/analyse \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "emotion-v1",
    "messages": [{
      "content": {"text": "I feel a bit unsure about this"}
    }]
  }'

Response (truncated):

{
  "object": "emotions.analyse",
  "emotions": {
    "_default": {
      "text": "Slightly FEAR",
      "category": "fear",
      "raw": {
        "fear": 0.62,
        "sadness": 0.21,
        "joy": 0.09
      }
    }
  }
}

Example 2: Context-Based Emotion Analysis

For agents that need memory across a session:

curl https://api.kaiko.ai/v1/emotions/user-session-123/analyse \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "emotion-v1",
    "messages": [{
      "role": "user",
      "external_id": "msg-1",
      "content": {"text": "This is great!"}
    }]
  }'

Later, retrieve the state:

curl https://api.kaiko.ai/v1/emotions/user-session-123 \
  -H "x-api-key: $KAIKO_API_KEY"

Example 3: Unified Chat + Emotion

Talk to an LLM and get emotion inference in the same call:

curl https://api.kaiko.ai/v1/chat/completions \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-nano",
    "emotion_model": "emotion-v1",
    "context_id": "user-session-alpha-789",
    "messages": [
      {"role": "user", "content": "You are adorable"}
    ]
  }'

Response (truncated):

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Thank you! That really made me smile."
    }
  }],
  "emotions": {
    "user": {"category": "joy"},
    "assistant": {"category": "joy"}
  }
}

You're ready to build with Kaiko. See Unified Chat API for full schema details.