Authenticated API

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

Kitchen Display API

Manage kitchen display systems (KDS), ticket routing, station configuration, and prep tracking.

Authentication Required

All endpoints require a Device Token or Bearer Token. See Authentication for details.

Overview

Attribute	Value
Base Path	`/api/v1/kitchen`
Authentication	Device Token or Bearer Token
Required Roles	`kitchen_staff`, `chef`, `sous_chef`, `line_cook`, `expeditor`, `manager`, `pos_staff`, `server`, `restaurant_staff`

Station Management

List Stations

Retrieve all kitchen stations for a location.

GET /api/v1/kitchen/stations

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`status`	string	`active`, `inactive`

Response

{
  "data": [
    {
      "id": "station_grill",
      "name": "Grill Station",
      "type": "prep",
      "display_order": 1,
      "status": "active",
      "device_id": "kds_001",
      "assigned_categories": ["entrees", "burgers"],
      "current_tickets": 5,
      "avg_completion_seconds": 480
    },
    {
      "id": "station_fry",
      "name": "Fry Station",
      "type": "prep",
      "display_order": 2,
      "status": "active",
      "assigned_categories": ["sides", "appetizers"]
    },
    {
      "id": "station_expo",
      "name": "Expo",
      "type": "expo",
      "display_order": 99,
      "status": "active"
    }
  ]
}

Station Types

Type	Description
`prep`	Preparation station
`expo`	Expeditor station
`bar`	Bar/drinks station
`dessert`	Dessert station
`salad`	Salad/cold prep

Create Station

POST /api/v1/kitchen/stations

Request Body

{
  "location_id": "loc_123",
  "name": "Salad Station",
  "type": "salad",
  "assigned_categories": ["salads", "cold_appetizers"],
  "routing_rules": {
    "auto_route": true,
    "priority_boost": ["vip", "catering"]
  }
}

Update Station

PUT /api/v1/kitchen/stations/{station_id}

Ticket Management

Get Active Tickets

Retrieve tickets for a station.

GET /api/v1/kitchen/stations/{station_id}/tickets

Query Parameters

Parameter	Type	Description
`status`	string	`pending`, `in_progress`, `ready`, `bumped`
`priority`	string	`normal`, `rush`, `vip`

Response

{
  "data": [
    {
      "id": "ticket_001",
      "order_id": "ord_xyz",
      "order_number": "42",
      "order_type": "dine_in",
      "table_number": "T5",
      "server_name": "Maria",
      "status": "in_progress",
      "priority": "normal",
      "created_at": "2026-01-24T18:25:00Z",
      "elapsed_seconds": 180,
      "items": [
        {
          "id": "item_001",
          "name": "Ribeye Steak",
          "quantity": 1,
          "modifiers": ["Medium Rare", "No Mushrooms"],
          "special_instructions": "Allergy: shellfish",
          "status": "cooking",
          "seat_number": 1
        },
        {
          "id": "item_002",
          "name": "Grilled Salmon",
          "quantity": 1,
          "modifiers": ["Extra Lemon"],
          "status": "pending",
          "seat_number": 2
        }
      ],
      "fire_time": "2026-01-24T18:30:00Z",
      "warnings": []
    }
  ],
  "summary": {
    "total_tickets": 5,
    "pending": 2,
    "in_progress": 3,
    "avg_wait_seconds": 240
  }
}

Get All Kitchen Tickets

View all active tickets across all stations.

GET /api/v1/kitchen/tickets

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`view`	string	`all`, `expo`, `station`
`order_type`	string	`dine_in`, `takeout`, `delivery`

Update Ticket Status

Progress ticket through kitchen workflow.

PATCH /api/v1/kitchen/tickets/{ticket_id}/status

Request Body

{
  "status": "ready",
  "station_id": "station_grill"
}

Ticket Status Values

Status	Description
`pending`	Waiting to start
`in_progress`	Being prepared
`ready`	Ready at station
`bumped`	Sent to expo
`completed`	Order complete
`voided`	Cancelled

Bump Ticket

Mark ticket as complete at station (bump to next).

POST /api/v1/kitchen/tickets/{ticket_id}/bump

Request Body

{
  "station_id": "station_grill",
  "bump_to": "expo"
}

Recall Ticket

Bring back a bumped ticket.

POST /api/v1/kitchen/tickets/{ticket_id}/recall

Item-Level Operations

Update Item Status

Update individual item within a ticket.

PATCH /api/v1/kitchen/tickets/{ticket_id}/items/{item_id}

Request Body

{
  "status": "cooking"
}

Item Status Values

Status	Description
`pending`	Not started
`cooking`	Being prepared
`ready`	Item complete
`held`	On hold

Fire Item

Signal to start cooking an item.

POST /api/v1/kitchen/tickets/{ticket_id}/items/{item_id}/fire

Hold Item

Put item on hold.

POST /api/v1/kitchen/tickets/{ticket_id}/items/{item_id}/hold

Request Body

{
  "reason": "Waiting for rest of table",
  "release_time": "2026-01-24T18:35:00Z"
}

Expo Operations

Get Expo View

Retrieve consolidated expo view.

GET /api/v1/kitchen/expo

Response

{
  "tickets": [
    {
      "id": "ticket_001",
      "order_number": "42",
      "table_number": "T5",
      "status": "ready",
      "all_items_ready": true,
      "station_status": {
        "grill": "ready",
        "fry": "ready",
        "salad": "ready"
      },
      "ready_since": "2026-01-24T18:32:00Z",
      "server_notified": false
    }
  ],
  "runners_available": 2
}

Mark Complete

Expo marks order as complete and ready for service.

POST /api/v1/kitchen/expo/tickets/{ticket_id}/complete

Notify Server

Send notification that order is ready.

POST /api/v1/kitchen/expo/tickets/{ticket_id}/notify

Routing Rules

Get Routing Rules

GET /api/v1/kitchen/routing

Response

{
  "rules": [
    {
      "id": "rule_001",
      "name": "Grill Items",
      "conditions": {
        "categories": ["entrees", "burgers"],
        "tags": ["grilled"]
      },
      "route_to": "station_grill",
      "priority": 1
    },
    {
      "id": "rule_002",
      "name": "Rush Orders",
      "conditions": {
        "order_priority": "rush"
      },
      "route_to": "all_stations",
      "priority_boost": true
    }
  ]
}

Update Routing Rules

PUT /api/v1/kitchen/routing

Analytics

Get Kitchen Metrics

GET /api/v1/kitchen/analytics

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`start_time`	datetime	Analysis start
`end_time`	datetime	Analysis end

Response

{
  "period": {
    "start": "2026-01-24T11:00:00Z",
    "end": "2026-01-24T14:00:00Z"
  },
  "summary": {
    "total_tickets": 145,
    "avg_ticket_time_seconds": 420,
    "avg_item_time_seconds": 180,
    "longest_ticket_seconds": 960,
    "on_time_percentage": 94.5
  },
  "by_station": [
    {
      "station_id": "station_grill",
      "station_name": "Grill Station",
      "tickets_processed": 68,
      "avg_time_seconds": 480,
      "utilization_percent": 85
    },
    {
      "station_id": "station_fry",
      "station_name": "Fry Station",
      "tickets_processed": 92,
      "avg_time_seconds": 240,
      "utilization_percent": 72
    }
  ],
  "by_hour": [
    {"hour": 11, "tickets": 35, "avg_time": 380},
    {"hour": 12, "tickets": 62, "avg_time": 450},
    {"hour": 13, "tickets": 48, "avg_time": 420}
  ],
  "slowest_items": [
    {"item_name": "Ribeye Steak", "avg_time_seconds": 720, "count": 25},
    {"item_name": "BBQ Ribs", "avg_time_seconds": 600, "count": 18}
  ]
}

Device Registration

Register KDS Device

POST /api/v1/kitchen/devices

Request Body

{
  "location_id": "loc_123",
  "station_id": "station_grill",
  "device_name": "Grill KDS 1",
  "hardware_id": "device_serial_456"
}

Response

{
  "device_id": "kds_001",
  "device_token": "kdt_abc123...",
  "station_id": "station_grill",
  "registered_at": "2026-01-24T10:00:00Z"
}

WebSocket Events

Real-Time Updates

Connect to wss://api.olympuscloud.ai/ws/kitchen for real-time updates instead of polling the REST API. This significantly reduces latency and server load.

Events

Event	Description
`ticket.new`	New ticket received
`ticket.updated`	Ticket status changed
`ticket.bumped`	Ticket bumped to next station
`item.fired`	Item fired for cooking
`item.ready`	Item completed
`alert.slow_ticket`	Ticket exceeding time threshold

Webhooks

Event	Description
`kitchen.ticket_received`	New ticket routed to kitchen
`kitchen.ticket_complete`	Ticket marked complete
`kitchen.slow_alert`	Ticket exceeded threshold
`kitchen.station_backed_up`	Station queue threshold

Error Responses

Status	Code	Description
400	`invalid_status_transition`	Cannot transition to status
404	`ticket_not_found`	Ticket ID not found
404	`station_not_found`	Station ID not found
409	`ticket_already_complete`	Ticket already completed

KDS API - Kitchen display system
Orders API - Order management
KDS Expo - Expo station management

Overview​

Station Management​

List Stations​

Station Types​

Create Station​

Update Station​

Ticket Management​

Get Active Tickets​

Get All Kitchen Tickets​

Update Ticket Status​

Ticket Status Values​

Bump Ticket​

Recall Ticket​

Item-Level Operations​

Update Item Status​

Item Status Values​

Fire Item​

Hold Item​

Expo Operations​

Get Expo View​

Mark Complete​

Notify Server​

Routing Rules​

Get Routing Rules​

Update Routing Rules​

Analytics​

Get Kitchen Metrics​

Device Registration​

Register KDS Device​

WebSocket Events​

Events​

Webhooks​

Error Responses​

Related Documentation​

Overview

Station Management

List Stations

Station Types

Create Station

Update Station

Ticket Management

Get Active Tickets

Get All Kitchen Tickets

Update Ticket Status

Ticket Status Values

Bump Ticket

Recall Ticket

Item-Level Operations

Update Item Status

Item Status Values

Fire Item

Hold Item

Expo Operations

Get Expo View

Mark Complete

Notify Server

Routing Rules

Get Routing Rules

Update Routing Rules

Analytics

Get Kitchen Metrics

Device Registration

Register KDS Device

WebSocket Events

Events

Webhooks

Error Responses

Related Documentation