Authenticated API

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

Maximus AI API

Maximus is the AI-powered business assistant for Olympus Cloud, providing conversational access to analytics, operations, and business intelligence.

Overview

Attribute	Value
Base Path	`/api/v1/maximus`
Authentication	Bearer Token
Required Roles	JWT authentication required (no specific role restriction)

Chat

Send Message

Send a message to Maximus and receive an AI-powered response.

POST /api/v1/maximus/chat

Request Body

{
  "session_id": "sess_abc123",
  "message": "How were sales yesterday compared to last week?",
  "context": {
    "location_id": "loc_123",
    "user_role": "manager",
    "timezone": "America/New_York"
  },
  "options": {
    "include_charts": true,
    "include_recommendations": true,
    "response_format": "detailed"
  }
}

Response

{
  "session_id": "sess_abc123",
  "message_id": "msg_001",
  "response": {
    "text": "Yesterday's sales were **$8,542**, which is **12% higher** than the same day last week ($7,625).\n\n**Key highlights:**\n- Lunch revenue was up 18% ($3,200 vs $2,712)\n- Dinner was steady at +5% ($4,850 vs $4,620)\n- Average ticket size increased by $2.50\n\nThe increase was driven primarily by a busy lunch rush and higher appetizer attach rates.",
    "structured_data": {
      "type": "sales_comparison",
      "metrics": {
        "yesterday": {
          "total": 8542.00,
          "lunch": 3200.00,
          "dinner": 4850.00,
          "other": 492.00
        },
        "last_week": {
          "total": 7625.00,
          "lunch": 2712.00,
          "dinner": 4620.00,
          "other": 293.00
        },
        "change_percent": 12.0
      }
    },
    "visualizations": [
      {
        "type": "bar_chart",
        "title": "Sales Comparison",
        "data_url": "https://charts.example.com/sales_comparison_001.png"
      }
    ],
    "recommendations": [
      {
        "title": "Capitalize on lunch momentum",
        "description": "Consider promoting lunch specials to maintain the upward trend",
        "action_url": "/marketing/promotions/create"
      }
    ],
    "follow_up_questions": [
      "What items sold best at lunch?",
      "How does this week compare to last month?",
      "Show me the hourly breakdown"
    ]
  },
  "metadata": {
    "data_sources": ["analytics", "orders"],
    "query_time_ms": 450,
    "model": "claude-haiku-4.5",
    "confidence": 0.95
  }
}

Stream Response

Stream responses for real-time display.

POST /api/v1/maximus/chat/stream

Request Body

{
  "session_id": "sess_abc123",
  "message": "Give me a detailed analysis of this week's performance"
}

Response (Server-Sent Events)

event: start
data: {"message_id": "msg_002"}

event: token
data: {"token": "This"}

event: token
data: {"token": " week"}

event: token
data: {"token": "'s"}

...

event: complete
data: {"message_id": "msg_002", "metadata": {...}}

Capabilities

Get Available Capabilities

List what Maximus can help with.

GET /api/v1/maximus/capabilities

Response

{
  "capabilities": [
    {
      "category": "analytics",
      "name": "Sales Analysis",
      "description": "Ask about sales performance, trends, and comparisons",
      "examples": [
        "How were sales today?",
        "Compare this week to last week",
        "What's our best selling item?"
      ]
    },
    {
      "category": "analytics",
      "name": "Labor Analytics",
      "description": "Analyze labor costs, scheduling, and productivity",
      "examples": [
        "What's our labor cost percentage?",
        "Who worked overtime this week?",
        "How many hours were scheduled vs worked?"
      ]
    },
    {
      "category": "operations",
      "name": "Inventory Queries",
      "description": "Check inventory levels and usage",
      "examples": [
        "What items are running low?",
        "How much chicken did we use this week?",
        "When is our next delivery?"
      ]
    },
    {
      "category": "operations",
      "name": "Order Information",
      "description": "Look up orders and customer information",
      "examples": [
        "Find order #12345",
        "What orders are in progress?",
        "Show me today's large orders"
      ]
    },
    {
      "category": "insights",
      "name": "Business Recommendations",
      "description": "Get AI-powered suggestions for improvement",
      "examples": [
        "How can I improve lunch sales?",
        "What should I do about slow Tuesdays?",
        "Suggest menu optimizations"
      ]
    },
    {
      "category": "actions",
      "name": "Quick Actions",
      "description": "Perform common tasks through conversation",
      "examples": [
        "86 the salmon",
        "Send a message to the kitchen",
        "Schedule a staff meeting"
      ],
      "requires_confirmation": true
    }
  ]
}

Session Management

Create Session

Start a new conversation session.

POST /api/v1/maximus/sessions

Request Body

{
  "context": {
    "location_id": "loc_123",
    "user_id": "user_001",
    "interface": "web_portal"
  },
  "preferences": {
    "response_style": "concise",
    "include_charts": true
  }
}

Response

{
  "session_id": "sess_abc123",
  "created_at": "2026-01-24T19:30:00Z",
  "expires_at": "2026-01-24T21:30:00Z",
  "greeting": "Hi! I'm Maximus, your AI assistant. How can I help you today?"
}

Get Session History

GET /api/v1/maximus/sessions/{session_id}/history

Response

{
  "session_id": "sess_abc123",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "How were sales yesterday?",
      "timestamp": "2026-01-24T19:30:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Yesterday's sales were $8,542...",
      "timestamp": "2026-01-24T19:30:05Z",
      "metadata": {
        "data_sources": ["analytics"],
        "has_visualization": true
      }
    }
  ],
  "context": {
    "topics_discussed": ["sales", "comparisons"],
    "data_accessed": ["daily_sales", "weekly_comparison"]
  }
}

End Session

DELETE /api/v1/maximus/sessions/{session_id}

Quick Actions

Execute Action

Perform a quick action through Maximus.

POST /api/v1/maximus/actions

Request Body

{
  "session_id": "sess_abc123",
  "action": "86_item",
  "parameters": {
    "item_id": "menu_item_salmon",
    "reason": "sold_out",
    "duration": "end_of_day"
  },
  "confirmation": true
}

Response

{
  "action_id": "action_001",
  "status": "completed",
  "result": {
    "item": "Atlantic Salmon",
    "previous_status": "available",
    "new_status": "86d",
    "until": "2026-01-25T04:00:00Z"
  },
  "message": "Done! I've marked Atlantic Salmon as 86'd for the rest of the day. The kitchen and servers have been notified."
}

List Available Actions

GET /api/v1/maximus/actions

Response

{
  "actions": [
    {
      "id": "86_item",
      "name": "86 Menu Item",
      "description": "Mark an item as unavailable",
      "parameters": ["item_id", "reason", "duration"],
      "requires_confirmation": true,
      "required_permissions": ["menu:write"]
    },
    {
      "id": "send_message",
      "name": "Send Staff Message",
      "description": "Send a message to staff",
      "parameters": ["recipients", "message"],
      "requires_confirmation": false,
      "required_permissions": ["messages:write"]
    },
    {
      "id": "adjust_price",
      "name": "Adjust Item Price",
      "description": "Temporarily adjust a menu item price",
      "parameters": ["item_id", "new_price", "duration"],
      "requires_confirmation": true,
      "required_permissions": ["menu:write", "pricing:write"]
    }
  ]
}

Proactive Insights

Get Proactive Alerts

Get insights Maximus wants to share.

GET /api/v1/maximus/insights

Response

{
  "insights": [
    {
      "id": "insight_001",
      "type": "alert",
      "priority": "high",
      "title": "Unusual sales drop",
      "message": "Sales are 20% below normal for this time. The weather is clear, so this might be worth investigating.",
      "suggested_question": "Why might sales be down today?",
      "timestamp": "2026-01-24T14:30:00Z"
    },
    {
      "id": "insight_002",
      "type": "opportunity",
      "priority": "medium",
      "title": "Upsell opportunity",
      "message": "Appetizer attach rate is only 15% today. Consider having servers mention the daily special.",
      "suggested_action": {
        "action": "send_message",
        "message": "Reminder: Don't forget to mention today's appetizer special!"
      }
    }
  ]
}

Personalization

Get Preferences

GET /api/v1/maximus/preferences

Response

{
  "user_id": "user_001",
  "preferences": {
    "response_style": "detailed",
    "default_comparisons": "last_week",
    "include_charts": true,
    "proactive_insights": true,
    "preferred_metrics": ["sales", "labor_cost", "ticket_average"],
    "notification_channels": ["web", "mobile"]
  },
  "learned_preferences": {
    "frequently_asked": ["daily_sales", "labor_percentage"],
    "preferred_time_ranges": ["today", "this_week"],
    "common_filters": ["location:loc_123"]
  }
}

Update Preferences

PUT /api/v1/maximus/preferences

Request Body

{
  "response_style": "concise",
  "include_charts": false,
  "proactive_insights": true
}

Feedback

Submit Feedback

Rate a response for continuous improvement.

POST /api/v1/maximus/feedback

Request Body

{
  "message_id": "msg_001",
  "rating": "helpful",
  "feedback_type": "accuracy",
  "comment": "The data was accurate but I'd like more detail on the lunch breakdown"
}

Rating Values

Rating	Description
`helpful`	Response was useful
`not_helpful`	Response wasn't useful
`incorrect`	Data or information was wrong
`incomplete`	Missing important information

Webhooks

Event	Description
`maximus.insight_generated`	New proactive insight
`maximus.action_executed`	Quick action completed
`maximus.session_started`	New session created

Error Responses

Status	Code	Description
400	`invalid_query`	Query couldn't be understood
403	`insufficient_permissions`	User lacks data access
404	`session_not_found`	Session expired or invalid
429	`rate_limit_exceeded`	Too many requests
503	`ai_unavailable`	AI service temporarily unavailable

LangGraph Agents - Agent workflows
AI Insights - Business insights
Analytics API - Raw analytics data

Overview​

Chat​

Send Message​

Stream Response​

Capabilities​

Get Available Capabilities​

Session Management​

Create Session​

Get Session History​

End Session​

Quick Actions​

Execute Action​

List Available Actions​

Proactive Insights​

Get Proactive Alerts​

Personalization​

Get Preferences​

Update Preferences​

Feedback​

Submit Feedback​

Rating Values​

Webhooks​

Error Responses​

Related Documentation​

Overview

Chat

Send Message

Stream Response

Capabilities

Get Available Capabilities

Session Management

Create Session

Get Session History

End Session

Quick Actions

Execute Action

List Available Actions

Proactive Insights

Get Proactive Alerts

Personalization

Get Preferences

Update Preferences

Feedback

Submit Feedback

Rating Values

Webhooks

Error Responses

Related Documentation