Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/ai/*.

NLP Services API

Natural language processing services for sentiment analysis, intent recognition, entity extraction, and text analysis.

Overview

Attribute	Value
Base Path	`/api/v1/nlp`
Authentication	Bearer Token
Required Roles	`ml_engineer`, `data_scientist`, `analytics_admin`, `platform_admin`, `system_admin`, `super_admin`

Sentiment Analysis

Analyze Sentiment

Analyze sentiment of text content.

POST /api/v1/nlp/sentiment

Request Body

{
  "text": "The food was absolutely amazing! Best steak I've ever had. Service was a bit slow though.",
  "options": {
    "granularity": "sentence",
    "include_aspects": true,
    "language": "en"
  }
}

Response

{
  "overall": {
    "sentiment": "positive",
    "score": 0.72,
    "confidence": 0.89
  },
  "sentences": [
    {
      "text": "The food was absolutely amazing!",
      "sentiment": "positive",
      "score": 0.95
    },
    {
      "text": "Best steak I've ever had.",
      "sentiment": "positive",
      "score": 0.92
    },
    {
      "text": "Service was a bit slow though.",
      "sentiment": "negative",
      "score": -0.45
    }
  ],
  "aspects": [
    {
      "aspect": "food",
      "sentiment": "positive",
      "score": 0.94,
      "mentions": ["food", "steak"]
    },
    {
      "aspect": "service",
      "sentiment": "negative",
      "score": -0.45,
      "mentions": ["service"]
    }
  ],
  "emotions": {
    "joy": 0.65,
    "satisfaction": 0.72,
    "frustration": 0.15
  }
}

Batch Sentiment Analysis

Analyze multiple texts at once.

POST /api/v1/nlp/sentiment/batch

Request Body

{
  "texts": [
    "Great experience overall!",
    "The wait was too long",
    "Food was okay, nothing special"
  ],
  "options": {
    "include_aspects": false
  }
}

Response

{
  "results": [
    {"text": "Great experience overall!", "sentiment": "positive", "score": 0.85},
    {"text": "The wait was too long", "sentiment": "negative", "score": -0.62},
    {"text": "Food was okay, nothing special", "sentiment": "neutral", "score": 0.05}
  ],
  "summary": {
    "positive": 1,
    "neutral": 1,
    "negative": 1,
    "avg_score": 0.09
  }
}

Intent Recognition

Recognize Intent

Identify user intent from text.

POST /api/v1/nlp/intent

Request Body

{
  "text": "I'd like to make a reservation for 4 people tomorrow at 7pm",
  "context": {
    "channel": "chat",
    "previous_intents": []
  }
}

Response

{
  "intent": {
    "name": "make_reservation",
    "confidence": 0.94
  },
  "entities": [
    {
      "type": "party_size",
      "value": 4,
      "text": "4 people",
      "confidence": 0.98
    },
    {
      "type": "date",
      "value": "2026-01-25",
      "text": "tomorrow",
      "confidence": 0.95
    },
    {
      "type": "time",
      "value": "19:00",
      "text": "7pm",
      "confidence": 0.97
    }
  ],
  "alternate_intents": [
    {"name": "check_availability", "confidence": 0.35},
    {"name": "get_hours", "confidence": 0.12}
  ],
  "suggested_response": "I'd be happy to help you make a reservation for 4 people tomorrow at 7pm. Let me check availability."
}

Common Intents

Intent	Description
`make_reservation`	Book a table
`check_availability`	Check table availability
`modify_reservation`	Change existing booking
`cancel_reservation`	Cancel booking
`get_hours`	Ask about hours
`get_menu`	Request menu info
`place_order`	Order food
`track_order`	Check order status
`make_complaint`	Register complaint
`give_feedback`	Leave feedback
`ask_question`	General inquiry

Train Custom Intent

Add custom intent to the model.

POST /api/v1/nlp/intent/train

Request Body

{
  "intent_name": "ask_about_specials",
  "training_examples": [
    "What are today's specials?",
    "Do you have any specials?",
    "What's on special today?",
    "Tell me about the daily special"
  ],
  "entities": []
}

Entity Extraction

Extract Entities

Extract named entities from text.

POST /api/v1/nlp/entities

Request Body

{
  "text": "I ordered the ribeye steak medium-rare with a side of truffle fries and a glass of Cabernet",
  "entity_types": ["menu_item", "modifier", "beverage"]
}

Response

{
  "entities": [
    {
      "type": "menu_item",
      "value": "ribeye steak",
      "start": 13,
      "end": 25,
      "confidence": 0.95,
      "normalized": {
        "item_id": "item_001",
        "name": "Ribeye Steak"
      }
    },
    {
      "type": "modifier",
      "value": "medium-rare",
      "start": 26,
      "end": 37,
      "confidence": 0.97,
      "category": "temperature"
    },
    {
      "type": "menu_item",
      "value": "truffle fries",
      "start": 53,
      "end": 66,
      "confidence": 0.92
    },
    {
      "type": "beverage",
      "value": "Cabernet",
      "start": 82,
      "end": 90,
      "confidence": 0.88,
      "normalized": {
        "item_id": "bev_015",
        "name": "Cabernet Sauvignon"
      }
    }
  ]
}

Entity Types

Type	Description
`menu_item`	Menu items
`modifier`	Item modifiers
`beverage`	Drinks
`ingredient`	Ingredients
`allergen`	Allergens
`dietary`	Dietary preferences
`person_name`	Customer names
`phone_number`	Phone numbers
`date`	Dates
`time`	Times
`number`	Quantities
`location`	Addresses/places

Topic Analysis

Analyze Topics

Extract topics from text collection.

POST /api/v1/nlp/topics

Request Body

{
  "texts": [
    "The steak was cooked perfectly",
    "Love the atmosphere here",
    "Service was excellent",
    "Great wine selection",
    "Food took a while to arrive"
  ],
  "num_topics": 3
}

Response

{
  "topics": [
    {
      "id": 0,
      "name": "Food Quality",
      "keywords": ["steak", "cooked", "perfectly", "food"],
      "weight": 0.45,
      "documents": [0, 4]
    },
    {
      "id": 1,
      "name": "Service",
      "keywords": ["service", "excellent", "arrive", "while"],
      "weight": 0.30,
      "documents": [2, 4]
    },
    {
      "id": 2,
      "name": "Ambiance",
      "keywords": ["atmosphere", "love", "wine", "selection"],
      "weight": 0.25,
      "documents": [1, 3]
    }
  ]
}

Text Classification

Classify Text

Classify text into predefined categories.

POST /api/v1/nlp/classify

Request Body

{
  "text": "The burger was cold when it arrived and the fries were soggy",
  "categories": ["praise", "complaint", "question", "suggestion"]
}

Response

{
  "classification": "complaint",
  "confidence": 0.92,
  "probabilities": {
    "complaint": 0.92,
    "suggestion": 0.05,
    "question": 0.02,
    "praise": 0.01
  },
  "subcategories": [
    {"category": "food_quality", "confidence": 0.88},
    {"category": "temperature", "confidence": 0.75}
  ]
}

Train Classifier

Train custom text classifier.

POST /api/v1/nlp/classify/train

Request Body

{
  "name": "review_classifier",
  "training_data": [
    {"text": "Excellent service!", "label": "praise"},
    {"text": "Food was cold", "label": "complaint"},
    {"text": "Do you have gluten-free options?", "label": "question"}
  ]
}

Language Detection

Detect Language

POST /api/v1/nlp/language/detect

Request Body

{
  "text": "La comida estuvo deliciosa"
}

Response

{
  "language": "es",
  "language_name": "Spanish",
  "confidence": 0.98,
  "alternatives": [
    {"language": "pt", "confidence": 0.15}
  ]
}

Text Summarization

Summarize Text

POST /api/v1/nlp/summarize

Request Body

{
  "text": "Long review text here...",
  "max_length": 100,
  "style": "extractive"
}

Response

{
  "summary": "Great food and atmosphere. Service was a bit slow but worth the wait.",
  "key_points": [
    "Excellent food quality",
    "Nice ambiance",
    "Slow service"
  ]
}

Review Analysis

Analyze Reviews

Comprehensive review analysis.

POST /api/v1/nlp/reviews/analyze

Request Body

{
  "reviews": [
    {
      "id": "rev_001",
      "text": "Amazing food, great service!",
      "rating": 5
    },
    {
      "id": "rev_002",
      "text": "Food was okay, service was slow",
      "rating": 3
    }
  ]
}

Response

{
  "analysis": {
    "overall_sentiment": 0.45,
    "avg_rating": 4.0,
    "sentiment_rating_correlation": 0.85
  },
  "aspect_summary": {
    "food": {
      "mentions": 2,
      "avg_sentiment": 0.55,
      "keywords": ["amazing", "okay"]
    },
    "service": {
      "mentions": 2,
      "avg_sentiment": 0.25,
      "keywords": ["great", "slow"]
    }
  },
  "actionable_insights": [
    {
      "category": "service",
      "insight": "Service speed mentioned negatively in 50% of reviews",
      "priority": "high",
      "suggested_action": "Review staffing during peak hours"
    }
  ],
  "individual_results": [...]
}

Command Parsing

Parse Natural Language Command

POST /api/v1/nlp/command

Request Body

{
  "text": "Show me sales for last week by category",
  "context": {
    "current_view": "dashboard",
    "user_role": "manager"
  }
}

Response

{
  "command": {
    "action": "show_report",
    "report_type": "sales",
    "parameters": {
      "time_range": "last_week",
      "group_by": "category"
    }
  },
  "executable": true,
  "api_call": {
    "endpoint": "/api/v1/analytics/sales",
    "method": "GET",
    "params": {
      "start_date": "2026-01-17",
      "end_date": "2026-01-24",
      "group_by": "category"
    }
  },
  "confirmation": "Showing sales by category for the last 7 days"
}

Webhooks

Event	Description
`nlp.sentiment_alert`	Negative sentiment detected
`nlp.intent_unknown`	Unrecognized intent
`nlp.model_updated`	Model updated

Error Responses

Status	Code	Description
400	`text_too_long`	Text exceeds max length
400	`unsupported_language`	Language not supported
400	`invalid_entity_type`	Unknown entity type
422	`insufficient_training_data`	Need more examples

Voice AI - Voice processing
AI Insights - AI-generated insights
LangGraph Agents - Agent orchestration

Overview​

Sentiment Analysis​

Analyze Sentiment​

Batch Sentiment Analysis​

Intent Recognition​

Recognize Intent​

Common Intents​

Train Custom Intent​

Entity Extraction​

Extract Entities​

Entity Types​

Topic Analysis​

Analyze Topics​

Text Classification​

Classify Text​

Train Classifier​

Language Detection​

Detect Language​

Text Summarization​

Summarize Text​

Review Analysis​

Analyze Reviews​

Command Parsing​

Parse Natural Language Command​

Webhooks​

Error Responses​

Related Documentation​

Overview

Sentiment Analysis

Analyze Sentiment

Batch Sentiment Analysis

Intent Recognition

Recognize Intent

Common Intents

Train Custom Intent

Entity Extraction

Extract Entities

Entity Types

Topic Analysis

Analyze Topics

Text Classification

Classify Text

Train Classifier

Language Detection

Detect Language

Text Summarization

Summarize Text

Review Analysis

Analyze Reviews

Command Parsing

Parse Natural Language Command

Webhooks

Error Responses

Related Documentation