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 text analysis, sentiment detection, and language operations.

Overview

The NLP Services provide:

Service	Purpose	Use Case
Sentiment Analysis	Detect sentiment polarity	Review analysis, feedback
Topic Extraction	Identify key topics	Trend detection
Entity Recognition	Extract named entities	Menu items, locations
Translation	Multi-language support	Localization
Command Parsing	Natural language commands	Voice AI
Conversation Analysis	Conversation insights	Support analytics

Sentiment Analysis

Analyze Text

POST /api/v1/nlp/sentiment
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "text": "The food was excellent and service was fast!",
  "language": "en"
}

Response:

{
  "label": "positive",
  "score": 0.85,
  "confidence": 0.92,
  "magnitude": 0.78,
  "positive_terms": ["excellent", "fast"],
  "negative_terms": [],
  "analyzed_at": "2026-01-19T12:00:00Z"
}

Sentiment Labels

Label	Score Range	Description
`positive`	> 0.15	Favorable sentiment
`neutral`	-0.15 to 0.15	Neutral or mixed
`negative`	< -0.15	Unfavorable sentiment

Batch Analysis

POST /api/v1/nlp/sentiment/batch
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "texts": [
    "Great food, will come back!",
    "Service was slow and cold food.",
    "Average experience, nothing special."
  ],
  "language": "en"
}

Response:

{
  "results": [
    {"label": "positive", "score": 0.78, "confidence": 0.88},
    {"label": "negative", "score": -0.65, "confidence": 0.91},
    {"label": "neutral", "score": 0.05, "confidence": 0.72}
  ],
  "summary": {
    "total": 3,
    "positive": 1,
    "neutral": 1,
    "negative": 1,
    "average_score": 0.06
  }
}

Sentiment Keywords

Default positive keywords:

excellent, great, good, love, amazing
awesome, pleasant, fast, friendly, helpful
delicious, tasty, fresh, clean, efficient

Default negative keywords:

bad, poor, slow, awful, terrible
dirty, rude, cold, stale, overpriced
late, unclean, noisy, crowded, missing

Topic Extraction

Extract Topics

POST /api/v1/nlp/topics
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "text": "The steak was overcooked but the wine selection was impressive. Our waiter John was very knowledgeable about the menu.",
  "max_topics": 5
}

Response:

{
  "topics": [
    {
      "topic": "food_quality",
      "keywords": ["steak", "overcooked"],
      "sentiment": "negative",
      "confidence": 0.85
    },
    {
      "topic": "beverages",
      "keywords": ["wine", "selection", "impressive"],
      "sentiment": "positive",
      "confidence": 0.90
    },
    {
      "topic": "service",
      "keywords": ["waiter", "knowledgeable"],
      "sentiment": "positive",
      "confidence": 0.82
    }
  ],
  "dominant_topic": "beverages"
}

Topic Categories

Category	Description	Keywords
`food_quality`	Food preparation, taste	cook, taste, fresh, raw
`service`	Staff interactions	waiter, server, friendly
`ambiance`	Environment, atmosphere	music, decor, lighting
`value`	Pricing, value perception	price, expensive, worth
`beverages`	Drinks, bar	wine, cocktail, beer
`wait_time`	Speed of service	wait, slow, fast, quick
`cleanliness`	Hygiene, cleanliness	clean, dirty, sanitary

Entity Recognition

Extract Entities

POST /api/v1/nlp/entities
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

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

Response:

{
  "entities": [
    {
      "text": "ribeye steak",
      "type": "menu_item",
      "start": 13,
      "end": 25,
      "confidence": 0.95
    },
    {
      "text": "medium-rare",
      "type": "modifier",
      "start": 26,
      "end": 37,
      "confidence": 0.98
    },
    {
      "text": "Caesar salad",
      "type": "menu_item",
      "start": 54,
      "end": 66,
      "confidence": 0.92
    },
    {
      "text": "Cabernet",
      "type": "beverage",
      "start": 85,
      "end": 93,
      "confidence": 0.89
    }
  ]
}

Entity Types

Type	Description	Examples
`menu_item`	Food items	burger, salad, steak
`modifier`	Cooking preferences	medium-rare, no onions
`beverage`	Drinks	wine, beer, soda
`allergen`	Allergen mentions	peanut, gluten, dairy
`person`	Names	John, waiter
`location`	Places	patio, bar, Table 7
`time`	Time references	7pm, tonight
`quantity`	Amounts	two, dozen, extra

Translation

Translate Text

POST /api/v1/nlp/translate
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "text": "Welcome to our restaurant. How may I help you today?",
  "source_language": "en",
  "target_language": "es"
}

Response:

{
  "translated_text": "Bienvenido a nuestro restaurante. ¿Cómo puedo ayudarle hoy?",
  "source_language": "en",
  "target_language": "es",
  "confidence": 0.96,
  "alternative_translations": [
    "Bienvenidos a nuestro restaurante. ¿En qué puedo ayudarles hoy?"
  ]
}

Supported Languages

Code	Language	Voice Support
`en`	English	Yes
`es`	Spanish	Yes
`fr`	French	Yes
`zh`	Chinese	Yes
`vi`	Vietnamese	Yes
`ko`	Korean	Yes
`ja`	Japanese	Limited
`pt`	Portuguese	Yes
`de`	German	Yes

Detect Language

POST /api/v1/nlp/detect-language
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "text": "Me gustaría ordenar una hamburguesa"
}

Response:

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

Command Parsing

Parse natural language commands for voice AI.

Parse Command

POST /api/v1/nlp/parse-command
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "text": "Add two cheeseburgers with no onions to table 7",
  "context": {
    "location_id": "loc-123",
    "user_role": "server"
  }
}

Response:

{
  "intent": "add_item",
  "confidence": 0.94,
  "entities": {
    "quantity": 2,
    "item": "cheeseburger",
    "modifiers": ["no onions"],
    "table": "7"
  },
  "action": {
    "type": "order_item",
    "parameters": {
      "menu_item_id": "item-cheeseburger",
      "quantity": 2,
      "modifiers": [{"type": "remove", "item": "onions"}],
      "table_id": "table-7"
    }
  }
}

Supported Intents

Intent	Description	Example
`add_item`	Add item to order	"Add a burger"
`remove_item`	Remove item	"Take off the fries"
`modify_item`	Change item	"Make that medium-rare"
`check_price`	Price inquiry	"How much is the steak?"
`get_status`	Order status	"Where's table 5's food?"
`call_server`	Request assistance	"We need a refill"
`process_payment`	Payment action	"Close out table 12"

Conversation Analytics

Analyze conversation transcripts for insights.

Analyze Conversation

POST /api/v1/nlp/conversation/analyze
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "messages": [
    {"role": "customer", "content": "Hi, I have a question about my order"},
    {"role": "agent", "content": "Of course! I'd be happy to help. What's your order number?"},
    {"role": "customer", "content": "It's 12345. The food was cold when it arrived."},
    {"role": "agent", "content": "I apologize for that. Let me process a refund for you right away."}
  ],
  "metrics": ["sentiment_flow", "resolution", "response_quality"]
}

Response:

{
  "summary": {
    "total_messages": 4,
    "customer_messages": 2,
    "agent_messages": 2,
    "duration_estimate": "2 minutes"
  },
  "sentiment_flow": [
    {"message": 1, "sentiment": "neutral", "score": 0.0},
    {"message": 2, "sentiment": "positive", "score": 0.6},
    {"message": 3, "sentiment": "negative", "score": -0.5},
    {"message": 4, "sentiment": "positive", "score": 0.7}
  ],
  "resolution": {
    "issue_identified": true,
    "issue_type": "food_quality",
    "resolution_offered": true,
    "resolution_type": "refund",
    "customer_satisfied": "likely"
  },
  "response_quality": {
    "empathy_score": 0.85,
    "professionalism": 0.92,
    "resolution_speed": "fast"
  },
  "topics_discussed": ["order_issue", "food_quality", "refund"]
}

Aggregate Sentiment

Get sentiment trends over time.

Get Sentiment Trends

GET /api/v1/nlp/sentiment/trends?
  start_date=2026-01-01&
  end_date=2026-01-19&
  granularity=day&
  source=reviews
Authorization: Bearer {access_token}

Response:

{
  "trends": [
    {
      "date": "2026-01-01",
      "average_score": 0.65,
      "positive_count": 45,
      "neutral_count": 12,
      "negative_count": 8,
      "total": 65
    },
    {
      "date": "2026-01-02",
      "average_score": 0.58,
      "positive_count": 38,
      "neutral_count": 15,
      "negative_count": 12,
      "total": 65
    }
  ],
  "summary": {
    "overall_average": 0.62,
    "trend_direction": "stable",
    "top_positive_topics": ["service", "food_quality"],
    "top_negative_topics": ["wait_time"]
  }
}

Error Responses

Invalid Language (400)

{
  "error": {
    "code": "INVALID_LANGUAGE",
    "message": "Language 'xyz' is not supported",
    "supported_languages": ["en", "es", "fr", "zh", "vi", "ko"]
  }
}

Text Too Long (400)

{
  "error": {
    "code": "TEXT_TOO_LONG",
    "message": "Text exceeds maximum length of 10000 characters",
    "provided_length": 15234
  }
}

Rate Limited (429)

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "NLP API rate limit exceeded",
    "retry_after": 60
  }
}

Best Practices

Sentiment Analysis

Clean input text: Remove HTML, special characters
Use batch API: For multiple texts, use batch endpoint
Consider context: Review sentiment may differ from chat
Monitor confidence: Low confidence may need manual review

Translation

Detect first: Use language detection for unknown sources
Cache results: Same text doesn't need re-translation
Review critical: Human review for customer-facing content
Handle failures: Graceful fallback to original language

Command Parsing

Provide context: Include location, role, menu context
Handle ambiguity: Confirm unclear commands
Train custom: Add domain-specific vocabulary
Log failures: Track unrecognized commands for improvement

AI Gateway - AI model routing
Voice AI - Speech processing
LangGraph Agents - Agent workflows

Overview​

Sentiment Analysis​

Analyze Text​

Sentiment Labels​

Batch Analysis​

Sentiment Keywords​

Topic Extraction​

Extract Topics​

Topic Categories​

Entity Recognition​

Extract Entities​

Entity Types​

Translation​

Translate Text​

Supported Languages​

Detect Language​

Command Parsing​

Parse Command​

Supported Intents​

Conversation Analytics​

Analyze Conversation​

Aggregate Sentiment​

Get Sentiment Trends​

Error Responses​

Invalid Language (400)​

Text Too Long (400)​

Rate Limited (429)​

Best Practices​

Sentiment Analysis​

Translation​

Command Parsing​

Related Documentation​

Overview

Sentiment Analysis

Analyze Text

Sentiment Labels

Batch Analysis

Sentiment Keywords

Topic Extraction

Extract Topics

Topic Categories

Entity Recognition

Extract Entities

Entity Types

Translation

Translate Text

Supported Languages

Detect Language

Command Parsing

Parse Command

Supported Intents

Conversation Analytics

Analyze Conversation

Aggregate Sentiment

Get Sentiment Trends

Error Responses

Invalid Language (400)

Text Too Long (400)

Rate Limited (429)

Best Practices

Sentiment Analysis

Translation

Command Parsing

Related Documentation