Authenticated API

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

Drive-Thru API

Manage drive-thru lanes, voice AI ordering, vehicle tracking, and order flow.

Authentication Required

All endpoints require a valid Bearer token. See Authentication for details.

Overview

Attribute	Value
Base Path	`/api/v1/drive-thru`
Authentication	Bearer Token
Required Roles	`pos_staff`, `drive_thru_staff`, `server`, `kitchen`, `manager`, `restaurant_staff`, `restaurant_manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Lane Management

Get Lane Status

Retrieve current status of all drive-thru lanes.

GET /api/v1/drive-thru/lanes

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location

Response

{
  "location_id": "loc_123",
  "lanes": [
    {
      "id": "lane_1",
      "name": "Lane 1",
      "status": "active",
      "current_vehicle": {
        "id": "veh_abc",
        "position": "speaker",
        "order_id": "ord_xyz",
        "wait_time_seconds": 45
      },
      "queue_length": 3,
      "avg_service_time_seconds": 180
    },
    {
      "id": "lane_2",
      "name": "Lane 2",
      "status": "active",
      "current_vehicle": null,
      "queue_length": 0
    }
  ],
  "metrics": {
    "total_in_queue": 5,
    "avg_wait_time_seconds": 120,
    "throughput_per_hour": 45
  }
}

Lane Status Values

Status	Description
`active`	Lane is open
`closed`	Lane is closed
`maintenance`	Under maintenance
`voice_ai_only`	Voice AI mode only

Update Lane Status

Open or close a lane.

PATCH /api/v1/drive-thru/lanes/{lane_id}/status

Request Body

{
  "status": "closed",
  "reason": "Scheduled maintenance"
}

Vehicle Tracking

Track Vehicle Entry

POST /api/v1/drive-thru/vehicles

Request Body

{
  "lane_id": "lane_1",
  "license_plate": "ABC123",
  "vehicle_type": "sedan",
  "detected_at": "2026-01-24T18:30:00Z"
}

Response

{
  "id": "veh_abc",
  "lane_id": "lane_1",
  "position": "entry",
  "status": "waiting",
  "created_at": "2026-01-24T18:30:00Z"
}

Position Values

Position	Description
`entry`	Just entered lane
`menu_board`	At menu board
`speaker`	At order speaker
`payment`	At payment window
`pickup`	At pickup window
`exit`	Exiting lane

Update Vehicle Position

Update vehicle position in lane.

PATCH /api/v1/drive-thru/vehicles/{vehicle_id}/position

Request Body

{
  "position": "speaker",
  "timestamp": "2026-01-24T18:31:00Z"
}

Link Order to Vehicle

Associate an order with a vehicle.

POST /api/v1/drive-thru/vehicles/{vehicle_id}/order

Request Body

{
  "order_id": "ord_xyz"
}

Voice AI

Voice AI Completion Rate

The Voice AI system typically achieves 80%+ completion rates for drive-thru orders. Use the handoff endpoint to gracefully transfer to a human operator when the AI confidence is low.

Start Voice Session

Initiate voice AI ordering session.

POST /api/v1/drive-thru/voice/sessions

Request Body

{
  "lane_id": "lane_1",
  "vehicle_id": "veh_abc",
  "audio_stream_url": "wss://..."
}

Response

{
  "session_id": "voice_001",
  "status": "active",
  "greeting_played": true,
  "ai_model": "drive-thru-v3",
  "websocket_url": "wss://voice.olympuscloud.ai/sessions/voice_001"
}

Get Voice Session

Retrieve voice session details and transcript.

GET /api/v1/drive-thru/voice/sessions/{session_id}

Response

{
  "session_id": "voice_001",
  "status": "completed",
  "vehicle_id": "veh_abc",
  "order_id": "ord_xyz",
  "duration_seconds": 95,
  "transcript": [
    {
      "speaker": "ai",
      "text": "Welcome to Restaurant Revolution! What can I get for you today?",
      "timestamp": 0
    },
    {
      "speaker": "customer",
      "text": "I'll have a number 3 combo with a Coke",
      "timestamp": 3.5,
      "confidence": 0.94
    },
    {
      "speaker": "ai",
      "text": "A number 3 combo with a Coke. Would you like to make that a large?",
      "timestamp": 6.2
    }
  ],
  "items_recognized": [
    {"item": "Combo #3", "confidence": 0.96},
    {"item": "Coca-Cola", "confidence": 0.92}
  ],
  "handoff_to_human": false
}

Handoff to Human

Transfer voice session to human operator.

POST /api/v1/drive-thru/voice/sessions/{session_id}/handoff

Request Body

{
  "reason": "customer_request",
  "notes": "Customer asked to speak to a person"
}

Order Queue

Get Order Queue

View orders in the drive-thru queue.

GET /api/v1/drive-thru/queue

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`lane_id`	string	Specific lane

Response

{
  "data": [
    {
      "order_id": "ord_001",
      "vehicle_id": "veh_abc",
      "lane_id": "lane_1",
      "position": "payment",
      "order_number": "DT-042",
      "items_count": 3,
      "total": 15.99,
      "status": "ready",
      "wait_time_seconds": 180,
      "promised_time": "2026-01-24T18:35:00Z"
    }
  ]
}

Analytics

Get Lane Analytics

Retrieve drive-thru performance metrics.

GET /api/v1/drive-thru/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"
  },
  "metrics": {
    "total_orders": 89,
    "avg_service_time_seconds": 185,
    "avg_order_time_seconds": 65,
    "avg_total_time_seconds": 250,
    "throughput_per_hour": 29.7,
    "peak_queue_length": 8,
    "voice_ai_completion_rate": 0.82,
    "handoff_rate": 0.18
  },
  "by_hour": [
    {"hour": 11, "orders": 25, "avg_time": 195},
    {"hour": 12, "orders": 42, "avg_time": 210},
    {"hour": 13, "orders": 22, "avg_time": 165}
  ],
  "voice_ai_stats": {
    "sessions": 89,
    "completed_by_ai": 73,
    "handed_off": 16,
    "avg_confidence": 0.91
  }
}

Push content to digital menu boards.

POST /api/v1/drive-thru/menu-boards/{board_id}/content

Request Body

{
  "template": "lunch_specials",
  "items": [
    {
      "position": 1,
      "item_id": "item_123",
      "highlighted": true
    }
  ],
  "promotions": [
    {
      "text": "Try our new spicy chicken!",
      "image_url": "https://..."
    }
  ]
}

Webhooks

Event	Description
`drive-thru.vehicle_entered`	Vehicle detected
`drive-thru.order_placed`	Order submitted
`drive-thru.order_ready`	Order ready at window
`drive-thru.vehicle_exited`	Vehicle left
`drive-thru.voice_handoff`	AI handed to human
`drive-thru.queue_alert`	Queue threshold exceeded

Error Responses

Status	Code	Description
400	`lane_closed`	Lane is not active
400	`no_active_session`	No voice session
404	`vehicle_not_found`	Vehicle ID not found
409	`vehicle_already_linked`	Vehicle has order

Voice AI Drive-Thru - Drive-thru voice AI
Voice AI Guide - Voice AI API
Orders API - Order management

Drive-Thru API

Overview

Lane Management

Get Lane Status

Lane Status Values

Update Lane Status

Vehicle Tracking

Track Vehicle Entry

Position Values

Update Vehicle Position

Link Order to Vehicle

Voice AI

Start Voice Session

Get Voice Session

Handoff to Human

Order Queue

Get Order Queue

Analytics

Get Lane Analytics

Digital Menu Board

Update Menu Board

Webhooks

Error Responses

Overview​

Lane Management​

Get Lane Status​

Lane Status Values​

Update Lane Status​

Vehicle Tracking​

Track Vehicle Entry​

Position Values​

Update Vehicle Position​

Link Order to Vehicle​

Voice AI​

Start Voice Session​

Get Voice Session​

Handoff to Human​

Order Queue​

Get Order Queue​

Analytics​

Get Lane Analytics​

Digital Menu Board​

Update Menu Board​

Webhooks​

Error Responses​

Related Documentation​

Overview

Lane Management

Get Lane Status

Lane Status Values

Update Lane Status

Vehicle Tracking

Track Vehicle Entry

Position Values

Update Vehicle Position

Link Order to Vehicle

Voice AI

Start Voice Session

Get Voice Session

Handoff to Human

Order Queue

Get Order Queue

Analytics

Get Lane Analytics

Digital Menu Board

Update Menu Board

Webhooks

Error Responses

Related Documentation