Skip to main content
Authenticated API

Voice AI endpoints require a valid JWT Bearer token with staff roles. Accessible via the API gateway at /v1/voice-ai/* and /v1/speech/*.

Voice Sessions

Manage the full lifecycle of a voice ordering session -- from start to completion.

Base Path: /api/v1/voice/sessions

Start Voice Session​

Request​

POST /api/v1/voice/sessions
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "location_id": "loc-xyz789",
  "channel": "drive_thru",
  "lane": 1,
  "language": "en-US"
}

Response​

{
  "session_id": "voice-sess-abc123",
  "status": "active",
  "cart": {
    "items": [],
    "subtotal": 0.00
  },
  "greeting": {
    "text": "Welcome to Acme Burgers! What can I get for you today?",
    "audio_url": "https://audio.olympuscloud.ai/tts/abc123.mp3"
  },
  "created_at": "2026-01-18T14:30:00Z"
}

Process Utterance​

Send customer speech for processing.

Request​

POST /api/v1/voice/sessions/{session_id}/utterance
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "audio_base64": "UklGRiQAAABXQVZFZm10IBAAAA...",
  "format": "wav",
  "sample_rate": 16000
}

Or with text (for testing):

{
  "text": "I'd like a large pepperoni pizza with extra cheese"
}

Response​

{
  "session_id": "voice-sess-abc123",
  "utterance_id": "utt-001",
  "transcript": "I'd like a large pepperoni pizza with extra cheese",
  "confidence": 0.95,
  "intent": {
    "name": "add_item",
    "confidence": 0.92
  },
  "entities": [
    {
      "type": "item",
      "value": "pepperoni pizza",
      "item_id": "item-pepperoni",
      "confidence": 0.94
    },
    {
      "type": "size",
      "value": "large",
      "modifier_id": "mod-large",
      "confidence": 0.98
    },
    {
      "type": "modifier",
      "value": "extra cheese",
      "modifier_id": "mod-extra-cheese",
      "confidence": 0.91
    }
  ],
  "cart_update": {
    "action": "add",
    "item": {
      "id": "line-001",
      "name": "Pepperoni Pizza",
      "size": "Large",
      "modifiers": ["Extra Cheese"],
      "price": 18.99,
      "quantity": 1
    }
  },
  "cart": {
    "items": [
      {
        "id": "line-001",
        "name": "Large Pepperoni Pizza",
        "modifiers": ["Extra Cheese"],
        "price": 18.99,
        "quantity": 1
      }
    ],
    "subtotal": 18.99
  },
  "response": {
    "text": "Got it! I've added a large pepperoni pizza with extra cheese. That's $18.99. Would you like anything else?",
    "audio_url": "https://audio.olympuscloud.ai/tts/utt-001.mp3"
  },
  "requires_clarification": false
}

Get Session State​

Request​

GET /api/v1/voice/sessions/{session_id}
Authorization: Bearer {access_token}

Response​

{
  "session_id": "voice-sess-abc123",
  "status": "active",
  "location_id": "loc-xyz789",
  "channel": "drive_thru",
  "cart": {
    "items": [
      {
        "id": "line-001",
        "name": "Large Pepperoni Pizza",
        "modifiers": ["Extra Cheese"],
        "price": 18.99,
        "quantity": 1
      }
    ],
    "subtotal": 18.99
  },
  "conversation": [
    {
      "role": "assistant",
      "text": "Welcome to Acme Burgers! What can I get for you today?",
      "timestamp": "2026-01-18T14:30:00Z"
    },
    {
      "role": "customer",
      "text": "I'd like a large pepperoni pizza with extra cheese",
      "timestamp": "2026-01-18T14:30:15Z"
    },
    {
      "role": "assistant",
      "text": "Got it! I've added a large pepperoni pizza with extra cheese. Would you like anything else?",
      "timestamp": "2026-01-18T14:30:17Z"
    }
  ],
  "started_at": "2026-01-18T14:30:00Z",
  "last_activity": "2026-01-18T14:30:17Z"
}

Cancel Session​

Request​

POST /api/v1/voice/sessions/{session_id}/cancel
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "reason": "customer_request"
}

Handle Clarification​

When the system needs clarification:

Clarification Response​

{
  "response": {
    "text": "I found a few options for chicken. Did you mean the Chicken Sandwich, Chicken Wings, or Chicken Salad?",
    "audio_url": "https://audio.olympuscloud.ai/tts/clarify-001.mp3"
  },
  "requires_clarification": true,
  "clarification": {
    "type": "item_selection",
    "options": [
      {"id": "item-sandwich", "name": "Chicken Sandwich", "price": 10.99},
      {"id": "item-wings", "name": "Chicken Wings", "price": 12.99},
      {"id": "item-salad", "name": "Chicken Salad", "price": 11.99}
    ]
  }
}

Customer Clarifies​

{
  "text": "The sandwich"
}

Resolved Response​

{
  "intent": {
    "name": "clarification",
    "resolved_to": "item-sandwich"
  },
  "cart_update": {
    "action": "add",
    "item": {
      "id": "line-002",
      "name": "Chicken Sandwich",
      "price": 10.99
    }
  },
  "response": {
    "text": "Perfect, one chicken sandwich. Anything else?",
    "audio_url": "https://audio.olympuscloud.ai/tts/utt-002.mp3"
  }
}

Complete Order​

Request​

POST /api/v1/voice/sessions/{session_id}/complete
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "order_type": "drive_thru",
  "payment_at_window": true
}

Response​

{
  "session_id": "voice-sess-abc123",
  "order": {
    "id": "order-12345",
    "number": "1234",
    "items": [
      {
        "name": "Large Pepperoni Pizza",
        "modifiers": ["Extra Cheese"],
        "price": 18.99
      },
      {
        "name": "Chicken Sandwich",
        "price": 10.99
      }
    ],
    "subtotal": 29.98,
    "tax": 2.62,
    "total": 32.60
  },
  "response": {
    "text": "Your total is $32.60. Please pull forward to the window. Thank you!",
    "audio_url": "https://audio.olympuscloud.ai/tts/complete-001.mp3"
  },
  "session_duration_seconds": 145,
  "completed_at": "2026-01-18T14:32:25Z"
}