Free cookie consent management tool by TermsFeed Generator
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
⚠️
Keep your key secret. For client-side widget embeds, use the Widget SDK instead — it is designed for public use and does not expose your key.

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 never exposed to visitors.
HTML embed
<!-- Place before </body> -->
<script src="https://ecomvis.com/static/js/widget.js"></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/static/js/widget.js" 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/static/js/widget.js" 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/static/js/widget.js"></script>
<script>
  EcomvisWidget.init({ apiKey: 'YOUR_API_KEY' });
</script>
Integration guide

Webflow

1

Open Project Settings → Custom Code

Webflow Dashboard → your project → SettingsCustom 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/static/js/widget.js"></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 SitemasterPage.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/static/js/widget.js';
  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/static/js/widget.js';
    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/static/js/widget.js';
    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 searchesConcurrent requests
Free 50 2
Starter Monthly 5,000 2
Starter Yearly 5,000 2
Growth monthly 15,000 2
Growth yearly 15,000 2
Pro monthly 50,000 2
Pro Yearly 50,000 2
Pay As You Go 9,999,999 2

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

Reference

Widget SDK options

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

OptionTypeDefaultDescription
apiKeyrequiredstringYour 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