Authenticated API

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

AI Insights API

AI-generated business insights, recommendations, anomaly detection, and automated analysis.

Overview

Attribute	Value
Base Path	`/api/v1/ai/insights`
Authentication	Bearer Token
Required Roles	JWT authentication required (no specific role restriction)

Dashboard Insights

Get Insights Dashboard

Retrieve AI-generated insights for the dashboard.

GET /api/v1/ai/insights/dashboard

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`period`	string	`today`, `week`, `month`
`categories`	string[]	Filter by insight categories

Response

{
  "generated_at": "2026-01-24T19:30:00Z",
  "summary": {
    "total_insights": 12,
    "actionable": 8,
    "critical": 2,
    "opportunities_value": 4500.00
  },
  "highlights": [
    {
      "id": "insight_001",
      "type": "opportunity",
      "category": "revenue",
      "title": "Happy Hour Expansion",
      "description": "Extending happy hour by 1 hour could increase weekday revenue by 12%",
      "impact": {
        "metric": "revenue",
        "estimated_value": 2500.00,
        "period": "monthly"
      },
      "confidence": 0.85,
      "priority": "high",
      "action": {
        "type": "recommendation",
        "text": "Consider extending happy hour to 7pm on weekdays",
        "link": "/settings/promotions"
      }
    },
    {
      "id": "insight_002",
      "type": "alert",
      "category": "operations",
      "title": "Kitchen Bottleneck Detected",
      "description": "Grill station showing 25% longer prep times during lunch rush",
      "impact": {
        "metric": "service_time",
        "current": 18,
        "target": 12,
        "unit": "minutes"
      },
      "confidence": 0.92,
      "priority": "critical",
      "action": {
        "type": "investigate",
        "text": "Review grill station staffing 11am-2pm",
        "link": "/analytics/kitchen"
      }
    }
  ],
  "insights_by_category": {
    "revenue": 4,
    "operations": 3,
    "customers": 3,
    "labor": 2
  }
}

Insight Types

Type	Description
`opportunity`	Revenue/growth opportunity
`alert`	Issue requiring attention
`trend`	Emerging pattern
`anomaly`	Unusual deviation
`recommendation`	Best practice suggestion
`prediction`	Future forecast

Get All Insights

GET /api/v1/ai/insights

Query Parameters

Parameter	Type	Description
`type`	string	Filter by type
`category`	string	Filter by category
`priority`	string	`critical`, `high`, `medium`, `low`
`status`	string	`new`, `viewed`, `actioned`, `dismissed`
`limit`	integer	Number of results

Response

{
  "data": [
    {
      "id": "insight_001",
      "type": "opportunity",
      "category": "revenue",
      "title": "Happy Hour Expansion",
      "description": "Extending happy hour by 1 hour could increase weekday revenue by 12%",
      "details": {
        "current_happy_hour": "4pm-6pm",
        "suggested": "4pm-7pm",
        "analysis": {
          "competitor_comparison": "3 nearby competitors offer until 7pm",
          "customer_feedback": "15 mentions requesting later hours",
          "traffic_pattern": "25% of potential customers arrive after 6pm"
        }
      },
      "impact": {
        "metric": "revenue",
        "estimated_value": 2500.00,
        "confidence_range": [1800.00, 3200.00],
        "period": "monthly"
      },
      "confidence": 0.85,
      "priority": "high",
      "status": "new",
      "created_at": "2026-01-24T06:00:00Z",
      "expires_at": "2026-02-24T06:00:00Z"
    }
  ]
}

Get Insight Details

GET /api/v1/ai/insights/{insight_id}

Response

{
  "id": "insight_001",
  "type": "opportunity",
  "category": "revenue",
  "title": "Happy Hour Expansion",
  "full_analysis": {
    "summary": "Analysis of 90 days of sales data suggests...",
    "data_points": [
      {"date": "2026-01-23", "metric": "revenue_6pm_7pm", "value": 450.00},
      {"date": "2026-01-22", "metric": "revenue_6pm_7pm", "value": 380.00}
    ],
    "methodology": "Time series analysis with seasonal adjustment",
    "assumptions": [
      "Similar customer behavior to current happy hour",
      "No significant competitor response"
    ],
    "risks": [
      "May cannibalize regular price sales",
      "Staff scheduling impact"
    ]
  },
  "supporting_evidence": [
    {
      "type": "data",
      "title": "Post-Happy Hour Traffic",
      "chart_url": "https://..."
    },
    {
      "type": "benchmark",
      "title": "Industry Comparison",
      "content": "Top quartile restaurants extend happy hour to 7pm"
    }
  ],
  "related_insights": ["insight_005", "insight_008"],
  "actions": [
    {
      "id": "action_001",
      "label": "Implement Recommendation",
      "type": "setting_change",
      "endpoint": "/api/v1/promotions/happy-hour",
      "parameters": {"end_time": "19:00"}
    },
    {
      "id": "action_002",
      "label": "Run A/B Test",
      "type": "experiment",
      "description": "Test extended hours at one location first"
    }
  ]
}

Update Insight Status

PATCH /api/v1/ai/insights/{insight_id}

Request Body

{
  "status": "actioned",
  "action_taken": "Implemented happy hour extension",
  "notes": "Will monitor for 2 weeks"
}

Dismiss Insight

POST /api/v1/ai/insights/{insight_id}/dismiss

Request Body

{
  "reason": "not_applicable",
  "feedback": "We have lease restrictions on operating hours"
}

Automated Analysis

Request Analysis

Trigger AI analysis on specific topic.

POST /api/v1/ai/insights/analyze

Request Body

{
  "topic": "menu_optimization",
  "scope": {
    "location_id": "loc_123",
    "time_range": {
      "start": "2026-01-01",
      "end": "2026-01-24"
    }
  },
  "questions": [
    "Which menu items have declining sales?",
    "What items should be promoted more?",
    "Are there pricing opportunities?"
  ]
}

Response

{
  "analysis_id": "analysis_001",
  "status": "processing",
  "estimated_completion": "2026-01-24T19:35:00Z"
}

Get Analysis Results

GET /api/v1/ai/insights/analyze/{analysis_id}

Response

{
  "analysis_id": "analysis_001",
  "status": "completed",
  "topic": "menu_optimization",
  "results": {
    "summary": "Analysis identified 3 underperforming items and 5 upsell opportunities...",
    "findings": [
      {
        "finding": "Declining Items",
        "items": [
          {
            "item_id": "item_025",
            "name": "Garden Salad",
            "trend": -15,
            "period": "30_days",
            "recommendation": "Consider recipe refresh or promotion"
          }
        ]
      },
      {
        "finding": "Upsell Opportunities",
        "items": [
          {
            "base_item": "Ribeye Steak",
            "upsell_item": "Truffle Butter Add-on",
            "current_attach_rate": 12,
            "target_attach_rate": 25,
            "potential_revenue": 850.00
          }
        ]
      },
      {
        "finding": "Pricing Opportunities",
        "items": [
          {
            "item_id": "item_001",
            "name": "Ribeye Steak",
            "current_price": 35.00,
            "suggested_price": 37.00,
            "elasticity": -0.3,
            "expected_impact": "+5% revenue"
          }
        ]
      }
    ],
    "confidence": 0.82
  },
  "completed_at": "2026-01-24T19:35:00Z"
}

Anomaly Detection

Get Anomalies

GET /api/v1/ai/insights/anomalies

Query Parameters

Parameter	Type	Description
`severity`	string	`critical`, `high`, `medium`, `low`
`category`	string	Filter by category
`status`	string	`active`, `investigating`, `resolved`

Response

{
  "data": [
    {
      "id": "anomaly_001",
      "category": "sales",
      "severity": "high",
      "title": "Unusual sales drop",
      "description": "Saturday dinner sales 35% below expected",
      "detected_at": "2026-01-24T22:00:00Z",
      "metrics": {
        "expected": 8500.00,
        "actual": 5525.00,
        "deviation_percent": -35
      },
      "possible_causes": [
        {"cause": "Weather", "likelihood": 0.65, "detail": "Heavy rain forecast"},
        {"cause": "Competition", "likelihood": 0.25, "detail": "New restaurant opened nearby"},
        {"cause": "Internal", "likelihood": 0.10, "detail": "No obvious issues"}
      ],
      "status": "active"
    }
  ]
}

Acknowledge Anomaly

POST /api/v1/ai/insights/anomalies/{anomaly_id}/acknowledge

Request Body

{
  "root_cause": "weather",
  "notes": "Heavy snowstorm affected entire area"
}

Recommendations

Get Recommendations

GET /api/v1/ai/insights/recommendations

Query Parameters

Parameter	Type	Description
`category`	string	Filter by category
`impact`	string	`high`, `medium`, `low`

Response

{
  "data": [
    {
      "id": "rec_001",
      "category": "staffing",
      "title": "Optimize Friday lunch staffing",
      "description": "Add 1 server during 12-2pm Friday lunch rush",
      "reasoning": "Analysis shows 15% longer wait times during this period",
      "impact": {
        "type": "service_improvement",
        "estimated_value": "8% faster service",
        "cost": 85.00
      },
      "effort": "low",
      "priority_score": 85
    }
  ]
}

Apply Recommendation

POST /api/v1/ai/insights/recommendations/{rec_id}/apply

Response

{
  "success": true,
  "action_taken": "Schedule updated for Friday lunch",
  "changes": [
    {
      "type": "schedule",
      "detail": "Added server shift 11:30am-2:30pm Friday"
    }
  ]
}

Trends

Get Trends

GET /api/v1/ai/insights/trends

Response

{
  "data": [
    {
      "id": "trend_001",
      "category": "customer_behavior",
      "title": "Growing preference for online ordering",
      "description": "Online orders increased 25% over 90 days",
      "metrics": {
        "current_percent": 35,
        "previous_percent": 28,
        "growth_rate": 25
      },
      "projection": {
        "30_days": 38,
        "90_days": 45
      },
      "implications": [
        "May need additional packaging supplies",
        "Consider dedicated online order prep station"
      ],
      "confidence": 0.88
    }
  ]
}

Custom Queries

Ask AI

Natural language query to AI.

POST /api/v1/ai/insights/query

Request Body

{
  "question": "Why were sales lower last Tuesday compared to other Tuesdays?",
  "context": {
    "location_id": "loc_123"
  }
}

Response

{
  "query_id": "query_001",
  "question": "Why were sales lower last Tuesday compared to other Tuesdays?",
  "answer": {
    "summary": "Last Tuesday's sales were 18% below the 4-week Tuesday average, primarily due to weather conditions.",
    "factors": [
      {
        "factor": "Weather",
        "impact": "high",
        "detail": "Rain from 5pm-9pm reduced dinner traffic by 25%"
      },
      {
        "factor": "Holiday proximity",
        "impact": "medium",
        "detail": "Day before holiday may have reduced corporate lunch orders"
      }
    ],
    "comparison": {
      "last_tuesday": 8500.00,
      "avg_tuesday": 10400.00,
      "variance": -18.3
    }
  },
  "confidence": 0.78,
  "follow_up_questions": [
    "How do rainy days typically affect sales?",
    "What promotions work best on slow days?"
  ]
}

Webhooks

Event	Description
`insights.new_insight`	New insight generated
`insights.critical_alert`	Critical issue detected
`insights.anomaly_detected`	Anomaly found
`insights.analysis_complete`	Analysis finished

Error Responses

Status	Code	Description
400	`invalid_query`	Query could not be processed
404	`insight_not_found`	Insight ID not found
429	`analysis_quota_exceeded`	Too many analysis requests

Analytics API - Analytics endpoints
Analytics Dashboard API - Dashboard API reference

Overview​

Dashboard Insights​

Get Insights Dashboard​

Insight Types​

Get All Insights​

Get Insight Details​

Update Insight Status​

Dismiss Insight​

Automated Analysis​

Request Analysis​

Get Analysis Results​

Anomaly Detection​

Get Anomalies​

Acknowledge Anomaly​

Recommendations​

Get Recommendations​

Apply Recommendation​

Trends​

Get Trends​

Custom Queries​

Ask AI​

Webhooks​

Error Responses​

Related Documentation​

Overview

Dashboard Insights

Get Insights Dashboard

Insight Types

Get All Insights

Get Insight Details

Update Insight Status

Dismiss Insight

Automated Analysis

Request Analysis

Get Analysis Results

Anomaly Detection

Get Anomalies

Acknowledge Anomaly

Recommendations

Get Recommendations

Apply Recommendation

Trends

Get Trends

Custom Queries

Ask AI

Webhooks

Error Responses

Related Documentation