REST API · JSON

API Documentation

Integrate ecomvis AI search into any website, app, or platform. Three endpoints, one API key, unlimited possibilities.

Overview

Introduction

The ecomvis API lets you add AI-powered product search to any e-commerce store. Your product catalog is indexed once — after that, every search returns ranked results in milliseconds.

The API is RESTful, uses JSON bodies, and is authenticated with an API key per store. All requests must be made over HTTPS.

ℹ️
Base URL: https://ecomvis.com/api/
All endpoints are relative to this base.

Supported search modes

💬

Text search

Natural language queries — "red summer dress under $50"

🖼️

Image search

Upload a photo or pass an image URL to find visually similar products

🎙️

Voice search

Send an audio recording; ecomvis transcribes and searches in one step

Security

Authentication

Every request must include your store's API key. You can pass it in three ways — the header is preferred for server-side usage:

MethodWhereValue
X-API-KeyRequest headerX-API-Key: your_api_key
AuthorizationRequest headerAuthorization: Bearer your_api_key
api_keyQuery string or POST body?api_key=your_api_key
⚠️
Your API key is domain-restricted. It only works from the domain you registered in the dashboard. Even if someone copies it from page source, it cannot be used on any other website. For extra security, never share your key and rotate it from the dashboard if compromised.

Find your API key in Dashboard → Settings → API Key after creating a store and training its index.

Getting started

Quick start

1

Create an account & add your store

Sign up, go to Dashboard → Add Website, and paste your store URL.

2

Train your product index

ecomvis crawls your product feed and builds a semantic search index. Training typically takes a few minutes for up to 10 000 products.

3

Copy your API key

Dashboard → Settings → API Key. The key is unique per store.

4

Make your first search call

Use the text search endpoint below — your first result should appear in under 200 ms.

cURL · first request
curl -X POST https://ecomvis.com/api/search/text/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "red summer dress", "top_k": 5}'
Endpoint

Status

Check the current state of your store's search index and remaining quota.

GET /api/status/
Request
curl https://ecomvis.com/api/status/ \
  -H "X-API-Key: YOUR_API_KEY"
Response 200
{
  "website": "mystore.com",
  "is_trained": true,
  "searches_today": 142,
  "monthly_limit": 10000,
  "plan": "Starter"
}
Integration guide

Vanilla JS / Plain HTML

The quickest way to add ecomvis to any website. Drop the script tag in your HTML and initialise the widget — no build step required.

✅
Recommended for most stores. The Widget SDK handles authentication, UI, and all three search modes automatically. Your API key is visible in page source but is domain-restricted — it only works from your registered domain, so copying it is useless to anyone else.
HTML embed
<!-- Place before </body> -->
<script src="https://ecomvis.com/api/widget/script/"></script>
<script>
  EcomvisWidget.init({
    apiKey:      'YOUR_API_KEY',
    position:    'bottom-right',    // or 'bottom-left'
    placeholder: 'Search products…',
    greeting:    'Hi! Search by text, image or voice.',
    topK:        8,
  });
</script>

Direct API call (no widget)

If you want to build your own search UI, call the API directly from the browser. Note: this exposes your API key to users — use a server-side proxy for production.

Custom search UI example
async function searchProducts(query) {
  const res = await fetch('https://ecomvis.com/api/search/text/', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, top_k: 8 }),
  });
  if (!res.ok) throw new Error(await res.text());
  return (await res.json()).results;
}

// Wire up a search input
document.getElementById('search-input')
  .addEventListener('input', async e => {
    const results = await searchProducts(e.target.value);
    renderResults(results); // your own render function
  });
Integration guide

Shopify

Add the ecomvis widget to any Shopify store in under two minutes — no app required.

1

Open the theme editor

Shopify Admin → Online Store → Themes → Edit code.

2

Edit theme.liquid

Find the closing </body> tag and paste the snippet just above it.

3

Save & preview

Click Save — the widget launcher appears immediately in the theme preview.

theme.liquid — before </body>
{%- comment -%}ecomvis AI search widget{%- endcomment -%}
<script src="https://ecomvis.com/api/widget/script/" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', function() {
    EcomvisWidget.init({
      apiKey:   'YOUR_API_KEY',
      position: 'bottom-right',
    });
  });
</script>
ℹ️
To train the index on your Shopify catalog, paste your store URL (e.g. mystore.myshopify.com) in Dashboard → Add Website. ecomvis fetches your product feed automatically.
Integration guide

WooCommerce (WordPress)

Two methods — a lightweight PHP snippet (recommended) or pasting directly into a child theme.

Method A — functions.php snippet

functions.php
add_action('wp_footer', 'ecomvis_widget');
function ecomvis_widget() { ?>
<script src="https://ecomvis.com/api/widget/script/" defer></script>
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      EcomvisWidget.init({
        apiKey:   'YOUR_API_KEY',
        position: 'bottom-right',
      });
    });
  </script>
<?php }

Method B — footer.php

footer.php — before </body>
<script src="https://ecomvis.com/api/widget/script/"></script>
<script>
  EcomvisWidget.init({ apiKey: 'YOUR_API_KEY' });
</script>
Integration guide

Webflow

1

Open Project Settings → Custom Code

Webflow Dashboard → your project → Settings → Custom Code.

2

Paste in "Footer Code"

The snippet below goes into the Footer Code box (runs before </body>).

3

Publish your site

Click Save Changes then re-publish. The widget appears on your live site.

Webflow Footer Code
<script src="https://ecomvis.com/api/widget/script/"></script>
<script>
  EcomvisWidget.init({
    apiKey:      'YOUR_API_KEY',
    position:    'bottom-right',
    placeholder: 'Search our products…',
  });
</script>
Integration guide

Wix

⚠️
Wix restricts arbitrary external scripts. Use Wix Velo (Dev Mode) or the Custom Element approach described below. Standard Wix sites without Velo cannot add external scripts.

Via Wix Velo (Dev Mode)

1

Enable Dev Mode

Wix Editor → Dev Mode toggle (top menu bar) → Turn on Velo.

2

Open masterPage.js

In the code panel, select Site → masterPage.js.

3

Paste the snippet

Wix loads this on every page of your site.

masterPage.js (Wix Velo)
$w.onReady(function () {
  const s = document.createElement('script');
  s.src  = 'https://ecomvis.com/api/widget/script/';
  s.onload = () => EcomvisWidget.init({
    apiKey: 'YOUR_API_KEY',
  });
  document.body.appendChild(s);
});
Integration guide

Custom CMS / Framework

For React, Vue, Next.js, Nuxt, or any custom-built storefront.

React component
import { useEffect } from 'react';

export default function EcomvisWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://ecomvis.com/api/widget/script/';
    script.onload = () => {
      window.EcomvisWidget.init({
        apiKey:   'YOUR_API_KEY',
        position: 'bottom-right',
      });
    };
    document.body.appendChild(script);
    return () => { /* cleanup on unmount */ };
  }, []);

  return null; // widget renders itself into the DOM
}
Vue plugin (plugins/ecomvis.js)
export default {
  install() {
    const s = document.createElement('script');
    s.src    = 'https://ecomvis.com/api/widget/script/';
    s.onload = () => window.EcomvisWidget.init({
      apiKey: 'YOUR_API_KEY',
    });
    document.body.appendChild(s);
  },
};

// main.js / nuxt plugin
// app.use(EcomvisPlugin);
TypeScript search hook
interface SearchResult {
  name:        string;
  product_url: string;
  score:       number;
}

async function ecvSearch(
  query: string,
  topK = 5,
): Promise<SearchResult[]> {
  const res = await fetch('https://ecomvis.com/api/search/text/', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ECOMVIS_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, top_k: topK }),
  });
  if (!res.ok) throw new Error(res.statusText);
  return (await res.json()).results;
}
Reference

Error codes

All errors return a JSON body with an error key describing the issue.

HTTP statusMeaningCommon cause
200 OK Request succeeded. Results in results array.
400 Bad Request Missing required field, query too short, or invalid file type.
401 Unauthorised API key missing from request.
403 Forbidden Invalid API key, or store index not yet trained.
429 Too Many Requests Daily or monthly quota exceeded for the current plan.
500 Server Error Unexpected error — contact info@ecomvis.com.
Error response shape
{
  "error": "API key required. Pass X-API-Key header."
}
Reference

Rate limits & quotas

Limits apply per store (per API key). The /api/status/ endpoint returns your current usage.

PlanMonthly searches
Free 50
Starter Monthly 5,000
Starter Yearly 5,000
Growth monthly 15,000
Growth yearly 15,000
Pro monthly 75,000
Pro Yearly 75,000
Pay As You Go Unlimited

When the monthly limit is reached the API returns 429. Upgrade your plan or wait for the next billing cycle to resume.

Owner reports

Merchant analytics without additional AI calls

Open Dashboard → Analytics to select your own websites, a rolling 7- or 30-day window, and export that same selection as spreadsheet-safe CSV. Recent searches have moved here; dashboard quotas, websites, management and billing remain available. The report counts successful logged API requests, not purchases, sessions or billing credits.

Search responses retain their existing results, count, engine and voice transcription fields, and may also contain analytics_token. Clients can ignore this optional field. The server writes one log per successful search request, even when the unchanged search engine returns cached results or an exact identity match. Cache-hit and identity-hit status themselves are unavailable at the boundary and are not inferred.

  • Zero-result rate counts only responses with no products. Weak results are listed separately below a top score of 0.55; neither outcome proves missing inventory.
  • Average top match score uses the first returned product's existing score, when available. It is a ranking measure on a 0–1 scale, not a calibrated probability or conversion metric.
  • Older logs keep their original timestamps, modality and result count. Missing scores, product snapshots, languages and impressions remain unavailable, not invented zeros.
  • Keyword trends recognize a small fixed English vocabulary in text queries, not AI intent. Budget ceilings recognize explicit “under/below/less than/max USD/EUR/GBP 50” patterns; bare dollar amounts and other formats remain unclassified. Widget language is client-reported, not a fresh language-analysis call. Hidden AI filters, ambiguity and deeper trends are unavailable.
  • No uploaded images, audio or voice transcripts are added to analytics. Image/voice rows retain placeholders. Product snapshots contain public catalog names/URLs and existing scores.

Widget impressions are not returned candidates

The updated widget sends X-Ecomvis-Language and X-Ecomvis-Widget: visible-v1 on search requests when visibility measurement is supported. It reports a result card only after at least 50% visibility for 250ms while the widget is open and the browser page is visible. Pagination, expanded results and restored chats are supported; each search/result position counts at most once. Demo/preview traffic is not sent. Measurement failures do not interrupt results.

POST /api/widget/impressions/

Use the same API-key header and existing domain policy. JSON body: {"token":"analytics_token from this search","positions":[0,4,8]}. Positions are zero-based indices into that exact response, not product IDs. Only submit cards actually exposed; this is client-reported telemetry, not verified human activity. The widget normally submits one measured position at a time.

  • Signed tokens are bound to one website/search and expire after 24 hours. Requests allow 1–50 integer positions and at most 4 KiB. Out-of-range, tampered, expired and cross-store tokens are rejected.
  • Duplicate positions are idempotent, never increment search quotas, and never create search logs. There is an additional 120-event/search/minute limit per cache worker with the default process-local cache; it is not a distributed global rate limit.
  • The response is {"accepted":true} when saved. Errors use 400, 401/403, 405, 429 or 503. Do not retry indefinitely or let event errors hide search results.
  • Historical and third-party traffic without measurement support has unknown impressions. Mixed traffic shows the measured-return coverage, not an implied view count for all results.

Catalog health reads existing manifest/index-file status only. It does not reload vectors, rebuild indexes or test external image URLs live. Image-failure counts reflect the last catalog indexing run.

Catalog management

Fetch current website prices

In Dashboard → Website → Fetch prices, Ecomvis tests the first linked product and then updates the remaining linked products one at a time. Progress, pause/resume and per-product source or failure messages are preserved. This is an owner-only, signed-in dashboard operation protected by CSRF, not a new public API-key endpoint.

  • PRODUCT NAME and image URL(s) remain the only required upload fields. PRODUCT LINK is optional for uploads and needed only for products whose prices are fetched.
  • Supported sources include product JSON-LD, product-price metadata, scoped product HTML, Shopify product data and KlipClop's verified custom product-page format.
  • KlipClop requires a single product URL and a matching product title. Its custom format publishes USD base prices before browser currency conversion; these are recorded as USD, not converted or inferred from a dollar symbol.
  • For differently priced KlipClop sizes, supply VARIANTS with the actual numeric size IDs and existing prices. All priced catalog variants must map uniquely. Unverified variant query links and combined color/size pricing remain unsupported.
  • HTTP failures, rate limits, robots restrictions and ambiguous products/options leave previous prices unchanged. Successful fetched prices survive catalog rebuilds and take precedence over older uploaded prices.

Merchant-controlled alternative

For unsupported stores, the store administrator can publish standard Product JSON-LD with current offers directly in the public page HTML. Publish the actual price and explicit three-letter currency; include offer SKUs or variant URLs when options have different prices. Do not publish installment amounts, crossed-out prices or recommendation prices as current offers. Retest Fetch prices after the store fixes its markup or grants appropriate access.

Alternatively, maintain PRICE and CURRENCY in the catalog upload for products without successful fetched overrides. Existing fetched overrides still take precedence; uploading an old CSV does not reset them. No paid scraping service, browser automation, AI extraction or access-control bypass is used.

Reference

Widget SDK options

The compact desktop widget is 400 pixels wide and up to 780 pixels tall, limited by the available viewport. Results remain four per page; the range, page number and Previous/Next controls stay visible within the current results block while scrolling. Maximize still shows the full returned result set. Mobile sizing and keyboard handling are preserved. The Language label and selector use matching typography.

No embed configuration or API changes are needed for this layout update. Use the stable /api/widget/script/ script URL to receive updates on page reload; preserve your existing initialization block and API key. In the website dashboard, overflowing price-fetch results have a bounded, keyboard-scrollable table with a contrasting scrollbar. Some operating systems hide native scrollbars until scrolling, according to the user's system preferences.

All options passed to EcomvisWidget.init({}):

OptionTypeDefaultDescription
apiKeyrequiredstring—Your store API key.
positionoptionalstring"bottom-right""bottom-right" or "bottom-left".
placeholderoptionalstring"What are you looking for..."Input placeholder text.
greetingoptionalstring"Hi! Search by text, image, or voice."Opening message shown in the widget.
topKoptionalinteger5Number of results to display.
primaryColoroptionalstring"#2563eb"Hex colour for buttons and accents.
✅
The Widget SDK is the safest way to integrate ecomvis on public-facing pages. It communicates with the ecomvis server directly and never stores your API key in localStorage or cookies.

Ready to integrate?

Create a free account, train your index, and go live in minutes.

Get started free → See pricing