API Reference

KLEO Chat exposes a RESTful API for store management and integration.

Base URL

Production: https://teflon-kleobot.onrender.com

Authentication

API requests require store authentication via query parameter or header:

# Query parameter
GET /api/products?storeId=mystore.myshopify.com

# Or header
GET /api/products
X-Store-Id: mystore.myshopify.com

Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "architecture": "SOLID",
  "timestamp": "2026-02-04T10:00:00.000Z"
}

---

Store Configuration

Get Store Config

GET /api/store-config/:storeId

Response:

{
  "success": true,
  "config": {
    "storeId": "mystore.myshopify.com",
    "services": {
      "telegram": {
        "botUsername": "mystorebot",
        "isActive": true,
        "webhookConfigured": true
      },
      "ai": {
        "enabled": true,
        "personality": "friendly"
      }
    }
  }
}

Save Telegram Token

POST /api/store-config/:storeId/telegram
Content-Type: application/json

{
  "botToken": "123456:ABC-DEF..."
}

Response:

{
  "success": true,
  "message": "Telegram bot configured and webhook registered",
  "botUsername": "mystorebot"
}

---

Products

Search Products

GET /api/products/search?storeId=:storeId&q=:query

Parameters:

Name	Type	Description
storeId	string	Shopify store domain
q	string	Search query
limit	number	Max results (default: 10)

Response:

{
  "success": true,
  "products": [
    {
      "id": "gid://shopify/Product/123",
      "title": "Red Running Shoes",
      "description": "Comfortable running shoes...",
      "price": "89.99",
      "currency": "EUR",
      "images": ["https://..."],
      "variants": [...]
    }
  ]
}

Get Product by ID

GET /api/products/:productId?storeId=:storeId

---

Webhooks

Telegram Webhook

POST /telegram/webhook/:storeId

Receives updates from Telegram Bot API. Configured automatically when merchant saves bot token.

Shopify Order Webhook

POST /webhooks/shopify/orders
X-Shopify-Hmac-SHA256: {signature}
X-Shopify-Shop-Domain: {shop}

Receives order notifications from Shopify.

---

Dashboard

Serve Dashboard

GET /shopify-app/

Embedded merchant dashboard (Polaris-based).

---

Error Responses

All errors follow this format:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

Code	HTTP Status	Description
STORE_NOT_FOUND	404	Store doesn't exist
INVALID_TOKEN	400	Bot token is invalid
UNAUTHORIZED	401	Missing authentication
RATE_LIMITED	429	Too many requests

Rate Limits

Endpoint	Limit
/api/*	100 req/min per store
/telegram/webhook/*	Unlimited (Telegram traffic)
/health	Unlimited

SDKs

Coming soon:

• JavaScript/TypeScript SDK
• Python SDK