Docs

Embed widget

Add this script to any page. Create an embed key in the dashboard under Embed.

<script
  src="https://fynd.chat/widget/fynd.js"
  data-key="YOUR_EMBED_KEY"
  data-bot="default"
  async></script>

• data-key: shop embed key (pk_live_…)
• data-bot: bot slug (default bot if omitted)
• data-position: launcher side: right (default) or left
• data-launcher: launcher emoji / label (default 💬)
• data-launcher-icon: optional image URL for the launcher button
• data-locale: optional UI locale override (e.g. nl, en)
• data-api: optional API base override

The public embed key (pk_live_…) is safe in the browser. Never put an sk_live catalog key in frontend code.

Catalog REST API

Push products into Fynd as an alternative or complement to sitemap and feeds. Indexed products power recommendations, prices, and product cards in chat.

Authenticate with Authorization: Bearer sk_live_…

Base URL: https://fynd.chat/api/v1/catalog

Create a key under API keys in the dashboard (Growth+). The full key is shown once. Store it securely. Plan limits apply to products and API keys (402 when exceeded).

Endpoints

• GET /products: list / search (q, page, bot)
• PUT /products/{external_id}: create or update one product
• POST /products/bulk: bulk upsert (max 500 per request)
• DELETE /products/{external_id}: soft-delete (available: false)
• POST /sync: re-index all available products for search / RAG

Writes default to the shop-wide shared catalog. Add ?bot=slug for a bot-specific overlay (overrides shared for the same external_id).

Product fields

Example: upsert

curl -X PUT https://fynd.chat/api/v1/catalog/products/MBP-14 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "MacBook Pro 14\"",
    "description": "Powerful laptop for pros",
    "price": 1999,
    "currency": "EUR",
    "product_url": "https://shop.example/macbook-pro-14",
    "image_url": "https://shop.example/mbp.jpg",
    "category": "Laptops",
    "attributes": {"ram": "16GB"},
    "available": true
  }'

Example: bulk

curl -X POST https://fynd.chat/api/v1/catalog/products/bulk \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "external_id": "SKU-1",
        "title": "Product A",
        "price": 49.99,
        "currency": "EUR",
        "product_url": "https://shop.example/a"
      },
      {
        "external_id": "SKU-2",
        "title": "Product B",
        "price": 79.00,
        "currency": "EUR",
        "product_url": "https://shop.example/b"
      }
    ]
  }'

Example: search, overlay, delete & sync

# Search
curl "https://fynd.chat/api/v1/catalog/products?q=macbook&page=1" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Bot overlay
curl -X PUT "https://fynd.chat/api/v1/catalog/products/MBP-14?bot=default" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"MacBook Pro 14\" (bot)","price":1899,"currency":"EUR"}'

# Soft-delete
curl -X DELETE https://fynd.chat/api/v1/catalog/products/MBP-14 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Re-index
curl -X POST https://fynd.chat/api/v1/catalog/sync \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Knowledge sources

Besides the Catalog API, sync knowledge from the dashboard with no code required.

• Custom knowledge: paste FAQs, policies, and tips (all plans)
• Sitemap crawl: each URL becomes a sync row you can watch (Growth+)
• Product feed XML/CSV: URL or upload (Growth+)
• REST pull: fetch a remote catalog on a schedule (Growth+)
• Catalog push API: the REST endpoints above (Growth+)

Rate limits

Catalog API and widget endpoints are throttled per key and IP to prevent abuse.

• Catalog API: 120 requests / minute per API key, 60 / minute per IP.
• Widget config/events: 120 requests / minute per embed key, 60 / minute per IP.
• Widget chat: 20 messages / minute per embed key, 10 / minute per IP (lower on the public demo).
• Plan limits (messages, products, bots) apply on top of technical throttles.

Error codes

API errors return JSON with a clear status code.

• 401: missing or invalid API key
• 402: plan / license limit reached (products, feature)
• 403: no access to this shop or feature
• 404: product or bot not found
• 422: validation error in the payload
• 429: rate limit hit; retry later

Widget events

The embed widget sends allowlisted analytics events to your shop dashboard.

• widget_open: visitor opens the advisor
• message_sent: visitor sends a message
• product_click: visitor clicks a recommended product
• lead_submit: visitor leaves contact details