REST API
Namespace: aiwsa/v1 (filter aiwsa_rest_namespace) Base: /wp-json/aiwsa/v1/
Shopper routes require the nonce from GET /config (and conversation ownership where noted). Analytics routes require an administrator permission callback.
Do not send API keys to these endpoints.
Shopper / widget
| Method | Route | Purpose |
|---|---|---|
| GET | /config | Bootstrap: nonce, flags, appearance, fallbacks, quick actions. No nonce required (by design). Uncacheable. |
| POST | /conversations | Start chat. Body channel: widget, block, shortcode, product (default widget). block is a channel label only. |
| GET | /conversations/{uuid} | Read conversation if owned |
| DELETE | /conversations/{uuid} | Erase if owned |
| POST | /conversations/{uuid}/messages | One turn. message and/or action_id (Quick Action) |
| POST | /confirm | Redeem or cancel staged intent. Body: intent_uuid, uuid, optional cancel |
| GET | /cart | Session cart + URLs |
| POST | /cart/add | Stage add (confirmation broker). product_id, optional variation, qty, conversation uuid |
| POST | /cart/update | Quantity. cart_item_key, quantity |
| POST | /cart/remove | Remove line. cart_item_key |
| GET | /products/refresh | Live price/stock for card IDs (ids) |
| GET | /products/{id}/variations | Purchasable variations |
| GET | /products/compare | Compare catalog products |
| GET | /recommendations | context=product or context=cart |
| POST | /stock-alerts | product_id, email |
Admin
| Method | Route | Purpose |
|---|---|---|
| GET | /analytics | Dashboard JSON for managers |
| GET | /analytics/orders/{order_id} | Attribution row (no customer email/payment in UI) |
Errors
Unexpected throwables become JSON errors (not a white screen). Rate-limit responses include headers from Rate_Limiter. Trace IDs join logs and the response.
Example: config
GET /wp-json/aiwsa/v1/configUse nonce (and X-WP-Nonce) on subsequent calls. features.ai is true when a provider is configured. transport may be sse even though the bundled widget uses POST.
PHP extensibility (high level)
Stable integration points are hooks (hooks.md) and aiwsa_register_tools / aiwsa_register_providers. Prefer those over instantiating internal classes.
Useful types (may evolve): Settings, Tool_Result, Search_Criteria, Conversation. Treat anything under includes/ without a hook as internal.