# Integration contract & APIs

> The documented integration surfaces for engineering teams — placement anchor, wire contract, and failure modes.

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](./roadmap.md).

## 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.