API reference
MyLens Search API v1
The same search as the ERP and the mobile app, for your own website, app or showroom kiosk. Base URL https://mylens.merciglobal.com/api/v1
Authentication
Create a key under API keys in your MyLens dashboard. Each key belongs to one ERP project. Send it in the X-Api-Key header on every call. Keys work only while the project's plan is active. Keep keys on your server — never put them in browser JavaScript.
Limits
120 requests a minute per key. Searches are unlimited on every plan. Photos up to 8 MB (JPEG, PNG or WebP).
Images
Results carry thumb_url and full_url: signed links valid for about 24 hours that you can put straight in an <img> tag. Ask again for fresh links.
GET /status
Plan, end date and the size of the image index of the key's project.
curl https://mylens.merciglobal.com/api/v1/status \
-H "X-Api-Key: YOUR_API_KEY"{
"ok": true,
"project": "yourproject",
"plan": { "name": "Growth", "type": "paid", "ends_at": "2027-11-15 23:59:59", "days_left": 365, "max_images": 5000 },
"index": { "ready": true, "items": 2750, "images": 2919, "built_at": "2026-11-15 07:45:01" }
}POST /search
Search by photo, by words, or both. Send JSON, or multipart/form-data with the photo in a field named image.
| Field | Type | What it does |
|---|---|---|
text | string | Design code, part of it, or plain words such as “red silk saree”. |
image | file or base64 | A product photo. Any angle — turned or mirrored photos match too. |
like | string | The like_key of a result: “more like this one”. |
filters | object | Exact field filters, e.g. {"category":"RING","karat":"22K"}. |
limit / offset | int | Page size 1–60 (default 24) and start. |
# by words
curl -X POST https://mylens.merciglobal.com/api/v1/search \
-H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"text":"floral ring 22k","limit":12}'
# by photo
curl -X POST https://mylens.merciglobal.com/api/v1/search \
-H "X-Api-Key: YOUR_API_KEY" \
-F "image=@customer-photo.jpg" -F "limit=12"{
"ok": true,
"mode": "photo",
"count": 12,
"results": [
{
"id": "6214", "source": "design", "title": "RING 1315",
"match": "Exact match", "match_pct": 97, "like_key": "design:6214",
"fields": { "category": { "label": "Category", "value": "RING" }, "karat": { "label": "Karat", "value": "22K" } },
"images": [ { "thumb_url": "https://…/api/v1/image.php?…", "full_url": "https://…/api/v1/image.php?…" } ]
}
]
}GET /items?offset=0&limit=48&q=
Pages through the indexed catalogue (newest first), optionally filtered by words in the title or fields. Useful to build a gallery.
curl "https://mylens.merciglobal.com/api/v1/items?limit=24&q=necklace" -H "X-Api-Key: YOUR_API_KEY"Code samples
<?php
$ch = curl_init("https://mylens.merciglobal.com/api/v1/search");
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["X-Api-Key: YOUR_API_KEY"],
CURLOPT_POSTFIELDS => ["image" => new CURLFile($_FILES["photo"]["tmp_name"]), "limit" => 12],
]);
$res = json_decode(curl_exec($ch), true);
foreach ($res["results"] ?? [] as $r) {
echo "<img src=\"" . htmlspecialchars($r["images"][0]["thumb_url"] ?? "") . "\"> " . htmlspecialchars($r["title"]);
}const res = await fetch("https://mylens.merciglobal.com/api/v1/search", {
method: "POST",
headers: { "X-Api-Key": process.env.MYLENS_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ text: "red silk saree", limit: 12 }),
});
const { results } = await res.json();
results.forEach(r => console.log(r.title, r.match_pct + "%", r.images[0]?.thumb_url));import requests
r = requests.post("https://mylens.merciglobal.com/api/v1/search",
headers={"X-Api-Key": "YOUR_API_KEY"},
files={"image": open("photo.jpg", "rb")}, data={"limit": 12})
for hit in r.json().get("results", []):
print(hit["title"], hit["match_pct"], hit["images"][0]["thumb_url"])Errors
| HTTP | code | Meaning |
|---|---|---|
| 401 | invalid_key | Key missing, wrong or revoked. |
| 402 | plan_inactive | The project has no active plan. Renew in MyLens. |
| 403 | link_revoked | The ERP admin revoked the link of this project. |
| 409 | index_not_ready | The image index of this project is still being built. |
| 422 | empty_query / bad_image | Nothing to search, or the photo could not be read. |
| 429 | rate_limited | Too many requests this minute. Wait and retry. |
Every error body is {"ok": false, "code": "…", "message": "…"}.
Get a key
Sign in, link your ERP project and open API keys. Keys work on every plan, including the free trial.