Emotions

Emotions and emotion categories are used to tag dialog blocks, enabling the emotional arc analysis feature. The hierarchy is: Category → Emotions.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/emotions/emotions	authenticated	List emotions
GET	/api/emotions/emotions/:id	authenticated	Get emotion by ID
POST	/api/emotions/emotions	emotion:create	Create an emotion
PUT / PATCH	/api/emotions/emotions/:id	emotion:edit	Update an emotion
DELETE	/api/emotions/emotions/:id	emotion:delete	Delete an emotion
GET	/api/emotions/categories	authenticated	List all categories
GET	/api/emotions/categories/with-emotions	authenticated	List categories with emotions
GET	/api/emotions/categories/:id	authenticated	Get category by ID
POST	/api/emotions/categories	emotion:category:create	Create a category
PUT / PATCH	/api/emotions/categories/:id	emotion:category:edit	Update a category
DELETE	/api/emotions/categories/:id	emotion:category:delete	Delete a category

Emotion Endpoints

List emotions

GET /api/emotions/emotions — Auth required

Query params (optional)

Param	Type	Description
categoryId	string	Filter by category UUID

Response — 200

[
  {
    "id": "em-uuid-001",
    "emoji": "😊",
    "keywords": ["happy", "cheerful", "glad"],
    "categoryId": "cat-uuid-001",
    "createdAt": "2025-01-10T09:00:00.000Z",
    "updatedAt": "2025-01-10T09:00:00.000Z",
    "keywordsI18n": {
      "uk": ["щасливий", "веселий", "радісний"],
      "en": ["happy", "cheerful", "glad"],
      "es": ["feliz", "alegre", "contento"]
    }
  }
]

---

Get emotion by ID

GET /api/emotions/emotions/:id — Auth required

Response — 200 — single emotion object (same shape as list item)

---

Create emotion

POST /api/emotions/emotions — Auth required, Permission: emotion:create

Request body

{
  "emoji": "😊",
  "keywords": ["happy", "cheerful", "glad"],
  "categoryId": "cat-uuid-001",
  "lang": "en"
}

Field	Required	Notes
emoji	yes	Emoji character
keywords	yes	Non-empty string array
categoryId	yes	UUID of the parent category
lang	no	Source language (uk, en, es). Auto-detected if omitted.

Response — 201

{
  "id": "em-uuid-002",
  "emoji": "😊",
  "keywords": ["happy", "cheerful", "glad"],
  "categoryId": "cat-uuid-001",
  "createdAt": "2025-04-10T08:00:00.000Z",
  "updatedAt": "2025-04-10T08:00:00.000Z",
  "keywordsI18n": {
    "uk": ["щасливий", "веселий", "радісний"],
    "en": ["happy", "cheerful", "glad"],
    "es": ["feliz", "alegre", "contento"]
  }
}

---

Update emotion

PUT /api/emotions/emotions/:id or PATCH /api/emotions/emotions/:id — Auth required, Permission: emotion:edit

Request body (all fields optional)

{
  "emoji": "😄",
  "keywords": ["joyful", "elated"],
  "categoryId": "cat-uuid-001",
  "lang": "en"
}

Response — 200 — updated emotion object

---

Delete emotion

DELETE /api/emotions/emotions/:id — Auth required, Permission: emotion:delete

Response — 204

---

Emotion Category Endpoints

List all categories

GET /api/emotions/categories — Auth required

Response — 200

[
  {
    "id": "cat-uuid-001",
    "icon": "😊",
    "name": "Positive",
    "order": 1,
    "createdAt": "2025-01-08T09:00:00.000Z",
    "updatedAt": "2025-01-08T09:00:00.000Z",
    "nameI18n": { "uk": "Позитивні", "en": "Positive", "es": "Positivas" }
  }
]

---

List categories with emotions

GET /api/emotions/categories/with-emotions — Auth required

Returns each category with its nested emotions array — used when populating the emotion picker.

Response — 200

[
  {
    "id": "cat-uuid-001",
    "icon": "😊",
    "name": "Positive",
    "order": 1,
    "nameI18n": { "uk": "Позитивні", "en": "Positive", "es": "Positivas" },
    "emotions": [
      {
        "id": "em-uuid-001",
        "emoji": "😊",
        "keywords": ["happy", "cheerful"],
        "categoryId": "cat-uuid-001",
        "keywordsI18n": {
          "uk": ["щасливий", "веселий"],
          "en": ["happy", "cheerful"],
          "es": ["feliz", "alegre"]
        }
      }
    ]
  }
]

---

Get category by ID

GET /api/emotions/categories/:id — Auth required

Response — 200 — single category object (same shape as list item, without emotions)

---

Create category

POST /api/emotions/categories — Auth required, Permission: emotion:category:create

Request body

{
  "icon": "😊",
  "name": "Positive",
  "order": 1
}

Field	Required	Notes
icon	yes	Emoji or icon string
name	yes	Auto-translated
order	yes	Non-negative integer for display ordering

Response — 201

{
  "id": "cat-uuid-002",
  "icon": "😊",
  "name": "Positive",
  "order": 1,
  "nameI18n": { "uk": "Позитивні", "en": "Positive", "es": "Positivas" }
}

---

Update category

PUT /api/emotions/categories/:id or PATCH /api/emotions/categories/:id — Auth required, Permission: emotion:category:edit

Request body (all fields optional)

{
  "icon": "🌟",
  "name": "Uplifting",
  "order": 2
}

Response — 200 — updated category object

---

Delete category

DELETE /api/emotions/categories/:id — Auth required, Permission: emotion:category:delete

Response — 204