Authenticated API

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

Forecasting API

AI-powered demand and resource forecasting.

Overview

The Forecasting API provides predictive analytics:

Feature	Description
Sales Forecasting	Predict future revenue
Demand Planning	Item-level demand prediction
Labor Forecasting	Optimal staffing levels
Inventory Forecasting	Stock requirements
Capacity Planning	Table and seat predictions

Sales Forecast

Request

GET /api/v1/forecasting/sales?
  location_id=loc-xyz789&
  start_date=2026-01-19&
  end_date=2026-01-25&
  granularity=day
Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`location_id`	string	Location to forecast
`start_date`	date	Forecast start
`end_date`	date	Forecast end
`granularity`	string	hour, day, week

Response

{
  "location_id": "loc-xyz789",
  "forecast_period": {
    "start": "2026-01-19",
    "end": "2026-01-25"
  },
  "forecast": [
    {
      "date": "2026-01-19",
      "day_of_week": "sunday",
      "predicted_revenue": 7500.00,
      "confidence_interval": {
        "lower": 6800.00,
        "upper": 8200.00
      },
      "confidence": 0.85,
      "factors": [
        {"name": "day_of_week", "impact": 0.3},
        {"name": "historical_trend", "impact": 0.5},
        {"name": "weather", "impact": 0.1}
      ]
    },
    {
      "date": "2026-01-20",
      "day_of_week": "monday",
      "predicted_revenue": 5800.00,
      "confidence_interval": {
        "lower": 5200.00,
        "upper": 6400.00
      },
      "confidence": 0.88
    }
  ],
  "summary": {
    "total_predicted": 48500.00,
    "avg_daily": 6928.57,
    "peak_day": "2026-01-24",
    "peak_revenue": 9200.00
  },
  "model_info": {
    "algorithm": "prophet_ensemble",
    "training_data_days": 365,
    "accuracy_mape": 8.5
  }
}

Hourly Forecast

Request

GET /api/v1/forecasting/hourly?
  location_id=loc-xyz789&
  date=2026-01-19
Authorization: Bearer {access_token}

Response

{
  "date": "2026-01-19",
  "hours": [
    {
      "hour": "11:00",
      "predicted_revenue": 450.00,
      "predicted_orders": 12,
      "predicted_guests": 20,
      "confidence": 0.82
    },
    {
      "hour": "12:00",
      "predicted_revenue": 1250.00,
      "predicted_orders": 35,
      "predicted_guests": 58,
      "confidence": 0.85
    },
    {
      "hour": "13:00",
      "predicted_revenue": 980.00,
      "predicted_orders": 28,
      "predicted_guests": 45,
      "confidence": 0.83
    }
  ],
  "peak_hours": ["12:00", "18:00", "19:00"]
}

Item Demand Forecast

Predict demand for specific menu items.

Request

GET /api/v1/forecasting/demand?
  location_id=loc-xyz789&
  date=2026-01-19&
  items=item-burger,item-wings,item-fries
Authorization: Bearer {access_token}

Response

{
  "date": "2026-01-19",
  "items": [
    {
      "item_id": "item-burger",
      "name": "Classic Burger",
      "predicted_quantity": 85,
      "confidence_interval": {
        "lower": 75,
        "upper": 95
      },
      "confidence": 0.87,
      "by_hour": [
        {"hour": "11:00", "quantity": 5},
        {"hour": "12:00", "quantity": 18},
        {"hour": "13:00", "quantity": 12}
      ]
    },
    {
      "item_id": "item-wings",
      "name": "Crispy Wings",
      "predicted_quantity": 62,
      "confidence_interval": {
        "lower": 55,
        "upper": 70
      },
      "confidence": 0.84
    },
    {
      "item_id": "item-fries",
      "name": "Classic Fries",
      "predicted_quantity": 120,
      "confidence_interval": {
        "lower": 105,
        "upper": 135
      },
      "confidence": 0.89
    }
  ]
}

Labor Forecast

Request

GET /api/v1/forecasting/labor?
  location_id=loc-xyz789&
  date=2026-01-19
Authorization: Bearer {access_token}

Response

{
  "date": "2026-01-19",
  "recommended_schedule": [
    {
      "hour": "11:00",
      "roles": {
        "server": {"recommended": 3, "current_scheduled": 3},
        "cook": {"recommended": 2, "current_scheduled": 2},
        "host": {"recommended": 1, "current_scheduled": 1}
      },
      "total_staff": 6,
      "expected_sales_per_labor_hour": 125.00
    },
    {
      "hour": "12:00",
      "roles": {
        "server": {"recommended": 5, "current_scheduled": 4},
        "cook": {"recommended": 3, "current_scheduled": 2},
        "host": {"recommended": 1, "current_scheduled": 1}
      },
      "total_staff": 9,
      "alert": "understaffed",
      "expected_sales_per_labor_hour": 140.00
    }
  ],
  "summary": {
    "total_hours_recommended": 98,
    "total_hours_scheduled": 92,
    "coverage_gaps": [
      {
        "hour": "12:00",
        "role": "server",
        "gap": 1
      },
      {
        "hour": "12:00",
        "role": "cook",
        "gap": 1
      }
    ],
    "estimated_labor_cost": 2450.00,
    "labor_percentage": 14.2
  }
}

Inventory Forecast

Request

GET /api/v1/forecasting/inventory?
  location_id=loc-xyz789&
  start_date=2026-01-19&
  end_date=2026-01-25
Authorization: Bearer {access_token}

Response

{
  "forecast_period": {
    "start": "2026-01-19",
    "end": "2026-01-25"
  },
  "items": [
    {
      "inventory_id": "inv-beef",
      "name": "Ground Beef",
      "unit": "lb",
      "current_stock": 75,
      "predicted_usage": 120,
      "days_until_stockout": 4,
      "reorder_recommendation": {
        "quantity": 100,
        "order_by": "2026-01-20",
        "urgency": "medium"
      }
    },
    {
      "inventory_id": "inv-chicken",
      "name": "Chicken Breast",
      "unit": "lb",
      "current_stock": 25,
      "predicted_usage": 85,
      "days_until_stockout": 2,
      "reorder_recommendation": {
        "quantity": 100,
        "order_by": "2026-01-19",
        "urgency": "high"
      }
    }
  ],
  "alerts": [
    {
      "type": "low_stock",
      "item": "Chicken Breast",
      "message": "Stock will run out in 2 days"
    }
  ]
}

Capacity Forecast

Request

GET /api/v1/forecasting/capacity?
  location_id=loc-xyz789&
  date=2026-01-19
Authorization: Bearer {access_token}

Response

{
  "date": "2026-01-19",
  "capacity": {
    "tables": 20,
    "seats": 80
  },
  "forecast": [
    {
      "hour": "12:00",
      "predicted_guests": 58,
      "predicted_occupancy_percent": 72.5,
      "wait_time_minutes": 0,
      "reservations": 12
    },
    {
      "hour": "18:00",
      "predicted_guests": 75,
      "predicted_occupancy_percent": 93.8,
      "wait_time_minutes": 15,
      "reservations": 28
    },
    {
      "hour": "19:00",
      "predicted_guests": 80,
      "predicted_occupancy_percent": 100.0,
      "wait_time_minutes": 25,
      "reservations": 35
    }
  ],
  "recommendations": [
    {
      "type": "reservation_limit",
      "hour": "19:00",
      "message": "Consider limiting new reservations for 7pm"
    },
    {
      "type": "waitlist_prep",
      "hour": "18:00",
      "message": "Prepare waitlist system for dinner rush"
    }
  ]
}

Event Impact Forecast

Predict impact of special events.

Request

POST /api/v1/forecasting/event-impact
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "location_id": "loc-xyz789",
  "event": {
    "type": "local_event",
    "name": "Football Game",
    "date": "2026-01-26",
    "venue_proximity_miles": 0.5,
    "expected_attendance": 50000
  }
}

Response

{
  "event": "Football Game",
  "date": "2026-01-26",
  "baseline_forecast": {
    "revenue": 7500.00,
    "guests": 200
  },
  "event_adjusted_forecast": {
    "revenue": 12000.00,
    "guests": 350
  },
  "impact": {
    "revenue_increase": 60.0,
    "guest_increase": 75.0
  },
  "recommendations": [
    "Increase staffing by 50%",
    "Pre-prep popular game day items",
    "Consider extended hours",
    "Ensure adequate inventory"
  ],
  "confidence": 0.78
}

Forecast Accuracy

Request

GET /api/v1/forecasting/accuracy?
  location_id=loc-xyz789&
  start_date=2026-01-01&
  end_date=2026-01-18
Authorization: Bearer {access_token}

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-18"
  },
  "metrics": {
    "revenue": {
      "mape": 8.5,
      "mae": 650.00,
      "rmse": 820.00
    },
    "orders": {
      "mape": 7.2,
      "mae": 12,
      "rmse": 15
    },
    "labor": {
      "mape": 6.8,
      "mae": 2.5,
      "rmse": 3.2
    }
  },
  "daily_accuracy": [
    {
      "date": "2026-01-18",
      "predicted_revenue": 8200.00,
      "actual_revenue": 8542.50,
      "error_percent": 4.0
    }
  ]
}

Error Responses

Insufficient Data (400)

{
  "error": {
    "code": "INSUFFICIENT_DATA",
    "message": "Not enough historical data for accurate forecasting",
    "minimum_days_required": 30,
    "current_days": 15
  }
}

Forecast Too Far Out (400)

{
  "error": {
    "code": "FORECAST_RANGE_EXCEEDED",
    "message": "Cannot forecast more than 30 days ahead",
    "max_days": 30,
    "requested_days": 45
  }
}

AI Insights - AI-powered analytics
Inventory API - Inventory management
Dashboard API - Real-time metrics

Overview​

Sales Forecast​

Request​

Query Parameters​

Response​

Hourly Forecast​

Request​

Response​

Item Demand Forecast​

Request​

Response​

Labor Forecast​

Request​

Response​

Inventory Forecast​

Request​

Response​

Capacity Forecast​

Request​

Response​

Event Impact Forecast​

Request​

Response​

Forecast Accuracy​

Request​

Response​

Error Responses​

Insufficient Data (400)​

Forecast Too Far Out (400)​

Related Documentation​

Overview

Sales Forecast

Request

Query Parameters

Response

Hourly Forecast

Request

Response

Item Demand Forecast

Request

Response

Labor Forecast

Request

Response

Inventory Forecast

Request

Response

Capacity Forecast

Request

Response

Event Impact Forecast

Request

Response

Forecast Accuracy

Request

Response

Error Responses

Insufficient Data (400)

Forecast Too Far Out (400)

Related Documentation