Authenticated API

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

Bottleneck Detection API

Real-time service bottleneck detection, speed of service analytics, and AI-powered staff coaching recommendations.

Overview

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

Event Recording

Record Service Event

Record a service timing event for bottleneck analysis.

POST /api/v1/bottleneck/events

Request Body

{
  "location_id": "loc_123",
  "order_id": "ord_456",
  "event_type": "station_complete",
  "station": "grill",
  "employee_id": "emp_001",
  "timestamp": "2026-01-24T12:30:45Z",
  "metadata": {
    "items_completed": 3,
    "complexity_score": 7,
    "modifications": 2
  }
}

Response

{
  "event_id": "evt_001",
  "recorded": true,
  "analysis": {
    "within_target": false,
    "target_seconds": 180,
    "actual_seconds": 245,
    "deviation_percent": 36
  }
}

Event Types

Event Type	Description
`order_received`	Order entered system
`order_sent_to_kitchen`	Sent to kitchen display
`station_start`	Station began working
`station_complete`	Station finished items
`order_ready`	Order fully prepared
`order_delivered`	Delivered to customer
`drive_thru_arrival`	Car arrived at speaker
`drive_thru_order_complete`	Order placed at speaker
`drive_thru_payment`	Payment processed
`drive_thru_handoff`	Food handed to customer

Batch Record Events

POST /api/v1/bottleneck/events/batch

Request Body

{
  "events": [
    {
      "order_id": "ord_456",
      "event_type": "station_start",
      "station": "grill",
      "timestamp": "2026-01-24T12:26:30Z"
    },
    {
      "order_id": "ord_456",
      "event_type": "station_complete",
      "station": "grill",
      "timestamp": "2026-01-24T12:30:45Z"
    }
  ]
}

Bottleneck Detection

Detect Current Bottlenecks

Get real-time bottleneck analysis.

POST /api/v1/bottleneck/detect

Request Body

{
  "location_id": "loc_123",
  "time_window_minutes": 30
}

Response

{
  "location_id": "loc_123",
  "analysis_time": "2026-01-24T12:30:00Z",
  "overall_status": "degraded",
  "bottlenecks": [
    {
      "station": "grill",
      "severity": "high",
      "current_wait_time_seconds": 245,
      "target_wait_time_seconds": 180,
      "queue_depth": 8,
      "throughput_per_hour": 45,
      "expected_throughput": 60,
      "contributing_factors": [
        {
          "factor": "understaffed",
          "impact": "high",
          "detail": "1 cook vs recommended 2"
        },
        {
          "factor": "complex_orders",
          "impact": "medium",
          "detail": "40% orders have modifications"
        }
      ],
      "recommendations": [
        {
          "action": "add_staff",
          "urgency": "immediate",
          "detail": "Assign additional cook to grill station"
        },
        {
          "action": "menu_86",
          "urgency": "if_worsens",
          "detail": "Consider 86ing slow-cooking items temporarily"
        }
      ]
    }
  ],
  "flow_analysis": {
    "avg_ticket_time_seconds": 485,
    "target_ticket_time_seconds": 360,
    "orders_in_progress": 15,
    "predicted_clear_time": "2026-01-24T12:55:00Z"
  }
}

Get Historical Bottlenecks

GET /api/v1/bottleneck/history

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`start_date`	datetime	Period start
`end_date`	datetime	Period end
`station`	string	Filter by station
`min_severity`	string	`low`, `medium`, `high`

Response

{
  "bottlenecks": [
    {
      "id": "bn_001",
      "station": "grill",
      "started_at": "2026-01-24T12:15:00Z",
      "resolved_at": "2026-01-24T12:45:00Z",
      "duration_minutes": 30,
      "severity": "high",
      "peak_queue_depth": 12,
      "orders_affected": 25,
      "resolution": "additional_staff_assigned"
    }
  ],
  "patterns": [
    {
      "station": "grill",
      "recurring_times": ["11:30-12:30", "17:30-19:00"],
      "frequency": "daily",
      "recommendation": "Schedule additional grill cook during these windows"
    }
  ]
}

Station Metrics

Get Station Metrics

GET /api/v1/bottleneck/stations

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`period`	string	`realtime`, `1h`, `today`, `7d`

Response

{
  "location_id": "loc_123",
  "period": "today",
  "stations": [
    {
      "station": "grill",
      "status": "busy",
      "metrics": {
        "orders_completed": 145,
        "avg_completion_time_seconds": 195,
        "target_time_seconds": 180,
        "performance_score": 82,
        "throughput_per_hour": 52
      },
      "current": {
        "queue_depth": 5,
        "active_items": 8,
        "estimated_clear_time_seconds": 480
      },
      "staff": [
        {
          "employee_id": "emp_001",
          "name": "John",
          "items_completed": 85,
          "avg_time_seconds": 188
        }
      ]
    },
    {
      "station": "fryer",
      "status": "normal",
      "metrics": {
        "orders_completed": 98,
        "avg_completion_time_seconds": 145,
        "target_time_seconds": 150,
        "performance_score": 95,
        "throughput_per_hour": 48
      }
    },
    {
      "station": "expo",
      "status": "normal",
      "metrics": {
        "orders_completed": 180,
        "avg_completion_time_seconds": 45,
        "target_time_seconds": 60,
        "performance_score": 98
      }
    }
  ],
  "summary": {
    "total_orders": 180,
    "avg_ticket_time_seconds": 425,
    "target_ticket_time_seconds": 360,
    "overall_performance_score": 88
  }
}

Station Status Values

Status	Description
`idle`	No active orders
`normal`	Operating within targets
`busy`	High volume, within targets
`degraded`	Falling behind targets
`critical`	Significant delays

Configure Station Targets

PUT /api/v1/bottleneck/stations/targets

Request Body

{
  "location_id": "loc_123",
  "targets": [
    {
      "station": "grill",
      "target_time_seconds": 180,
      "max_queue_depth": 6,
      "min_staff": 2,
      "rush_hour_targets": {
        "hours": ["11:00-13:00", "17:00-20:00"],
        "target_time_seconds": 150,
        "min_staff": 3
      }
    },
    {
      "station": "fryer",
      "target_time_seconds": 150,
      "max_queue_depth": 8
    }
  ]
}

Speed of Service

Get Speed of Service Report

GET /api/v1/bottleneck/speed-of-service

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`period`	string	`today`, `week`, `month`
`service_type`	string	`dine_in`, `drive_thru`, `pickup`

Response

{
  "location_id": "loc_123",
  "period": "today",
  "service_type": "drive_thru",
  "summary": {
    "total_orders": 245,
    "avg_total_time_seconds": 185,
    "target_total_time_seconds": 180,
    "performance_score": 94
  },
  "breakdown": {
    "speaker_to_order": {
      "avg_seconds": 45,
      "target_seconds": 60,
      "score": 100
    },
    "order_to_payment": {
      "avg_seconds": 65,
      "target_seconds": 60,
      "score": 88
    },
    "payment_to_handoff": {
      "avg_seconds": 75,
      "target_seconds": 60,
      "score": 80
    }
  },
  "by_hour": [
    {
      "hour": "11:00",
      "orders": 35,
      "avg_time_seconds": 195,
      "score": 90
    },
    {
      "hour": "12:00",
      "orders": 48,
      "avg_time_seconds": 225,
      "score": 78
    }
  ],
  "comparison": {
    "vs_yesterday": -5.2,
    "vs_last_week": 2.8,
    "vs_target": -2.7
  }
}

Staff Coaching

Generate Coaching Recommendations

POST /api/v1/bottleneck/coaching

Request Body

{
  "location_id": "loc_123",
  "employee_id": "emp_001",
  "period": "7d"
}

Response

{
  "employee_id": "emp_001",
  "employee_name": "John Smith",
  "station": "grill",
  "period": "7d",
  "performance": {
    "orders_completed": 425,
    "avg_time_seconds": 195,
    "target_time_seconds": 180,
    "performance_score": 85,
    "rank": 3,
    "total_staff": 8
  },
  "strengths": [
    {
      "area": "consistency",
      "detail": "Very consistent timing across all order types",
      "metric": "Low variance (±12 seconds)"
    },
    {
      "area": "quality",
      "detail": "Zero remake requests this week"
    }
  ],
  "coaching_opportunities": [
    {
      "area": "complex_orders",
      "priority": "high",
      "observation": "Takes 35% longer on orders with 3+ modifications",
      "suggestion": "Practice modification workflow - prep common mods ahead during slower periods",
      "expected_improvement": "15-20 seconds per complex order"
    },
    {
      "area": "station_setup",
      "priority": "medium",
      "observation": "First 30 minutes of shift are 20% slower",
      "suggestion": "Arrive 5 minutes early to verify station setup and preheat equipment",
      "expected_improvement": "Faster start to shift"
    }
  ],
  "training_recommendations": [
    {
      "course": "Advanced Grill Techniques",
      "reason": "Would help with complex order efficiency"
    }
  ],
  "generated_at": "2026-01-24T19:30:00Z"
}

Get Staff Leaderboard

GET /api/v1/bottleneck/leaderboard

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`station`	string	Filter by station
`period`	string	`today`, `week`, `month`
`metric`	string	`speed`, `quality`, `overall`

Response

{
  "location_id": "loc_123",
  "station": "grill",
  "period": "week",
  "metric": "overall",
  "leaderboard": [
    {
      "rank": 1,
      "employee_id": "emp_005",
      "name": "Maria G.",
      "score": 96,
      "metrics": {
        "avg_time_seconds": 165,
        "orders_completed": 520,
        "quality_score": 100
      },
      "badges": ["speed_champion", "quality_star"],
      "trend": "up"
    },
    {
      "rank": 2,
      "employee_id": "emp_003",
      "name": "James T.",
      "score": 92,
      "metrics": {
        "avg_time_seconds": 175,
        "orders_completed": 485,
        "quality_score": 98
      },
      "trend": "same"
    },
    {
      "rank": 3,
      "employee_id": "emp_001",
      "name": "John S.",
      "score": 85,
      "metrics": {
        "avg_time_seconds": 195,
        "orders_completed": 425,
        "quality_score": 100
      },
      "trend": "up"
    }
  ],
  "team_average": {
    "score": 84,
    "avg_time_seconds": 188
  }
}

Real-time Dashboard

Get Live Dashboard Data

GET /api/v1/bottleneck/dashboard/live

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location

Response

{
  "location_id": "loc_123",
  "timestamp": "2026-01-24T12:30:00Z",
  "orders": {
    "in_progress": 15,
    "waiting_kitchen": 4,
    "being_prepared": 8,
    "ready_for_expo": 3
  },
  "stations": {
    "grill": {"queue": 5, "status": "busy", "wait_seconds": 180},
    "fryer": {"queue": 3, "status": "normal", "wait_seconds": 90},
    "saute": {"queue": 2, "status": "normal", "wait_seconds": 60},
    "expo": {"queue": 3, "status": "normal", "wait_seconds": 30}
  },
  "alerts": [
    {
      "type": "bottleneck",
      "station": "grill",
      "message": "Queue depth exceeds threshold"
    }
  ],
  "predictions": {
    "next_30_min_orders": 45,
    "expected_bottleneck": "grill",
    "recommended_action": "Consider calling in backup cook"
  }
}

Webhooks

Event	Description
`bottleneck.detected`	New bottleneck detected
`bottleneck.resolved`	Bottleneck cleared
`bottleneck.worsening`	Bottleneck severity increased
`sos.target_missed`	Speed of service target missed
`coaching.recommendation`	New coaching recommendation

Error Responses

Status	Code	Description
400	`invalid_event`	Event data invalid
400	`invalid_station`	Station not configured
404	`location_not_found`	Location ID not found
404	`employee_not_found`	Employee ID not found

KDS API - Kitchen Display System API
Cockpit Operations - Operations dashboard
Staff Training - Training API

Overview​

Event Recording​

Record Service Event​

Event Types​

Batch Record Events​

Bottleneck Detection​

Detect Current Bottlenecks​

Get Historical Bottlenecks​

Station Metrics​

Get Station Metrics​

Station Status Values​

Configure Station Targets​

Speed of Service​

Get Speed of Service Report​

Staff Coaching​

Generate Coaching Recommendations​

Get Staff Leaderboard​

Real-time Dashboard​

Get Live Dashboard Data​

Webhooks​

Error Responses​

Related Documentation​

Overview

Event Recording

Record Service Event

Event Types

Batch Record Events

Bottleneck Detection

Detect Current Bottlenecks

Get Historical Bottlenecks

Station Metrics

Get Station Metrics

Station Status Values

Configure Station Targets

Speed of Service

Get Speed of Service Report

Staff Coaching

Generate Coaching Recommendations

Get Staff Leaderboard

Real-time Dashboard

Get Live Dashboard Data

Webhooks

Error Responses

Related Documentation