Skip to main content
The Kitchen API provides endpoints specifically designed for kitchen display systems (KDS). It allows kitchen staff to view active orders and update item preparation status in real-time.

​
Overview

Kitchen displays show orders that need to be prepared and allow staff to mark items as they progress through preparation. The system uses WebSocket connections for real-time updates, ensuring all displays stay synchronized.

​
Authentication

All endpoints require authentication using a Bearer token: 
Authorization: Bearer YOUR_ACCESS_TOKEN

​
Permissions

Kitchen staff need the following permissions:
  • orders:read - View active orders
  • orders:update_item_status - Update individual item status

​
Base URL

https://api.restai.com/api/kitchen

​
Endpoints

​
GET /orders

Retrieve active orders for the kitchen display. By default, returns orders in pending, confirmed, preparing, and ready statuses. 
curl -X GET "https://api.restai.com/api/kitchen/orders?status=preparing" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Query Parameters

​
status
string
Filter by specific status. Options: pending, confirmed, preparing, readyIf omitted, returns orders with any active status.

​
Response

​
success
boolean
Indicates if the request was successful
​
data
array
Array of orders with their items

​
Example Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "order_number": "ORD-00042",
      "type": "dine_in",
      "status": "preparing",
      "customer_name": "John Doe",
      "notes": "Extra napkins please",
      "created_at": "2024-01-15T14:30:00.000Z",
      "items": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "name": "Cheeseburger",
          "quantity": 2,
          "status": "preparing",
          "notes": "No onions"
        },
        {
          "id": "770e8400-e29b-41d4-a716-446655440002",
          "name": "French Fries",
          "quantity": 1,
          "status": "pending",
          "notes": null
        }
      ]
    }
  ]
}

​
PATCH /items/:id/status

Update the preparation status of a specific order item. This is the primary action for kitchen staff as items move through preparation. 
curl -X PATCH https://api.restai.com/api/kitchen/items/660e8400-e29b-41d4-a716-446655440001/status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ready"
  }'

​
Path Parameters

​
id
string
required
UUID of the order item to update

​
Request Body

​
status
string
required
New item status. Must be a valid transition.Options: pending, preparing, ready, served

​
Item Status Workflow

Current StatusAllowed Next Status
pendingpreparing
preparingready
readyserved
served(terminal state)
Kitchen staff typically only move items from pending → preparing → ready. Waiters mark items as served.

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
The updated order item

​
Example Response

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "menu_item_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Cheeseburger",
    "unit_price": 1200,
    "quantity": 2,
    "total": 2400,
    "notes": "No onions",
    "status": "ready"
  }
}

​
Real-Time Updates with WebSocket

Kitchen displays should connect to the WebSocket server to receive real-time updates when orders are created or modified.

​
WebSocket Connection

const ws = new WebSocket('wss://api.restai.com/ws');

// Authenticate
ws.send(JSON.stringify({
  type: 'auth',
  token: 'YOUR_ACCESS_TOKEN'
}));

// Subscribe to kitchen channel
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'branch:YOUR_BRANCH_ID:kitchen'
}));

// Listen for events
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  handleKitchenEvent(data);
};

​
WebSocket Events

Kitchen displays receive events on the branch:{branchId}:kitchen channel:

​
order:new

Broadcast when a new order is created. 
{
  "type": "order:new",
  "payload": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-00042",
    "status": "pending",
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "name": "Cheeseburger",
        "quantity": 2,
        "status": "pending",
        "notes": "No onions"
      }
    ]
  },
  "timestamp": 1705330200000
}

​
order:updated

Broadcast when an order’s status changes. 
{
  "type": "order:updated",
  "payload": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-00042",
    "status": "preparing"
  },
  "timestamp": 1705330500000
}

​
order:item_status

Broadcast when an individual item’s status changes. 
{
  "type": "order:item_status",
  "payload": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-00042",
    "item": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Cheeseburger",
      "quantity": 2,
      "status": "ready"
    }
  },
  "timestamp": 1705330800000
}

​
WebSocket Channels

Different channels receive different event scopes:
ChannelScopeUse Case
branch:{branchId}All branch eventsStaff dashboards, order management
branch:{branchId}:kitchenKitchen-relevant eventsKitchen Display Systems (KDS)
session:{sessionId}Customer session eventsCustomer mobile apps
Kitchen displays should subscribe to the branch:{branchId}:kitchen channel to receive only relevant updates.

​
Best Practices

Polling Fallback

While WebSocket provides real-time updates, implement periodic polling of GET /orders as a fallback in case of connection issues.

Sound Alerts

Play notification sounds when order:new events arrive to alert kitchen staff.

Visual Timers

Display elapsed time since order creation to help prioritize older orders.

Status Colors

Use color coding for different item statuses (pending=gray, preparing=yellow, ready=green).

​
Notes

Item status transitions are strictly enforced. Kitchen staff cannot skip steps (e.g., cannot go directly from pending to ready).
For optimal kitchen efficiency, group items by preparation station and display them on separate screens or sections.

Build docs developers (and LLMs) love

Get started for freeTalk to us