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 reads the shopper's search term structurally from the page URL (common query parameters such as q, query, search, or a configured one) and mounts above your results container. It resolves its anchor in this order: your configured selectors, then an element carrying the data-skaii-agentic-anchor attribute, then conservative structural fallbacks. Adding data-skaii-agentic-anchor to your search 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>", "session_id": "<optional>" }

The response is { base, plan, rendering }. When nothing should render for the term (surface not published, term not live, no servable kits), base is null and the page stays native. Otherwise rendering carries the kits and recommendations 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.