Authenticated API

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

AI Insights API

Access AI-powered business insights and recommendations.

Overview

The AI Insights API leverages machine learning to provide:

Feature	Description
Anomaly Detection	Identify unusual patterns
Trend Predictions	Forecast future performance
Recommendations	Actionable business suggestions
Sentiment Analysis	Customer feedback insights
Optimization	Menu and pricing suggestions

---

Get Insights Summary

Request

GET /api/v1/analytics/ai-insights?
  location_id=loc-xyz789&
  period=week
Authorization: Bearer {access_token}

Response

{
  "location_id": "loc-xyz789",
  "period": {
    "start": "2026-01-11",
    "end": "2026-01-18"
  },
  "summary": {
    "total_insights": 12,
    "critical": 2,
    "actionable": 5,
    "informational": 5
  },
  "insights": [
    {
      "id": "insight-001",
      "type": "anomaly",
      "severity": "critical",
      "title": "Unusual decline in lunch revenue",
      "description": "Tuesday lunch revenue was 35% below the expected range based on historical patterns.",
      "metric": {
        "name": "lunch_revenue",
        "actual": 850.00,
        "expected": 1300.00,
        "deviation": -34.6
      },
      "suggested_actions": [
        "Review staff scheduling for Tuesday lunch shift",
        "Check for local events that may have affected traffic",
        "Consider lunch promotion for next Tuesday"
      ],
      "confidence": 0.92,
      "detected_at": "2026-01-14T15:00:00Z"
    },
    {
      "id": "insight-002",
      "type": "trend",
      "severity": "info",
      "title": "Wings sales trending up",
      "description": "Crispy Wings sales have increased 25% week-over-week for the past 3 weeks.",
      "metric": {
        "name": "item_sales",
        "item_id": "item-wings",
        "growth_rate": 25.0
      },
      "suggested_actions": [
        "Ensure adequate inventory for wings",
        "Consider featuring wings in promotions"
      ],
      "confidence": 0.88,
      "detected_at": "2026-01-18T06:00:00Z"
    }
  ]
}

---

Anomaly Detection

Request

GET /api/v1/analytics/ai-insights/anomalies?
  location_id=loc-xyz789&
  start_date=2026-01-11&
  end_date=2026-01-18
Authorization: Bearer {access_token}

Response

{
  "anomalies": [
    {
      "id": "anomaly-001",
      "detected_at": "2026-01-14T15:00:00Z",
      "metric": "lunch_revenue",
      "date": "2026-01-14",
      "actual_value": 850.00,
      "expected_value": 1300.00,
      "expected_range": {"min": 1100.00, "max": 1500.00},
      "deviation_percentage": -34.6,
      "severity": "critical",
      "probable_causes": [
        {"cause": "Staffing shortage", "probability": 0.45},
        {"cause": "Weather impact", "probability": 0.30},
        {"cause": "Local event", "probability": 0.25}
      ]
    }
  ]
}

Severity Levels

Severity	Threshold	Description
critical	over 30% deviation	Immediate attention needed
warning	15-30% deviation	Should investigate
info	10-15% deviation	Worth noting

---

Trend Predictions

Request

GET /api/v1/analytics/ai-insights/predictions?
  location_id=loc-xyz789&
  metrics=revenue,orders&
  horizon_days=14
Authorization: Bearer {access_token}

Response

{
  "predictions": [
    {
      "metric": "revenue",
      "forecast": [
        {
          "date": "2026-01-19",
          "predicted": 8200.00,
          "lower_bound": 7400.00,
          "upper_bound": 9000.00,
          "confidence": 0.85
        },
        {
          "date": "2026-01-20",
          "predicted": 7800.00,
          "lower_bound": 7000.00,
          "upper_bound": 8600.00,
          "confidence": 0.82
        }
      ],
      "trend": "stable",
      "seasonality": {
        "weekly_pattern": true,
        "peak_days": ["friday", "saturday"]
      }
    }
  ],
  "model_info": {
    "algorithm": "prophet",
    "training_data_days": 365,
    "last_trained": "2026-01-18T00:00:00Z"
  }
}

---

Business Recommendations

Request

GET /api/v1/analytics/ai-insights/recommendations?
  location_id=loc-xyz789&
  categories=menu,labor,marketing
Authorization: Bearer {access_token}

Response

{
  "recommendations": [
    {
      "id": "rec-001",
      "category": "menu",
      "priority": "high",
      "title": "Consider removing Quinoa Bowl",
      "description": "Quinoa Bowl has sold only 15 units in the past 30 days with 12% food waste. Removing it could save $450/month in waste costs.",
      "impact": {
        "type": "cost_reduction",
        "estimated_value": 450.00,
        "timeframe": "monthly"
      },
      "data_points": [
        {"metric": "units_sold_30d", "value": 15},
        {"metric": "waste_percentage", "value": 12},
        {"metric": "food_cost", "value": 6.50}
      ],
      "confidence": 0.78
    },
    {
      "id": "rec-002",
      "category": "labor",
      "priority": "medium",
      "title": "Optimize Tuesday staffing",
      "description": "Tuesday 2-4pm shows consistent overstaffing. Reducing by 1 server could save $120/week without impacting service.",
      "impact": {
        "type": "cost_reduction",
        "estimated_value": 480.00,
        "timeframe": "monthly"
      },
      "data_points": [
        {"metric": "avg_customers_2pm_4pm", "value": 12},
        {"metric": "current_servers", "value": 3},
        {"metric": "recommended_servers", "value": 2}
      ],
      "confidence": 0.85
    },
    {
      "id": "rec-003",
      "category": "marketing",
      "priority": "medium",
      "title": "Launch Monday dinner promotion",
      "description": "Monday dinner revenue is 40% below weekly average. A 15% discount could increase traffic based on similar promotions at peer locations.",
      "impact": {
        "type": "revenue_increase",
        "estimated_value": 800.00,
        "timeframe": "monthly"
      },
      "confidence": 0.72
    }
  ]
}

---

Sentiment Analysis

Request

GET /api/v1/analytics/ai-insights/sentiment?
  location_id=loc-xyz789&
  start_date=2026-01-01&
  end_date=2026-01-18&
  source=reviews,surveys
Authorization: Bearer {access_token}

Response

{
  "overall_sentiment": {
    "score": 0.72,
    "label": "positive",
    "trend": "improving"
  },
  "by_category": [
    {
      "category": "food_quality",
      "score": 0.85,
      "label": "very_positive",
      "mentions": 145
    },
    {
      "category": "service",
      "score": 0.65,
      "label": "positive",
      "mentions": 98
    },
    {
      "category": "wait_time",
      "score": 0.45,
      "label": "neutral",
      "mentions": 52
    },
    {
      "category": "cleanliness",
      "score": 0.78,
      "label": "positive",
      "mentions": 34
    }
  ],
  "trending_topics": [
    {
      "topic": "new burger",
      "sentiment": 0.92,
      "mentions": 28,
      "sample_mentions": [
        "The new burger is amazing!",
        "Best burger I've had in town"
      ]
    },
    {
      "topic": "wait time",
      "sentiment": 0.35,
      "mentions": 15,
      "sample_mentions": [
        "Had to wait 20 minutes for a table",
        "Service was slow during lunch rush"
      ]
    }
  ],
  "improvement_areas": [
    {
      "area": "lunch_service_speed",
      "current_score": 0.45,
      "potential_impact": "high",
      "suggested_actions": [
        "Add staff during 12-1pm",
        "Pre-prep popular lunch items"
      ]
    }
  ]
}

---

Menu Optimization

Request

GET /api/v1/analytics/ai-insights/menu-optimization?
  location_id=loc-xyz789
Authorization: Bearer {access_token}

Response

{
  "menu_analysis": {
    "stars": [
      {
        "item": "Classic Burger",
        "popularity": "high",
        "profitability": "high",
        "recommendation": "maintain_visibility"
      }
    ],
    "puzzles": [
      {
        "item": "Ribeye Steak",
        "popularity": "low",
        "profitability": "high",
        "recommendation": "increase_promotion",
        "suggested_actions": [
          "Feature in specials board",
          "Add server recommendations script"
        ]
      }
    ],
    "plowhorses": [
      {
        "item": "Fries",
        "popularity": "high",
        "profitability": "low",
        "recommendation": "consider_price_increase",
        "potential_price": 5.49,
        "current_price": 4.99
      }
    ],
    "dogs": [
      {
        "item": "Quinoa Bowl",
        "popularity": "low",
        "profitability": "low",
        "recommendation": "remove_or_reinvent"
      }
    ]
  },
  "pricing_suggestions": [
    {
      "item": "Crispy Wings",
      "current_price": 12.99,
      "suggested_price": 14.49,
      "reasoning": "High demand elasticity detected. Price increase of $1.50 projected to increase margin without significant volume loss.",
      "estimated_impact": {
        "margin_increase": 850.00,
        "volume_change": -3.0
      }
    }
  ]
}

---

Ask AI

Natural language queries for business insights.

Request

POST /api/v1/analytics/ai-insights/ask
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "question": "What drove the revenue increase last week?",
  "location_id": "loc-xyz789",
  "context": {
    "period": "last_week"
  }
}

Response

{
  "answer": "Last week's revenue increase of 12% was primarily driven by three factors: (1) Strong Friday and Saturday performance with a local event bringing 45% more traffic than typical weekends, (2) The new Spicy Chicken Sandwich promotion which sold 180 units at $14.99 each, contributing $2,700 in incremental revenue, and (3) A 15% increase in average ticket size from successful upselling of appetizers.",
  "supporting_data": [
    {
      "metric": "weekend_traffic_increase",
      "value": 45,
      "unit": "percentage"
    },
    {
      "metric": "new_item_revenue",
      "value": 2700.00,
      "unit": "currency"
    },
    {
      "metric": "avg_ticket_increase",
      "value": 15,
      "unit": "percentage"
    }
  ],
  "confidence": 0.89,
  "model_used": "claude-sonnet-4.5"
}

---

Error Responses

Insufficient Data (400)

{
  "error": {
    "code": "INSUFFICIENT_DATA",
    "message": "Not enough historical data to generate insights",
    "minimum_days_required": 30,
    "current_days": 15
  }
}

---

Related Documentation

• Dashboard API - Real-time metrics
• AI Gateway - AI infrastructure
• Forecasting API - Demand forecasting