Architecture

Neuroon sits between two ends of your integration: the shopper's browser (where the widget runs) and your server (where your catalog lives). Two separate APIs with different credentials sit between them, so you never expose a server secret in the client.

Block view

Hover or click a flow to see details.

The two APIs

API	Prefix	Who calls it	Credential
Widget	/api/widget/*	Your frontend (shopper's browser)	X-Widget-Token (24 h TTL)
Plugin	/api/plugin/shops/*	Your server	Permanent X-Shop-API-Key + origin validation

Both share the same search engine. Your server always speaks HTTPS to api.neuroon.ai. The shopper never sees your Shop API Key.

End-to-end flow

1. Shopper searches: the widget calls the Widget API with its X-Widget-Token. The response carries products, guided filters and, depending on plan, the AI assistant answer.
2. Shopper clicks: the widget sends track/click (idempotent).
3. Shopper checks out: your server calls the Plugin API with X-Shop-API-Key to register the conversion.
4. You update the catalog: your server calls the Plugin API with products/sync (batches up to 500). The product is searchable in 2 to 5 seconds.

Eventual consistency

After 200 OK from products/sync there is a short window before the product becomes searchable. If your E2E test fails searching for a freshly inserted product, wait a few seconds and retry with backoff.

URL versioning

Today, the API does not expose /v1/, /v2/ in the URL: backward compatibility is kept by contract and breaking changes are announced upfront in the Changelog. URL versioning will be added later — when it lands it will be additive: today's routes will keep working through a grace window.

Next reads

• Quickstart — from zero to your first search in 5 minutes.
• Environments — Production vs Development.
• Authentication · Overview — which credential to use and when.