API Reference

Getting Started

Sign up at skawr.com/search/import, then paste your store URL or upload a CSV to index your products. You'll get an API key immediately.

Authentication

All API requests require an API key passed via the X-API-Key header. Keys use a prefix.suffix format: the 8-char prefix is safe for frontend (search-only), and the full key grants write access.

Search

Search your indexed products with hybrid BM25 + semantic matching.

{
  "query": "iPhone 15 Pro",
  "per_page": 10,
  "filters": {
    "brand": "Apple"
  }
}

{
  "results": [
    {
      "id": "prod_abc123",
      "title": "iPhone 15 Pro Max 256GB",
      "price": 4299,
      "currency": "SAR",
      "image_url": "https://...",
      "score": 0.97
    }
  ],
  "total": 42,
  "query_time_ms": 23
}

Autocomplete

Get instant search suggestions as users type.

GET /api/v1/autocomplete?q=ipho&limit=5

{
  "suggestions": [
    "iPhone 15 Pro",
    "iPhone 15 Pro Max",
    "iPhone case",
    "iPhone charger"
  ]
}

Upload Documents

Add or update documents in your search index.

{
  "documents": [
    {
      "id": "prod_001",
      "title": "Samsung Galaxy S24 Ultra",
      "price": 4699,
      "currency": "SAR",
      "brand": "Samsung",
      "image_url": "https://...",
      "categories": ["Electronics", "Phones"]
    }
  ]
}

{
  "indexed": 1,
  "errors": []
}

Bulk Upload

Upload thousands of products in a single request. Supports JSON array or CSV.

// JSON array of products (up to 10,000 per request)
[
  { "id": "1", "title": "Product A", "price": 99 },
  { "id": "2", "title": "Product B", "price": 149 }
]

{
  "indexed": 2,
  "total_time_ms": 1230
}

Usage & Limits

Check your current usage against your plan limits.

GET /api/v1/saas/usage

{
  "plan": "Growth",
  "products_indexed": 12847,
  "products_limit": 50000,
  "searches_this_month": 23419,
  "searches_limit": 500000
}

SkawrBot

SkawrBot is a Q&A chat assistant you embed on your storefront. Shoppers ask questions in plain language, and it answers from a built-in FAQ set plus any custom FAQ pairs you configure. For product questions, it falls back to a search over your index. It is a static assistant with no external AI calls, so replies stay fast and predictable. SkawrBot is available on the Pro and Scale plans, alongside the Skawr Bar and Skawr Search Widget. On the Growth plan it is not available, and its endpoints return 403. Embed it with a single script tag, the same way as the other storefront widgets. Use your public prefix key (the 8-char prefix), which is safe to expose in the browser. The widget loads its settings from GET /api/v1/skawrbot/config and sends shopper messages to POST /api/v1/skawrbot/message.

<script
  src="https://api.skawr.com/static/skawrbot.js"
  data-skawr-key="pk_your_public_key"
  async
></script>

SkawrBot Message

Answer a shopper message. Matches against your FAQ set first, then falls back to a product search over your index. Configure the greeting, suggested questions, and custom FAQ pairs via POST /api/v1/skawrbot/config.

{
  "message": "do you have running shoes?"
}

{
  "answer": "Here is what I found in our store. You can also search for more.",
  "matched": true,
  "type": "product",
  "products": [
    {
      "title": "Nike Air Zoom Running Shoes",
      "url": "https://store.example.com/products/air-zoom",
      "image_url": "https://store.example.com/img/air-zoom.jpg"
    }
  ]
}

SDKs & Integrations

We provide official SDKs for quick integration: • JavaScript (npm): @skawr/sdk, full backend access • JavaScript (frontend): @skawr/search, search-only, uses prefix key • Flutter/Dart: skawr_sdk • PHP: skawr/sdk Native integrations: Salla (zero-code app), Shopify (theme extension). For platforms without an SDK, use the REST API directly with any HTTP client.

Analytics SDK

Product analytics is bundled with your Search SaaS plan. Send events from the browser, your server, or a mobile app, then view them in the dashboard.

The Analytics SDK ships for the platforms you are most likely to use: • @skawr/analytics-react: React and Next.js • @skawr/analytics-web: vanilla browser (no framework) • @skawr/analytics-node: server side (Node) • skawr-analytics: Python (PyPI) • skawr_analytics: Flutter and Dart Every SDK talks to the same ingest API. It sends POST /api/v1/events/track for events, POST /api/v1/events/identify for identity, and POST /api/v1/heatmaps/batch for heatmap interactions. Requests authenticate with the X-API-Key header, and each SDK also sends an X-SDK-Name header (react, web, node, python, or flutter) that shows up as a "by tool" breakdown in the dashboard. The default endpoint is https://analytics-api.skawr.com, which you can override with the endpoint option.

React and Next Quickstart

Wrap your app once in the Skawr provider. Pageviews are captured out of the box, and you opt in to the rest.

Install the package, then wrap your app at the root. Pass your logged-in user through the user prop so the SDK identifies and resets automatically as auth state changes. See the API keys section first: a key used in the browser must be track-only.

npm install @skawr/analytics-react
# or
pnpm add @skawr/analytics-react

import { Skawr } from '@skawr/analytics-react'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  // your auth provider: an object with id, email, name, or null when signed out
  const user = useCurrentUser()

  return (
    <html>
      <body>
        <Skawr
          apiKey={process.env.NEXT_PUBLIC_SKAWR_ANALYTICS_KEY!}
          autoPageviews
          autoClicks
          autoForms
          autoErrors
          heatmap
          attribution
          user={user}
        >
          {children}
        </Skawr>
      </body>
    </html>
  )
}

Browser SDK

For sites that do not use React. This is the @skawr/analytics-web equivalent of the React setup.

Use the browser SDK on plain HTML or non-React sites. It mirrors the React configuration: the same apiKey, endpoint, autoPageviews, autoClicks, autoForms, autoErrors, and heatmap options, plus a track call for custom events. The snippet below is illustrative of the browser SDK surface. Confirm the exact export and method names against the @skawr/analytics-web package README, since they can differ slightly from the React provider.

npm install @skawr/analytics-web

import { Skawr } from '@skawr/analytics-web'

const skawr = Skawr.init({
  apiKey: 'ska_your_track_only_key',
  endpoint: 'https://analytics-api.skawr.com',
  autoPageviews: true,
  autoClicks: true,
  autoForms: true,
  autoErrors: true,
  heatmap: true,
})

// custom event
skawr.track('newsletter_signup', { plan: 'growth' })

Node (server side)

Send events from your backend with @skawr/analytics-node.

Use the Node SDK for server-side events, for example a confirmed payment from a webhook. A server-side key is not exposed to browsers, so it may carry the query permission in addition to track. The snippet below is illustrative of the server SDK surface. Confirm the exact constructor and method names against the @skawr/analytics-node package README.

npm install @skawr/analytics-node

import { Skawr } from '@skawr/analytics-node'

const skawr = new Skawr({
  apiKey: process.env.SKAWR_ANALYTICS_SERVER_KEY, // server key, may include query
  endpoint: 'https://analytics-api.skawr.com',
})

await skawr.track({
  event: 'order_paid',
  userId: 'user_123',
  properties: { value: 4299, currency: 'SAR' },
})

Python and Flutter

Minimal server (Python) and mobile (Flutter) examples.

Install skawr-analytics from PyPI for Python, or add skawr_analytics to pubspec.yaml for Flutter and Dart. The snippets below are illustrative of each SDK surface, including the version pin. Confirm the exact class and method names and the current version against each package README before relying on them.

pip install skawr-analytics

from skawr_analytics import Skawr

skawr = Skawr(api_key="ska_your_server_key", endpoint="https://analytics-api.skawr.com")

skawr.track("order_paid", user_id="user_123", properties={"value": 4299, "currency": "SAR"})

dependencies:
  skawr_analytics: ^0.1.0

final skawr = Skawr(apiKey: 'ska_your_track_only_key');

skawr.track('order_paid', properties: {'value': 4299, 'currency': 'SAR'});

Getting your API key

Create and scope keys in the dashboard, then follow one rule for browser code.

Create analytics keys in the dashboard under Settings, then API keys. Keys carry permissions. A track key can send events. A query key can also read your analytics data. Scope each key to where it runs. Browser code (React, the browser SDK, mobile apps that ship the key) should use a track-only key. Server code (Node, Python) can use a key that also has query, because it is never exposed to a shopper.

Autocapture

Capture common interactions without writing tracking calls.

Autocapture records pageviews, clicks, form submits, and JavaScript errors for you. Turn on the streams you want with the autoPageviews, autoClicks, autoForms, and autoErrors props. Clicks on links, buttons, and any element with a data-skawr-track attribute are captured, form submits include non-sensitive fields, and errors come from window error and unhandled rejection handlers.

<Skawr
  apiKey={KEY}
  autoPageviews
  autoClicks
  autoForms
  autoErrors
>
  {children}
</Skawr>

Named and custom events

Track your own events from code or from markup.

Track custom events three ways. Call track from the useSkawr hook for events tied to an interaction, use useTrackOnMount for an event that should fire once when a component mounts, or add a data-skawr-track attribute to any element to capture it on click. Any data-skawr-* attribute becomes a property, and numbers and booleans are coerced to their primitive types. Name events in lowercase snake_case, for example purchase, newsletter_signup, or listing_clicked. Keep names stable so your reports stay consistent.

import { useSkawr, useTrackOnMount } from '@skawr/analytics-react'

function CheckoutButton({ value }: { value: number }) {
  const { track } = useSkawr()
  return (
    <button onClick={() => track('purchase', { value, currency: 'SAR' })}>
      Buy
    </button>
  )
}

function ArticlePage({ slug }: { slug: string }) {
  useTrackOnMount('article_viewed', { slug }) // fires once on mount
  return <article>...</article>
}

<button
  data-skawr-track="listing_clicked"
  data-skawr-listing-id={listing.id}
  data-skawr-price={listing.price}
>
  View listing
</button>

Identify and reset

Tie events to a known user after login, and clear identity on logout.

The simplest path in React is the user prop on the Skawr provider: set it after login, clear it on logout, and the SDK identifies and resets for you. If you need to do it by hand, useSkawr returns identify and reset. Call identify with your stable user id after login, and call reset on logout so the next session starts anonymous.

import { useSkawr } from '@skawr/analytics-react'

function useAuthAnalytics() {
  const { identify, reset } = useSkawr()

  return {
    onLogin: (user: { id: string; plan: string }) =>
      identify(user.id, { plan: user.plan }),
    onLogout: () => reset(),
  }
}

Heatmaps

Record click, scroll, and optional move interactions.

Set the heatmap prop to true to start the recorder, or pass an object to choose which signals to record. The recorder posts interactions to POST /api/v1/heatmaps/batch. trackMoves is the highest-volume signal, so leave it off unless you need mouse movement, to keep request volume down.

<Skawr
  apiKey={KEY}
  heatmap={{ trackClicks: true, trackScroll: true, trackMoves: false }}
>
  {children}
</Skawr>

Consent and privacy

Honoring consent signals and running a consent banner is your responsibility.

Respecting Do Not Track and Global Privacy Control, and showing a consent banner where required, are the integrator's responsibility for compliance with PDPL, CCPA, and GDPR. We recommend a consent-gated setup: mount the SDK only after the visitor has agreed, so no events are sent before consent.

export function Analytics({ children }: { children: React.ReactNode }) {
  const { hasConsent } = useConsent() // your consent banner state
  const user = useCurrentUser()

  if (!hasConsent) return <>{children}</>

  return (
    <Skawr apiKey={process.env.NEXT_PUBLIC_SKAWR_ANALYTICS_KEY!} autoPageviews user={user}>
      {children}
    </Skawr>
  )
}

Verify it works

A short checklist to confirm events are flowing.

Run through this after wiring the SDK: 1. Open your browser developer tools, go to the Network tab, and use your site. Confirm you see POST requests to /api/v1/events/track. 2. Open the analytics dashboard and confirm your SDK appears in the "by tool" breakdown (react, web, node, python, or flutter). 3. If you see nothing, the usual causes are an unset or empty key, a key without the track permission, or autocapture left off. Fix whichever applies and reload.

Troubleshooting

Common symptoms mapped to cause and fix.

No requests in the Network tab: the key is unset or empty. Confirm the environment variable is set at build time and holds a real track key. track requests return 401 or 403: the key lacks the track permission or belongs to the wrong project. Create a track-only key in Settings, then API keys. Clicks, form submits, or errors are missing: autocapture is opt-in since 0.7.0. Set autoClicks, autoForms, and autoErrors on the provider. Events do not appear under your SDK in the dashboard: check the "by tool" breakdown and make sure you are on a current SDK version, which sends the X-SDK-Name header. Heatmap density grid has no background image: this is expected for now, since DOM snapshot capture has not shipped. Interactions are still recorded.