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.
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
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:
| Method | Where | Value |
|---|---|---|
| X-API-Key | Request header | X-API-Key: your_api_key |
| Authorization | Request header | Authorization: Bearer your_api_key |
| api_key | Query string or POST body | ?api_key=your_api_key |
Find your API key in Dashboard → Settings → API Key after creating a store and training its index.
Quick start
Create an account & add your store
Sign up, go to Dashboard → Add Website, and paste your store URL.
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.
Copy your API key
Dashboard → Settings → API Key. The key is unique per store.
Make your first search call
Use the text search endpoint below — your first result should appear in under 200 ms.
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}'
Text search
Search your product catalog using a natural-language query string. The AI model understands synonyms, intent, and context — not just exact keyword matches.
Request body
| Field | Type | Description |
|---|---|---|
| queryrequired | string | Natural language product description. Min 2 characters. |
| top_koptional | integer | Number of results to return. Default 5. Max 20. |
Example
POST /api/search/text/ X-API-Key: your_api_key Content-Type: application/json { "query": "red summer dress", "top_k": 5 }
{
"results": [
{
"name": "Floral Red Midi",
"product_url": "https://...",
"score": 0.94
},
...
]
}
Code examples
// Text search example 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: 'red summer dress', top_k: 5 }), }); const data = await res.json(); console.log(data.results);
import requests
resp = requests.post(
"https://ecomvis.com/api/search/text/",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"query": "red summer dress", "top_k": 5},
)
results = resp.json()["results"]
$ch = curl_init('https://ecomvis.com/api/search/text/'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-API-Key: YOUR_API_KEY', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'query' => 'red summer dress', 'top_k' => 5, ]), ]); $data = json_decode(curl_exec($ch), true);
Image search
Find products that look visually similar to a photo. Pass either an image URL (JSON body) or upload a file directly (multipart form).
Option A — image URL (JSON)
| Field | Type | Description |
|---|---|---|
| image_urlrequired | string | Publicly accessible URL of the image. |
| top_koptional | integer | Results to return. Default 5. |
Option B — file upload (multipart)
| Field | Type | Description |
|---|---|---|
| imagerequired | file | Image file. JPEG, PNG, WebP supported. Max 10 MB. |
| top_koptional | integer | Results to return. Default 5. |
Examples
curl -X POST https://ecomvis.com/api/search/image/ \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"image_url":"https://example.com/dress.jpg","top_k":5}'
// fileInput is an <input type="file"> element const form = new FormData(); form.append('image', fileInput.files[0]); form.append('top_k', '5'); const res = await fetch('https://ecomvis.com/api/search/image/', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY' }, body: form, }); const data = await res.json();
import requests with open("product.jpg", "rb") as f: resp = requests.post( "https://ecomvis.com/api/search/image/", headers={"X-API-Key": "YOUR_API_KEY"}, files={"image": f}, data={"top_k": 5}, ) results = resp.json()["results"]
Voice search
Send an audio recording and receive ranked product results in one call. ecomvis transcribes the audio then runs the semantic search automatically.
Request — multipart form
| Field | Type | Description |
|---|---|---|
| audiorequired | file | Audio recording. WAV, MP3, WebM, OGG supported. Max 25 MB. |
| top_koptional | integer | Results to return. Default 5. |
Example — JavaScript MediaRecorder
// Record from microphone, then search const stream = await navigator.mediaDevices.getUserMedia({ audio: true }); const recorder = new MediaRecorder(stream); const chunks = []; recorder.ondataavailable = e => chunks.push(e.data); recorder.onstop = async () => { const blob = new Blob(chunks, { type: 'audio/webm' }); const form = new FormData(); form.append('audio', blob, 'query.webm'); form.append('top_k', '5'); const res = await fetch('https://ecomvis.com/api/search/voice/', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY' }, body: form, }); const data = await res.json(); console.log(data.results); }; recorder.start(); setTimeout(() => recorder.stop(), 3000); // record 3 seconds
Status
Check the current state of your store's search index and remaining quota.
curl https://ecomvis.com/api/status/ \
-H "X-API-Key: YOUR_API_KEY"
{
"website": "mystore.com",
"is_trained": true,
"searches_today": 142,
"monthly_limit": 10000,
"plan": "Starter"
}
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.
<!-- 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.
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
});
Shopify
Add the ecomvis widget to any Shopify store in under two minutes — no app required.
Open the theme editor
Shopify Admin → Online Store → Themes → Edit code.
Edit theme.liquid
Find the closing </body> tag and paste the snippet just above it.
Save & preview
Click Save — the widget launcher appears immediately in the theme preview.
{%- 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>
mystore.myshopify.com) in Dashboard → Add Website. ecomvis fetches your product feed automatically.WooCommerce (WordPress)
Two methods — a lightweight PHP snippet (recommended) or pasting directly into a child theme.
Method A — functions.php snippet
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
<script src="https://ecomvis.com/api/widget/script/"></script> <script> EcomvisWidget.init({ apiKey: 'YOUR_API_KEY' }); </script>
Webflow
Open Project Settings → Custom Code
Webflow Dashboard → your project → Settings → Custom Code.
Paste in "Footer Code"
The snippet below goes into the Footer Code box (runs before </body>).
Publish your site
Click Save Changes then re-publish. The widget appears on your live site.
<script src="https://ecomvis.com/api/widget/script/"></script> <script> EcomvisWidget.init({ apiKey: 'YOUR_API_KEY', position: 'bottom-right', placeholder: 'Search our products…', }); </script>
Wix
Via Wix Velo (Dev Mode)
Enable Dev Mode
Wix Editor → Dev Mode toggle (top menu bar) → Turn on Velo.
Open masterPage.js
In the code panel, select Site → masterPage.js.
Paste the snippet
Wix loads this on every page of your site.
$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);
});
Custom CMS / Framework
For React, Vue, Next.js, Nuxt, or any custom-built storefront.
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
}
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);
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;
}
Error codes
All errors return a JSON body with an error key describing the issue.
| HTTP status | Meaning | Common 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": "API key required. Pass X-API-Key header."
}
Rate limits & quotas
Limits apply per store (per API key). The /api/status/ endpoint returns your current usage.
| Plan | Monthly 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.
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.
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.
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.
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({}):
| Option | Type | Default | Description |
|---|---|---|---|
| apiKeyrequired | string | — | Your store API key. |
| positionoptional | string | "bottom-right" | "bottom-right" or "bottom-left". |
| placeholderoptional | string | "What are you looking for..." | Input placeholder text. |
| greetingoptional | string | "Hi! Search by text, image, or voice." | Opening message shown in the widget. |
| topKoptional | integer | 5 | Number of results to display. |
| primaryColoroptional | string | "#2563eb" | Hex colour for buttons and accents. |
Ready to integrate?
Create a free account, train your index, and go live in minutes.