API Reference

Base URL

Every endpoint shares one base URL; all paths are versioned under /v1.

API keys

Keys are generated from the Developer Access tab in your dashboard. Every request requires an X-API-KEY header with no Bearer prefix.

Using a secret key on a publishable endpoint (or vice versa) returns 403 Forbidden. See API keys for rotation instructions.

Headers

Ingestion endpoints

All ingestion endpoints return 202 Accepted and use the same response envelope: { success, message, data: { accepted }, error }.

POST /v1/ingest/items/upsert

Load your catalog before anything else; Lehnz can only recommend items it knows about. Re-call whenever items change. To hide or remove an item, upsert it with status: inactive or deleted rather than omitting it.

Auth: Secret key (server-side only). Worked example: Load your catalog.

{
  "success": true,
  "message": "items accepted",
  "data": { "accepted": 1 },
  "error": null
}

POST /v1/ingest/users/upsert

Load your users so recommendations can be personalised to them. Re-call when a profile changes or a user deactivates. Set status: inactive or deleted to preserve event history for analytics.

Auth: Secret key (server-side only). Worked example: Load your catalog.

{
  "success": true,
  "message": "users accepted",
  "data": { "accepted": 1 },
  "error": null
}

POST /v1/ingest/events/ingest

Stream every meaningful interaction so Lehnz learns in real time. Accepts a single event object or an array. When an interaction came from a recommendation, include recommendation_id to close the attribution loop.

Auth: Publishable key (browser-safe). Worked examples: Tracking Events.

{
  "success": true,
  "message": "events accepted",
  "data": { "accepted": 1 },
  "error": null
}

Recommendations

One endpoint, many strategies. POST /v1/recommend serves every use case; the strategy field picks the algorithm.

POST /v1/recommend

Auth: Publishable key (browser-safe). See Recommendations for the full strategy list, when to use each, and worked examples.

{
  "success": true,
  "message": "Success",
  "data": {
    "recommendation_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "glow-beauty-ng",
    "domain": "commerce",
    "strategy": "personalized",
    "mode": "behavioral",
    "results": [
      { "item_id": "prod_7", "score": 0.985, "reason": "behavioral_match", "metadata": { "brand": "Sony" } }
    ],
    "recommended_items": ["prod_7", "prod_3", "prod_22"],
    "pagination": { "page": 1, "limit": 20, "total_count": 48, "has_next": true },
    "latency_ms": 42.5
  },
  "error": null
}

Response envelope

All responses share the same structure:

{ "success": true, "message": "...", "data": { } }

{ "success": false, "message": "Human-readable error", "error": "Detail" }

HTTP status codes

202 Accepted means the payload entered the processing queue, not that it has been persisted. Events are typically available within seconds. See Errors & status codes for the full message catalog.

Rate limits

1,000 requests per 15 minutes per organisation, shared across all API keys. Auth endpoints (/auth/register, /auth/login) are capped at 10 requests per 15 minutes per IP. Batch multiple events into a single array to stay efficient.

On 429, retry with exponential backoff; the RateLimit-Reset header tells you when to try again. See Retries & rate limits for the full pattern.