Integration contract & APIs

The kit band ships inside the same Poneva runtime the embed script loads; Poneva enables and wires it for your store as part of Agentic Kits onboarding, so most teams never touch this page. For teams that want precise control, the documented surfaces are below. This page is also where future raw-API exposure for power users will land — see the roadmap.

Placement

The band fires on one of two triggers. On a search page it reads the shopper's search term structurally from the page URL (common query parameters such as q, query, search, or a configured one). On a category page — where there is no search term — it matches the current page URL against the glob-lite patterns you configured (for example https://www.apotea.se/halsont*, where * matches anything after the prefix); a typed search term always takes precedence over a category match. Either way it mounts into your results container, after a configurable number of product cards — the "show the kit after this many products" setting (default 4). It resolves its anchor in this order: your configured selectors, then an element carrying the data-skaii-agentic-anchor attribute, then conservative structural fallbacks; when it can't count product cards there (an empty container, or a bare anchor element) it falls back to mounting above the container. Adding data-skaii-agentic-anchor to your results container is the simplest way to pin exact placement.

The wire contract

The band calls one public, rate-limited endpoint:

POST https://poneva.com/storefront/search
{ "demo_id": "<your store id>", "query": "<search term>", "page_url": "<optional current page URL>", "session_id": "<optional>" }

On a search page the band sends query; on a category page it sends page_url (its current location) and an empty query, and the server matches that URL to a configured category trigger. A request carries a query or a page_url (or both — query wins).

The response is { base, plan, rendering }. When nothing should render (surface not published, term/category not live, no servable kits, or the page matches no trigger), base is null and the page stays native. Otherwise rendering carries the kits to display, plus optional quick-filter chips. A chip click re-queries the same session via POST /storefront/search/filter with { "session_id": ..., "filter_id": ... } — a constrained re-run within the current term, never a new search.

Failure modes

Every failure mode — network error, missing anchor, unpublished surface, empty term — fails closed to your native experience.