Authenticated API

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

ML Forecasting API

Machine learning models for demand forecasting, staffing optimization, churn prediction, and recommendations.

Overview

Attribute	Value
Base Path	`/api/v1/ml`
Authentication	Bearer Token
Required Roles	`manager`, `restaurant_manager`, `analytics_viewer`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Demand Forecasting

Get Demand Forecast

Predict future demand for sales, orders, and guests.

GET /api/v1/ml/forecast/demand

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`start_date`	date	Forecast start
`end_date`	date	Forecast end
`granularity`	string	`15min`, `hour`, `day`, `week`
`metric`	string	`sales`, `orders`, `guests`, `items`

Response

{
  "location_id": "loc_123",
  "metric": "sales",
  "granularity": "hour",
  "forecast": [
    {
      "timestamp": "2026-01-25T11:00:00Z",
      "predicted_value": 1250.00,
      "lower_bound": 1100.00,
      "upper_bound": 1400.00,
      "confidence": 0.85
    },
    {
      "timestamp": "2026-01-25T12:00:00Z",
      "predicted_value": 2850.00,
      "lower_bound": 2500.00,
      "upper_bound": 3200.00,
      "confidence": 0.82
    }
  ],
  "model_info": {
    "model_id": "demand_v3",
    "last_trained": "2026-01-24T00:00:00Z",
    "accuracy_metrics": {
      "mape": 8.5,
      "rmse": 125.00
    }
  },
  "factors": {
    "day_of_week": "saturday",
    "weather": "sunny",
    "local_events": ["Concert at arena"],
    "historical_pattern": "peak_day"
  }
}

Get Item Demand Forecast

Predict demand for specific menu items.

GET /api/v1/ml/forecast/demand/items

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`date`	date	Forecast date
`item_ids`	string[]	Specific items (optional)

Response

{
  "date": "2026-01-25",
  "location_id": "loc_123",
  "items": [
    {
      "item_id": "item_001",
      "name": "Ribeye Steak",
      "predicted_quantity": 45,
      "lower_bound": 38,
      "upper_bound": 52,
      "confidence": 0.80,
      "prep_recommendation": {
        "prep_quantity": 48,
        "reason": "Buffer for peak demand"
      }
    },
    {
      "item_id": "item_002",
      "name": "Grilled Salmon",
      "predicted_quantity": 28,
      "lower_bound": 22,
      "upper_bound": 34,
      "confidence": 0.78
    }
  ],
  "inventory_alerts": [
    {
      "item_id": "item_001",
      "current_stock": 30,
      "predicted_need": 45,
      "shortfall": 15,
      "action": "order_more"
    }
  ]
}

Staffing Optimization

Get Staffing Forecast

Predict optimal staffing levels.

GET /api/v1/ml/forecast/staffing

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`date`	date	Forecast date
`role`	string	Filter by role

Response

{
  "date": "2026-01-25",
  "location_id": "loc_123",
  "staffing_plan": [
    {
      "hour": 11,
      "predicted_demand": "medium",
      "recommended_staff": {
        "server": 4,
        "host": 1,
        "cook": 3,
        "dishwasher": 1,
        "bartender": 1
      },
      "confidence": 0.85
    },
    {
      "hour": 12,
      "predicted_demand": "high",
      "recommended_staff": {
        "server": 6,
        "host": 2,
        "cook": 4,
        "dishwasher": 2,
        "bartender": 2
      },
      "confidence": 0.82
    }
  ],
  "comparison_to_schedule": {
    "overstaffed_hours": [10, 15],
    "understaffed_hours": [12, 13, 18, 19],
    "potential_labor_savings": 125.00,
    "potential_service_impact": "low"
  }
}

Get Labor Cost Optimization

POST /api/v1/ml/forecast/staffing/optimize

Request Body

{
  "location_id": "loc_123",
  "date": "2026-01-25",
  "constraints": {
    "max_labor_percent": 25,
    "min_coverage": {
      "server": 2,
      "cook": 2
    },
    "max_consecutive_hours": 8
  },
  "objectives": ["minimize_cost", "maximize_coverage"]
}

Response

{
  "optimized_schedule": {
    "shifts": [
      {
        "role": "server",
        "employee_id": "emp_001",
        "start": "10:00",
        "end": "18:00",
        "break_at": "14:00"
      }
    ],
    "summary": {
      "total_hours": 145.5,
      "total_cost": 2473.50,
      "labor_percent": 19.8
    }
  },
  "savings_vs_current": {
    "hours_saved": 12.5,
    "cost_saved": 212.50,
    "percent_improvement": 7.9
  }
}

Churn Prediction

Get Churn Risk

Identify customers at risk of churning.

GET /api/v1/ml/churn/risk

Query Parameters

Parameter	Type	Description
`segment`	string	Customer segment
`min_risk`	number	Minimum risk score (0-1)
`limit`	integer	Number of results

Response

{
  "data": [
    {
      "customer_id": "cust_001",
      "customer_name": "John Doe",
      "churn_risk": 0.78,
      "risk_level": "high",
      "days_since_last_order": 45,
      "lifetime_value": 850.00,
      "risk_factors": [
        {"factor": "declining_frequency", "weight": 0.35},
        {"factor": "decreasing_spend", "weight": 0.25},
        {"factor": "no_recent_engagement", "weight": 0.18}
      ],
      "recommended_actions": [
        {
          "action": "send_winback_offer",
          "offer": "20% off next order",
          "predicted_response_rate": 0.25
        }
      ]
    }
  ],
  "summary": {
    "high_risk_customers": 125,
    "medium_risk_customers": 340,
    "at_risk_revenue": 45000.00
  }
}

Get Churn Analysis

GET /api/v1/ml/churn/analysis

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "metrics": {
    "churn_rate": 5.2,
    "at_risk_customers": 465,
    "churned_customers": 85,
    "recovered_customers": 32
  },
  "churn_reasons": [
    {"reason": "price_sensitivity", "percent": 35},
    {"reason": "poor_experience", "percent": 25},
    {"reason": "competition", "percent": 20},
    {"reason": "life_changes", "percent": 20}
  ],
  "model_performance": {
    "accuracy": 82.5,
    "precision": 78.3,
    "recall": 85.2,
    "auc_roc": 0.89
  }
}

Customer Segmentation

Get Segments

Retrieve customer segments.

GET /api/v1/ml/segments

Response

{
  "segments": [
    {
      "id": "seg_vip",
      "name": "VIP Customers",
      "description": "High-value frequent customers",
      "size": 250,
      "characteristics": {
        "avg_order_frequency": 3.5,
        "avg_order_value": 65.00,
        "avg_lifetime_value": 1250.00
      },
      "behaviors": [
        "orders_weekly",
        "prefers_premium_items",
        "high_engagement"
      ]
    },
    {
      "id": "seg_occasional",
      "name": "Occasional Diners",
      "description": "Monthly visitors",
      "size": 1250,
      "characteristics": {
        "avg_order_frequency": 0.8,
        "avg_order_value": 42.00,
        "avg_lifetime_value": 320.00
      }
    }
  ]
}

Run Segmentation

Trigger segmentation analysis.

POST /api/v1/ml/segments/analyze

Request Body

{
  "method": "rfm",
  "parameters": {
    "recency_bins": 5,
    "frequency_bins": 5,
    "monetary_bins": 5
  },
  "include_behaviors": true
}

Price Optimization

Get Price Recommendations

GET /api/v1/ml/pricing/recommendations

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`category`	string	Menu category

Response

{
  "recommendations": [
    {
      "item_id": "item_001",
      "name": "Ribeye Steak",
      "current_price": 35.00,
      "recommended_price": 37.00,
      "change_percent": 5.7,
      "rationale": "High demand, price elasticity low",
      "predicted_impact": {
        "revenue_change": 8.5,
        "volume_change": -2.1,
        "margin_change": 12.3
      },
      "confidence": 0.78
    }
  ],
  "analysis": {
    "price_sensitivity_index": 0.65,
    "competitor_price_avg": 38.00,
    "demand_elasticity": -0.45
  }
}

Simulate Price Change

POST /api/v1/ml/pricing/simulate

Request Body

{
  "item_id": "item_001",
  "new_price": 38.00,
  "duration_days": 30
}

Response

{
  "simulation": {
    "current_daily_revenue": 1225.00,
    "predicted_daily_revenue": 1330.00,
    "revenue_change_percent": 8.6,
    "predicted_daily_volume": 35,
    "volume_change_percent": -2.9,
    "break_even_volume": 32
  },
  "confidence": 0.75,
  "risk_factors": [
    "Competitor may respond with lower prices"
  ]
}

Recommendations

Get Item Recommendations

GET /api/v1/ml/recommendations/items

Query Parameters

Parameter	Type	Description
`customer_id`	string	Customer ID
`context`	string	`order`, `upsell`, `cross_sell`
`limit`	integer	Number of recommendations

Response

{
  "customer_id": "cust_001",
  "recommendations": [
    {
      "item_id": "item_005",
      "name": "Truffle Fries",
      "reason": "frequently_ordered_together",
      "confidence": 0.85,
      "expected_acceptance": 0.35
    },
    {
      "item_id": "item_008",
      "name": "Chocolate Lava Cake",
      "reason": "similar_customers_liked",
      "confidence": 0.72,
      "expected_acceptance": 0.28
    }
  ],
  "based_on": {
    "order_history": true,
    "similar_customers": true,
    "current_cart": ["item_001"]
  }
}

Model Management

List Models

GET /api/v1/ml/models

Response

{
  "models": [
    {
      "id": "demand_forecast_v3",
      "type": "demand_forecasting",
      "status": "active",
      "accuracy": {
        "mape": 8.5,
        "rmse": 125.00
      },
      "last_trained": "2026-01-24T00:00:00Z",
      "training_data_range": {
        "start": "2024-01-01",
        "end": "2026-01-23"
      }
    },
    {
      "id": "churn_predictor_v2",
      "type": "churn_prediction",
      "status": "active",
      "accuracy": {
        "auc_roc": 0.89,
        "precision": 0.78
      }
    }
  ]
}

Trigger Model Training

POST /api/v1/ml/models/{model_id}/train

Request Body

{
  "include_recent_data": true,
  "hyperparameter_tuning": false
}

Get Model Status

GET /api/v1/ml/models/{model_id}/status

Webhooks

Event	Description
`ml.forecast_ready`	New forecast available
`ml.churn_alert`	High-risk customer detected
`ml.model_trained`	Model training complete
`ml.anomaly_detected`	Prediction anomaly

Error Responses

Status	Code	Description
400	`insufficient_data`	Not enough data for prediction
400	`invalid_date_range`	Date range invalid
404	`model_not_found`	Model ID not found
503	`model_training`	Model currently training

AI Insights API - AI-generated insights
Analytics API - Analytics endpoints
Analytics Dashboard - Dashboard API

Overview​

Demand Forecasting​

Get Demand Forecast​

Get Item Demand Forecast​

Staffing Optimization​

Get Staffing Forecast​

Get Labor Cost Optimization​

Churn Prediction​

Get Churn Risk​

Get Churn Analysis​

Customer Segmentation​

Get Segments​

Run Segmentation​

Price Optimization​

Get Price Recommendations​

Simulate Price Change​

Recommendations​

Get Item Recommendations​

Model Management​

List Models​

Trigger Model Training​

Get Model Status​

Webhooks​

Error Responses​

Related Documentation​

Overview

Demand Forecasting

Get Demand Forecast

Get Item Demand Forecast

Staffing Optimization

Get Staffing Forecast

Get Labor Cost Optimization

Churn Prediction

Get Churn Risk

Get Churn Analysis

Customer Segmentation

Get Segments

Run Segmentation

Price Optimization

Get Price Recommendations

Simulate Price Change

Recommendations

Get Item Recommendations

Model Management

List Models

Trigger Model Training

Get Model Status

Webhooks

Error Responses

Related Documentation