API Reference

Predictions

AI-powered sales forecasting and operational recommendations. Possfer analyzes your historical sales data to predict demand, identify top items, and suggest optimal staffing levels.

Data Requirements

Predictions require at least 30 days of historical sales data to generate meaningful forecasts. Accuracy improves with more data. The model accounts for day-of-week patterns, seasonal trends, and local events.

Demand Prediction

Get the predicted demand for a specific date, broken down by meal period. Useful for inventory planning and preparation.

GET/api/predictions/demandAdmin Only

Returns predicted order volume and revenue for the specified date, segmented by meal period.

Query Parameters

Name	Type	Required	Description
`date`	`string (YYYY-MM-DD)`	Required	The date to predict demand for. Can be today or a future date. Example: 2026-03-25

Response

json

{
  __PH0__: "2026-03-25",
  __PH2__: 0.87,
  __PH3__: 165,
  __PH4__: 4620.00,
  __PH5__: 248,
  __PH6__: [
    {
      __PH7__: "lunch",
      __PH9__: "11:00-15:00",
      __PH11__: 72,
      __PH12__: 1944.00,
      __PH13__: 108
    },
    {
      __PH14__: "dinner",
      __PH16__: "17:00-22:00",
      __PH18__: 85,
      __PH19__: 2550.00,
      __PH20__: 128
    },
    {
      __PH21__: "other",
      __PH23__: "15:00-17:00",
      __PH25__: 8,
      __PH26__: 126.00,
      __PH27__: 12
    }
  ],
  __PH28__: [
    "Wednesday historically 12% below weekly average",
    "No local events detected",
    "Weather forecast: clear, 18°C"
  ]
}

Response Fields

Name	Type	Required	Description
`date`	`string`	Required	The date the prediction covers.
`confidence`	`number (0-1)`	Required	Model confidence score. Higher values indicate more reliable predictions.
`predicted_orders`	`integer`	Required	Predicted total number of orders for the day.
`predicted_revenue`	`number`	Required	Predicted gross revenue in EUR.
`predicted_guests`	`integer`	Required	Predicted guest count (covers).
`periods`	`array`	Required	Breakdown by meal period (lunch, dinner, other).
`factors`	`string[]`	Required	Human-readable factors influencing the prediction.

Predicted Top Items

Get the predicted best-selling menu items for a specific date. Helps with ingredient preparation and stock ordering.

GET/api/predictions/itemsAdmin Only

Returns a ranked list of menu items predicted to sell the most on the specified date.

Query Parameters

Name	Type	Required	Description
`date`	`string (YYYY-MM-DD)`	Required	The date to predict item demand for.
`limit`	`integer`	Optional	Maximum number of items to return. Default: 10, Max: 50.

Response

json

{
  __PH0__: "2026-03-25",
  __PH2__: [
    {
      __PH3__: "550e8400-e29b-41d4-a716-446655440010",
      __PH5__: "Schnitzel Wiener Art",
      __PH7__: "Hauptgerichte",
      __PH9__: 38,
      __PH10__: 608.00,
      __PH11__: 0.91
    },
    {
      __PH12__: "550e8400-e29b-41d4-a716-446655440011",
      __PH14__: "Currywurst mit Pommes",
      __PH16__: "Hauptgerichte",
      __PH18__: 32,
      __PH19__: 384.00,
      __PH20__: 0.88
    },
    {
      __PH21__: "550e8400-e29b-41d4-a716-446655440012",
      __PH23__: "Flammkuchen Elsässer Art",
      __PH25__: "Vorspeisen",
      __PH27__: 24,
      __PH28__: 264.00,
      __PH29__: 0.82
    }
  ]
}

Response Fields (per item)

Name	Type	Required	Description
`item_id`	`string (UUID)`	Required	Menu item identifier.
`name`	`string`	Required	Menu item display name.
`category`	`string`	Required	Category the item belongs to.
`predicted_quantity`	`integer`	Required	Predicted number of units to be sold.
`predicted_revenue`	`number`	Required	Predicted revenue from this item in EUR.
`confidence`	`number (0-1)`	Required	Prediction confidence for this specific item.

Staffing Recommendations

Get AI-generated staffing recommendations based on predicted demand. Helps optimize labor costs while maintaining service quality.

GET/api/predictions/staffAdmin Only

Returns recommended staffing levels per role and time slot based on predicted demand.

Query Parameters

Name	Type	Required	Description
`date`	`string (YYYY-MM-DD)`	Required	The date to get staffing recommendations for.

Response

json

{
  __PH0__: "2026-03-25",
  __PH2__: 62.5,
  __PH3__: [
    {
      __PH4__: "10:00-15:00",
      __PH6__: "high",
      __PH8__: {
        __PH9__: 3,
        __PH10__: 4,
        __PH11__: 1,
        __PH12__: 1
      },
      __PH13__: "Lunch rush expected. Consider additional kitchen support 11:30-13:30."
    },
    {
      __PH15__: "15:00-17:00",
      __PH17__: "low",
      __PH19__: {
        __PH20__: 1,
        __PH21__: 1,
        __PH22__: 1,
        __PH23__: 0
      },
      __PH24__: "Quiet period. Minimal staffing sufficient."
    },
    {
      __PH26__: "17:00-23:00",
      __PH28__: "medium",
      __PH30__: {
        __PH31__: 2,
        __PH32__: 3,
        __PH33__: 1,
        __PH34__: 1
      },
      __PH35__: "Steady evening service. No reservations for large groups."
    }
  ]
}

Response Fields

Name	Type	Required	Description
`date`	`string`	Required	The date the recommendation covers.
`total_staff_hours`	`number`	Required	Total recommended staff-hours for the day.
`shifts`	`array`	Required	Recommended staffing per time slot.
`shifts[].time_range`	`string`	Required	Time window for this shift block.
`shifts[].predicted_demand`	`string`	Required	Expected demand level. Values: "low", "medium", "high".
`shifts[].roles`	`object`	Required	Recommended headcount per role (kitchen, service, bar, cashier).
`shifts[].notes`	`string`	Required	Human-readable context and suggestions for this time slot.