Best practices & FAQ
Recommendations to get better search results with XEYE and answers to the most frequent questions.
Writing good elements
Write texts the way your users search, not the way your database names things.
Give every element a description with synonyms and context — it is the cheapest semantic boost available.
Test with real user queries: a typo and a synonym tell you more than a perfect match.
Working efficiently
Import in bulk, edit in batches, train once at the end.
Test in the console Search page first; integrate via API when results look right.
Try two or three embedding models on real queries before choosing the one in use.
Security
Treat API keys like passwords: server-side only, one per integration, delete unused ones.
Keep lists private until they are ready to be exposed through the API.
Deleting a list, a key or your account is permanent — there is no undo.
Frequently asked questions
Why does my list return nothing through the API?
Check three things: the list is public, the key is valid, and list_name matches the list name exactly. Private lists are only searchable from the console.
Does editing elements break search?
No. Searches keep using the last training in use. Elements added after that training match by text only until you retrain; deleted elements stop appearing immediately.
How often should I retrain?
Whenever the content has changed enough to matter — after adding a batch of elements or rewriting texts and descriptions. There is no need to retrain after every small edit.
Which embedding model should I pick?
Start with the default one. If results miss nuance, train with a larger model and compare using the same queries from the Search page; keep whichever wins as "in use".
Can I search private lists from my app?
No. The public API only serves public lists. The console can search all your lists, which is useful while preparing a list before making it public.
What happens if I delete an API key?
Every integration using it stops working immediately with a 401 error. Create the new key first, switch your integrations over, then delete the old one.