Introduction

The SessionMood API is a REST API that infers a user's emotional state in real time from behavioral signals — clicks, scrolls, idle time, errors, and more. Send events as they happen in the browser, then read back a mood label with confidence score, signals, and a suggested intervention action. Every response is JSON. HTTPS only.

# 1. Send events
curl -X POST "https://session-mood-api-production.up.railway.app/v1/sessions/user_abc/events" \
     -H "X-Api-Key: YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"events":[{"type":"rage_click","x":240,"y":580,"ts":1746352800}]}'

# 2. Read the mood
curl "https://session-mood-api-production.up.railway.app/v1/sessions/user_abc/mood" \
     -H "X-Api-Key: YOUR_KEY"

Authentication

All endpoints except GET /health require an API key. Pass it using either of the two supported methods below. Both are equally valid; the header approach is preferred for server-side calls.

curl "https://session-mood-api-production.up.railway.app/v1/sessions/abc/mood" \
     -H "X-Api-Key: sm_live_xxxxxxxxxxxx"

fetch("https://session-mood-api-production.up.railway.app/v1/sessions/abc/mood", {
  headers: { "X-Api-Key": "sm_live_xxxxxxxxxxxx" }
})

curl "https://session-mood-api-production.up.railway.app/v1/sessions/abc/mood" \
     -H "Authorization: Bearer sm_live_xxxxxxxxxxxx"

fetch("https://session-mood-api-production.up.railway.app/v1/sessions/abc/mood", {
  headers: {
    "Authorization": "Bearer sm_live_xxxxxxxxxxxx"
  }
})

Base URL

All API requests are made over HTTPS to the following base URL:

https://session-mood-api-production.up.railway.app

Every endpoint is prefixed with /v1, for example:

Rate Limits

Rate limits are tracked per API key on a rolling monthly basis. If you exceed your plan's session allowance, the API returns 429 Too Many Requests.

There is no documented per-minute hard limit at this time. When a rate limit is exceeded the response body will contain the standard error shape:

{
  "error": "Rate limit exceeded",
  "plan": "free",
  "limit": 5000,
  "reset_at": "2026-06-01T00:00:00.000Z"
}

session_id

The :id path parameter identifies a unique user session. The API places no format constraints on it — you can use your own session token, a UUID, or any opaque identifier you already generate.

// Option A: your own session token (already unique per user)
const sessionId = authToken.userId; // e.g. "u_8f3k2a"

// Option B: UUID generated client-side (persist in sessionStorage)
function getSessionId() {
  const key = "sm_session_id";
  let id = sessionStorage.getItem(key);
  if (!id) {
    id = crypto.randomUUID();
    sessionStorage.setItem(key, id);
  }
  return id;
}

POST /v1/keys/generate

Generate a new API key. No authentication required — this is the endpoint your signup form calls. The key is returned once and cannot be retrieved again, so store it immediately.

Request body

Example request

curl -X POST "https://session-mood-api-production.up.railway.app/v1/keys/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Acme Inc",
    "email": "dev@acme.com",
    "plan": "starter"
  }'

Response 201 Created

{
  "api_key":  "sm_4c9174cbe8250bb1d09ae779c168a4399e765819da244cbf",
  "customer": "Acme Inc",
  "email":    "dev@acme.com",
  "plan":     "starter",
  "limits":   "5,000 sessions/month",
  "message":  "Store this key safely - it won't be shown again."
}

Error responses

// 400 — missing customer_name
{ "error": "customer_name is required" }

// 400 — invalid plan
{
  "error": "Invalid plan",
  "valid_plans": ["starter", "growth", "pro"]
}

POST /v1/sessions/:id/events

Submit one or more behavioral events for a session. Events are batched — send as many as you like in a single request. The engine updates the mood score immediately and returns the current mood in the response body, so you don't need to make a separate GET /mood call after every batch.

curl -X POST \
  "https://session-mood-api-production.up.railway.app/v1/sessions/user_abc/events" \
  -H "X-Api-Key: sm_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "rage_click",
        "x": 240, "y": 580,
        "ts": 1746352800
      },
      {
        "type": "error",
        "message": "Payment failed",
        "ts": 1746352802
      },
      {
        "type": "idle",
        "duration_ms": 4500,
        "ts": 1746352807
      }
    ]
  }'

const res = await fetch(
  `https://session-mood-api-production.up.railway.app/v1/sessions/${sessionId}/events`,
  {
    method: "POST",
    headers: {
      "X-Api-Key": "sm_live_xxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      events: [
        { type: "rage_click", x: 240, y: 580, ts: Date.now() / 1000 },
        { type: "error", message: "Payment failed" },
        { type: "idle", duration_ms: 4500 },
      ],
    }),
  }
);
const data = await res.json();

{
  "session_id":    "user_abc",
  "events_stored": 3,
  "total_events":  6,
  "current_mood":  "frustrated"
}

{
  "error": "Invalid event type(s)",
  "invalid": ["page_visit"],
  "valid_types": [
    "click", "rage_click",
    "scroll", "input_pause",
    "backtrack", "back_nav",
    "page_view", "error",
    "idle", "hover",
    "focus", "blur"
  ]
}

GET /v1/sessions/:id/mood

Retrieve the current inferred mood state for a session. The response includes the mood label, a confidence score, human-readable signal descriptions, and a recommended UI action to trigger based on the mood.

curl \
  "https://session-mood-api-production.up.railway.app/v1/sessions/user_abc/mood" \
  -H "X-Api-Key: sm_live_xxxxxxxxxxxx"

const res = await fetch(
  `https://session-mood-api-production.up.railway.app/v1/sessions/${sessionId}/mood`,
  { headers: { "X-Api-Key": "sm_live_xxxxxxxxxxxx" } }
);
const mood = await res.json();

if (mood.suggested_action === "show_live_chat") {
  openLiveChat();
}

{
  "session_id":       "user_abc",
  "mood":             "frustrated",
  "confidence":       0.89,
  "signals": [
    "rage_click_detected",
    "repeated_errors"
  ],
  "suggested_action": "show_live_chat",
  "event_count":      6,
  "updated_at":       "2026-05-04T10:00:00.000Z"
}

{
  "error": "Session not found",
  "session_id": "user_abc"
}

POST /v1/sessions/:id/feedback

Record the outcome of a mood-triggered action. Sending feedback helps the engine learn over time which interventions work for which signals. This endpoint is optional but strongly recommended for production integrations.

curl -X POST \
  "https://session-mood-api-production.up.railway.app/v1/sessions/user_abc/feedback" \
  -H "X-Api-Key: sm_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action_taken": "show_live_chat",
    "was_helpful": true,
    "notes": "User started chat immediately"
  }'

await fetch(
  `https://session-mood-api-production.up.railway.app/v1/sessions/${sessionId}/feedback`,
  {
    method: "POST",
    headers: {
      "X-Api-Key": "sm_live_xxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action_taken: "show_live_chat",
      was_helpful: true,
    }),
  }
);

{
  "session_id": "user_abc",
  "feedback_recorded": true
}

{
  "error": "Missing required field",
  "field": "action_taken"
}

GET /v1/analytics/moods

Retrieve aggregate mood statistics across all sessions associated with your API key. Use this to understand the emotional landscape of your user base over time — what percentage of sessions are frustrated, how many have resulted in feedback, and so on.

curl \
  "https://session-mood-api-production.up.railway.app/v1/analytics/moods" \
  -H "X-Api-Key: sm_live_xxxxxxxxxxxx"

{
  "total_sessions": 1842,
  "feedback_count": 310,
  "mood_distribution": [
    { "mood": "browsing",    "count": 640,  "percentage": 34.7 },
    { "mood": "focused",     "count": 510,  "percentage": 27.7 },
    { "mood": "neutral",     "count": 280,  "percentage": 15.2 },
    { "mood": "frustrated",  "count": 198,  "percentage": 10.7 },
    { "mood": "confused",    "count": 144,  "percentage": 7.8  },
    { "mood": "disengaged", "count": 70,   "percentage": 3.8  },
    { "mood": "decisive",   "count": 0,    "percentage": 0.0  }
  ]
}

DELETE /v1/sessions/:id

Permanently erase all stored data for a session — events, mood state, and feedback. Intended for GDPR right-to-erasure compliance. Once deleted, the session cannot be recovered, and a subsequent GET /mood for the same ID will return 404.

curl -X DELETE \
  "https://session-mood-api-production.up.railway.app/v1/sessions/user_abc" \
  -H "X-Api-Key: sm_live_xxxxxxxxxxxx"

{
  "session_id": "user_abc",
  "deleted":    true,
  "message":    "Session data permanently erased."
}

GET /health

A simple health check endpoint. No authentication required. Use this in uptime monitors, load balancer health checks, or CI/CD pipelines to verify the API is reachable.

curl "https://session-mood-api-production.up.railway.app/health"

{
  "status":  "ok",
  "version": "1.0.0"
}

Event Types

The full catalogue of recognized event types with their optional fields and the moods they contribute to. All fields are optional except type. Providing more fields increases classification accuracy.

Mood States

The engine classifies each session into one of seven states. neutral is returned when there is insufficient data for a confident classification. All others are ranked by confidence and come with a suggested_action.

Error Codes

All errors follow a consistent JSON shape with at minimum an error string. Additional fields such as field, invalid, or valid_types may be present depending on the error type.

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

{
  "error": "Internal Server Error",
  "request_id": "req_7f3a2b"
}

{
  "error": "Session not found",
  "session_id": "user_abc"
}

{
  "error":    "Rate limit exceeded",
  "plan":     "free",
  "limit":    5000,
  "reset_at": "2026-06-01T00:00:00.000Z"
}

Response Schemas

TypeScript interfaces for all response types. Use these as a reference when integrating in typed projects, or to generate client types with tools like zod or io-ts.

interface PostEventsResponse {
  session_id:    string;   // the session identifier
  events_stored: number;   // events accepted in this request
  total_events:  number;   // cumulative event count for session
  current_mood:  MoodLabel; // updated mood after this batch
}

type MoodLabel =
  | "frustrated" | "confused" | "decisive"
  | "browsing"   | "disengaged" | "focused"
  | "neutral";

interface GetMoodResponse {
  session_id:       string;
  mood:             MoodLabel;
  confidence:       number;          // 0–1
  signals:          string[];        // e.g. ["rage_click_detected"]
  suggested_action: SuggestedAction;
  event_count:      number;
  updated_at:       string;          // ISO 8601
}

type SuggestedAction =
  | "no_action"          // do nothing
  | "show_live_chat"     // open chat widget
  | "show_tooltip"       // display contextual help
  | "show_recommendations" // surface personalized content
  | "show_exit_offer";   // discount / retention popup

interface PostFeedbackRequest {
  action_taken: string;            // required
  was_helpful?: boolean;           // optional
  notes?:       string;            // optional, max 512 chars
}

interface PostFeedbackResponse {
  session_id:        string;
  feedback_recorded: boolean;
}

interface MoodDistributionItem {
  mood:       MoodLabel;
  count:      number;
  percentage: number;   // 0–100, one decimal
}

interface GetAnalyticsResponse {
  total_sessions:    number;
  feedback_count:    number;
  mood_distribution: MoodDistributionItem[];
}

interface DeleteSessionResponse {
  session_id: string;
  deleted:    boolean;
  message:    string;
}

interface HealthResponse {
  status:  "ok" | "degraded" | "down";
  version: string;  // semver, e.g. "1.0.0"
}

interface ApiError {
  error:        string;             // human-readable error description
  message?:     string;             // additional detail (optional)
  field?:       string;             // which field caused the 400
  invalid?:     string[];           // invalid event types (400)
  valid_types?: string[];           // full list of valid types (400)
  plan?:        string;             // current plan (429)
  limit?:       number;             // plan session limit (429)
  reset_at?:    string;             // ISO 8601 reset date (429)
  session_id?:  string;             // affected session (404)
  request_id?:  string;             // opaque ID for support (500)
}