Consume Recommendations

Read recommendations and search from the AI Engine API. Point the UI at the API base (the same tunnel host, or http://localhost:8000 locally).

const API = "https://merely-matrix-naples-jews.trycloudflare.com"; // or http://localhost:8000

Recommendations

const res = await fetch(`${API}/api/recommend?user_id=${userId}&limit=10`);
const { result } = await res.json();
// result.strategy is "warm" or "cold"; result.filter echoes the filter you sent
result.items.forEach(it => {
  render({
    id: it.id,
    title: it.content?.title,
    score: it.relevance_score,
    why: it.breakdown            // {semantic: 0.41, tag: 0.33} -> explanation
  });
});

Response shape (the payload is wrapped in result):

{
  "result": {
    "user_id": "u1",
    "strategy": "warm",
    "filter": null,
    "items": [
      { "id": "842", "rank": 1, "relevance_score": 0.74, "role": "target",
        "breakdown": { "semantic": 0.41, "tag": 0.33 },
        "content": { "id": "842", "title": "...", "content_type": "text_item" } }
    ],
    "diagnostics": {}
  }
}

Each item carries a breakdown you can surface as a "why this" cue (see Explainability) and a role (target or distractor).

Query parameters

Param	Purpose
user_id	required, the visitor id
limit	cap the number of items (1 to 50)
filter	restrict candidates to a single tag, for example a location: filter=AiARLocationBarrack3
include_content	false returns a compact result (ids and scores only, no content)

// Filter recommendations to a location/tag
fetch(`${API}/api/recommend?user_id=${userId}&filter=AiARLocationBarrack3&limit=10`);

Test without events

POST /api/recommend/preview recommends from a hand-authored user model (tag affinity, liked items, demographics) without sending any events. Handy for trying the engine or for LLM evaluation. Same filter and include_content options apply.

Search and narrative

// Semantic search
const s = await (await fetch(`${API}/api/search?q=${encodeURIComponent(q)}`)).json();
s.result.forEach(item => render(item));   // item.score, item.highlight, item.title

// Geo search
fetch(`${API}/api/search/geo?lat=52.7579&lon=9.9048&radius_meters=2000`);

// Narrative from a set of items
fetch(`${API}/api/narrative`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ items: selectedItems })
});

Inspect the user model (debug)

fetch(`${API}/api/usermodel?user_id=${userId}`); // positives, negatives, tag_affinity, taste_vector

Full request/response detail with a try-it console: the interactive AI Engine API.

CORS

The API allows all origins by default (demo posture). For production, restrict it to your UI origin. See Cloud and production.