Merci MyLens Sign inFree trialStart free trial

API reference

REST · JSON · HTTPS

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.

FieldTypeWhat it does
textstringDesign code, part of it, or plain words such as “red silk saree”.
imagefile or base64A product photo. Any angle — turned or mirrored photos match too.
likestringThe like_key of a result: “more like this one”.
filtersobjectExact field filters, e.g. {"category":"RING","karat":"22K"}.
limit / offsetintPage 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

HTTPcodeMeaning
401invalid_keyKey missing, wrong or revoked.
402plan_inactiveThe project has no active plan. Renew in MyLens.
403link_revokedThe ERP admin revoked the link of this project.
409index_not_readyThe image index of this project is still being built.
422empty_query / bad_imageNothing to search, or the photo could not be read.
429rate_limitedToo 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.

Get an API key