Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

Discovery skill rather than search: given only a location, surface products and stores worth the user’s attention right now.

​
When to use

  • User asks “what’s around me?” or “anything interesting nearby?”
  • Ambient context (weather, time of day, user history) suggests discovery rather than targeted search.
  • Agent is filling slow time — e.g. user is waiting at a bus stop — and wants to show something local.

​
Inputs to gather

  • latitude, longitude — required
  • radius_km — default 2 (hyperlocal; tighter than regular search)
  • Optional: category hint (“food”, “home goods”), time window

​
Flow

​
1. Pull nearby stores

GET /locations/api/v1/nearby?lat=...&lon=...&radius_km=2
Returns stores with geo distance, categories, and last-updated inventory timestamps.

​
2. Prioritize

Score each store by a few signals (all optional; use what’s available):
  • Local-independent (not a national chain) — bonus
  • Recently updated inventory (last_inventory_sync < 1d) — bonus
  • New products added this week — via offer created timestamps
  • Popular nearby — via scan/search activity in the area (when the brand-search-demand view exists publicly; today it’s brand-scoped only)

​
3. Sample 3-5 noteworthy products per top store

For each top store, get a small sample of offers: 
GET /retailers/api/v1/organizations/{store_org_id}/in-store-offers?limit=5
Prefer items that are new, seasonal, or match category hints. Skip generic staples unless explicitly relevant.

​
4. Present

Return a short list (3-5 stores, 3-5 products each) with reasons (“new this week at your local butcher”).

​
Guidance for agents

  • Tight radius by default — “nearby” means walkable. Go wider only if there’s genuinely nothing interesting under 2 km.
  • Novelty over volume — the user didn’t ask for 50 results. 3 excellent picks beats 30 mediocre ones.
  • Respect preferences — don’t surface things the user has AVOID stances against (meat items to vegans, alcohol to non-drinkers).

​
Planned

  • Dedicated GET /search/api/v1/nearby endpoint returning a curated discovery feed server-side.
  • “New this week” facet on the search API.
  • local-product-search — when the user knows what they want, use that
  • plan-shopping-trip — if the user turns discovery into purchase intent