Shop Lightbeam AI Agent API

Voice assistants, chatbots, and AI agents can order delivery through natural language

Overview

Shop Lightbeam provides an AI-friendly API that allows any AI system to browse local vendors, search products, and place orders on behalf of users. Perfect for voice assistants, chatbots, and autonomous agents.

Fast Integration

Simple JSON API with structured responses

Secure

API key authentication per user

Well Documented

Clear schemas and examples

Authentication

All requests require an API key

POST https://shop-lightbeam.com/api/ai
Headers:
  x-api-key: sk_your_api_key_here
  Content-Type: application/json

Users can generate API keys from their account dashboard. Each key is tied to a specific user account.

Available Actions

Search Vendors & Products

Find local vendors by name, category, or cuisine type.

{
  "action": "search",
  "query": "pizza",
  "location": "Toronto"
}

Response:

{
  "success": true,
  "results": [
    {
      "vendor_id": "v123",
      "name": "Tony's Pizza",
      "category": "restaurant",
      "is_open": true,
      "page_url": "https://shop-lightbeam.com/vendor?id=v123"
    }
  ]
}

get_vendor_menu

Get Vendor Menu

Retrieve full menu/catalog with items and pricing.

{
  "action": "get_vendor_menu",
  "vendor_id": "v123"
}

place_order

Place Order

Create an order (returns payment URL for user to complete).

{
  "action": "place_order",
  "vendor_id": "v123",
  "items": [
    {"item_id": "i456", "quantity": 2}
  ],
  "delivery_address": "123 Main St, Toronto, ON M5V 1A1",
  "customer_name": "John Doe",
  "customer_phone": "+14165551234",
  "special_instructions": "Ring doorbell twice"
}

Response:

{
  "success": true,
  "order_id": "ord789",
  "total_amount": 45.99,
  "payment_url": "https://shop-lightbeam.com/checkout?temp_order_id=ord789",
  "note": "Order confirmed after payment"
}

get_order_status

Check Order Status

Get real-time order status and tracking.

{
  "action": "get_order_status",
  "order_id": "ord789"
}

help

Get API Documentation

Returns full API documentation with all actions and parameters.

{"action": "help"}

Example: Voice Assistant Flow

User:

"Order me a large pepperoni pizza"

AI Agent → API:

{"action": "search", "query": "pizza"}

AI Agent → API:

{"action": "get_vendor_menu", "vendor_id": "v123"}

AI Agent:

"I found Tony's Pizza. A large pepperoni costs $18.99. Shall I place the order?"

User:

"Yes, deliver to my home"

AI Agent → API:

{"action": "place_order", ...}

AI Agent:

"Order placed! Check your phone for a payment link. Your pizza will arrive in 30 minutes."

Error Handling

All errors return clear messages with hints:

{
  "success": false,
  "error": "Missing required field: delivery_address",
  "hint": "Use action: 'help' to see API documentation"
}

Rate Limits & Best Practices

No rate limits currently - fair use policy applies
Cache vendor menus when possible to reduce API calls
Orders require user action for payment completion
Keep API keys secure - never expose in client-side code