API REFERENCE

REST API Reference

Sessions, Shades, and Analytics — the three core resource groups of the LumeCore REST API.

REST API Reference

Base URL: https://api.lumeglint.com/v1

Authentication: All requests require Authorization: Bearer lmg_live_YOUR_KEY header.

Content-Type: application/json for all request and response bodies.

Sessions

A session represents a single shopper's try-on interaction on a product page.

POST /sessions

Create a new try-on session for a product page. Returns a session token used by the JS SDK.

Request JSON
{ "product_id": "prod_matte_rose_06", "catalog_id": "cat_lipstick_2025", "locale": "en-US" }
Response 200 JSON
{ "session_id": "ses_1a2b3c4d", "token": "lmg_token_xyz...", "expires_at": "2025-09-01T15:22:09Z", "shade_count": 24 }

GET /sessions/{id}

Retrieve a session with its full shade interaction history.

Shades

Shades are the product color entries in a catalog. Each shade has a HEX value, finish type, and optional metadata.

GET /shades?catalog_id={id}

List all shades in a catalog.

POST /shades

Create a shade or batch-import shades (up to 500 per request).

Batch import request JSON
{ "catalog_id": "cat_lipstick_2025", "shades": [ { "sku": "LIP-001", "name": "Rose Crimson", "hex": "#B8245C", "finish": "matte" } ] }

Analytics

GET /analytics/sessions

Returns aggregate try-on stats. Query params: start_date, end_date, product_id (optional).

Response 200 JSON
{ "period": "2025-08-01 / 2025-09-01", "total_sessions": 1842, "avg_shades_per_session": 3.7, "cart_intent_rate": 0.34, "top_shades": [ { "sku": "LIP-001", "selections": 421 }, { "sku": "LIP-003", "selections": 384 } ] }

Error codes

  • 401 — Invalid or missing API key
  • 404 — Resource not found (catalog, session, shade)
  • 429 — Rate limit exceeded (1,000 req/min)
  • 402 — Session quota exceeded for your plan