Loading documentation…
Loading documentation…
Two ways to integrate: connect your AI agent via MCP (recommended), or call our REST API directly. Text-only tool-using assistants can still handle image search because simlir does the visual interpretation inside the tool or API call.
Market scoping is required on every search-like call. Always send the shopper's country so results stay market-scoped. Use market in MCP calls andgl in REST calls. The current product catalogue covers the United Kingdom (GB).
The Model Context Protocol (MCP) lets AI agents discover and use our tools natively — no custom API code needed. Your agent calls our MCP server, and simlir becomes a tool it can use like any other.
Add simlir as an MCP server in your agent's config. Works with Claude Desktop, Cursor, VS Code, and any MCP-compatible agent.
{
"mcpServers": {
"simlir": {
"url": "https://simlir.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Once connected, your agent can discover the simlir_search_products , simlir_lookup_products_by_identifier , and simlir_search_products_by_image tools automatically via tools/list.
simlir_search_products2 creditsSemantic search across our product database. Returns structured product data with specs, price snapshots, review scores, descriptions, visual metadata, and direct retailer product links. The requested limit is a ceiling: a post-search sanity filter can return fewer items or zero when the current candidate page is clearly the wrong product type.
| Parameter | Type | Req | Description |
|---|---|---|---|
| query | string | Yes | Natural language search query |
| category | string | No | Filter by product category |
| brand | string | No | Filter by brand name |
| min_price | number | No | Minimum price filter |
| max_price | number | No | Maximum price filter |
| market | string | Yes | Required shopper country code. Currently supporting gb (United Kingdom). |
| limit | number | No | Results ceiling 1–50 (default: 10). Returned count can be lower after mismatch filtering. |
simlir_search_products_by_image3 creditsVisual search across the same product database. Pass a hosted HTTPS image URL and get structured product results back with avisual_similarity_score. The requested limit is a ceiling: a post-search sanity filter can return fewer items or zero when the current candidate page is clearly the wrong product type.
| Parameter | Type | Req | Description |
|---|---|---|---|
| image_url | string | No | Hosted HTTPS image URL |
| category | string | No | Filter by product category |
| brand | string | No | Filter by brand name |
| min_price | number | No | Minimum price filter |
| max_price | number | No | Maximum price filter |
| market | string | Yes | Required shopper country code. Currently supporting gb (United Kingdom). |
| limit | number | No | Results ceiling 1–50 (default: 10). Returned count can be lower after mismatch filtering. |
Send a hosted image_url . This keeps tool calls text-only: the model does not need to inspect the image itself before calling simlir.
simlir_lookup_products_by_identifier1 creditExact lookup by GTIN, MPN/model number, or retailer SKU. This is the right MCP tool when your workflow already has an identifier from a merchant feed, checkout export, ERP row, or retailer PDP and you want matching products without semantic ranking.
| Parameter | Type | Req | Description |
|---|---|---|---|
| identifier | string | Yes | Exact GTIN, MPN/model number, or retailer SKU to match |
| type | auto | gtin | mpn | sku | No | Lookup strategy. auto tries gtin first, then mpn, then sku. type=mpn maps onto the model_number field in the returned product shape. |
| brand | string | No | Optional exact brand filter for ambiguous identifiers |
| retailer | string | No | Optional retailer filter. Strongly recommended for retailer-specific SKU lookups. |
| market | string | Yes | Required shopper country code. Currently supporting gb (United Kingdom). |
| limit | number | No | Results ceiling 1–50 (default: 20). |
Example use case: a price comparison site already has GTINs from merchant feeds. It can call simlir with the GTIN and shopper market to pull back matching offers, price snapshots, and direct retailer links without relying on fuzzy search. If a source only has an MPN, use type=mpn and remember that the response field is still model_number.
simlir_lookup_products_by_identifier({ identifier: "8806095048789", type: "gtin", market: "gb", retailer: "Currys" })When a user asks your agent about a product, the agent can decide when to call simlir, pull back structured product evidence, and turn it into a normal reply.
Buying Assistant
simlir MCP connected
What's the best protein powder under £30?
I'll check the U.K. catalog for powders under your £30 cap, then rank the best-value options by price, review coverage, and protein per serving.
Tool call: simlir_search_products
Structured search with price cap and explicit market scoping.
simlir_search_products({ query: "protein powder", max_price: 30, market: "gb" })Matches reviewed
18
Shortlist returned
3
Price ceiling
£30
Here are three strong options that stay under budget and still have reliable review coverage.
Optimum Nutrition Gold Standard 100% Whey
£29.99Best overall balance of price, review score, and flavour range.
Holland & Barrett
Bulk Pure Whey Protein
£27.49Strong protein-per-pound pick if you want a leaner shortlist option.
Bulk
Myprotein Impact Whey Protein
£22.98Lowest upfront price here while still keeping solid review coverage.
Myprotein
Example input
What's the best protein powder under £30?
The agent chooses when to call simlir and injects the structured results into the reply.
The agent gets structured specs, price snapshots, review scores, visual cues, and purchase links without maintaining its own scraping stack.
The same structured product surface, delivered as standard HTTP endpoints for text search, image search, exact identifier lookup, UUID lookup, and integrations that don't use MCP. All requests require an API key in the Authorization: Bearer header.
gl is required on /v1/search, /v1/search/image, /v1/lookup, and /v1/categories. We do not infer shopper country server-side.
/v1/searchYour primary endpoint. Send a natural language query, get semantically-ranked products with full specs, prices, and retailer links. The limit is a ceiling, not a promise: the returned list can be shorter or empty if the current candidate page is the wrong product type.
/v1/lookupExact lookup by identifier. Best for price comparison sites, merchant-feed joins, catalog sync, and ERP workflows that already have a GTIN, MPN, or retailer SKU. Use type=auto to try GTIN first, then MPN, then SKU. GTIN is the strongest cross-retailer key, MPN is next, and retailer SKU is contextual because it is retailer-specific.
/v1/productFollow-up lookup by UUID. Every search result includes a stable id (UUID) that never changes. Use this endpoint to fetch a product later — when a user clicks a result, to refresh pricing, or to retrieve a product you've cached the ID of. Costs 1 credit instead of 2 for a full search.
/v1/search/imageSearch from a hosted product image. Send a hosted HTTPS product photo, pack shot, or screenshot URL and get visually similar products back with the same structured product shape plus a visual_similarity_score. Costs 3 credits, and the returned list can be shorter than the requested limit when the mismatch filter removes obviously wrong products.
/v1/categoriesFree utility. List all available product categories for a market — use this to populate filters or validate category parameters before searching.
/v1/search2 creditsSemantic search across products — same engine as the MCP tool
| Param | Req | Description |
|---|---|---|
| q | Yes | Natural language search query |
| gl | Yes | Required shopper country code. Currently supporting gb (United Kingdom). |
| category | No | Filter by category |
| brand | No | Filter by brand |
| min_price | No | Minimum price |
| max_price | No | Maximum price |
| limit | No | Results ceiling (1–50, default: 20). Returned count may be lower after mismatch filtering. |
| offset | No | Pagination offset (max 500) |
curl "https://simlir.com/api/v1/search?q=protein+powder&gl=gb&limit=5" -H "Authorization: Bearer sk_your_key"/v1/lookup1 creditExact lookup by GTIN, MPN/model number, or retailer SKU. Ideal for price comparison feeds and catalog joins when you already have an identifier. type=mpn maps onto the model_number field in the returned product shape.
| Param | Req | Description |
|---|---|---|
| identifier | Yes | Exact GTIN, MPN/model number, or retailer SKU to match |
| type | No | Lookup strategy. auto tries gtin first, then mpn, then sku. type=mpn maps onto the model_number field in the returned product shape. |
| gl | Yes | Required shopper country code. Currently supporting gb (United Kingdom). |
| brand | No | Optional exact brand filter for ambiguous identifiers |
| retailer | No | Optional retailer filter. Strongly recommended for retailer-specific SKU lookups. |
| limit | No | Results ceiling (1–50, default: 20). |
# Exact lookup when you already have a GTIN, MPN, or retailer SKU
curl "https://simlir.com/api/v1/lookup?identifier=8806095048789&type=gtin&gl=gb&retailer=Currys&limit=10" -H "Authorization: Bearer sk_your_key"/v1/search/image3 creditsSend JSON with a hosted HTTPS image_url to find visually similar products
| Param | Req | Description |
|---|---|---|
| image_url | Yes | Hosted HTTPS image URL |
| market | Yes | Required shopper country code. Currently supporting gb (United Kingdom). |
| category | No | Filter by category |
| brand | No | Filter by brand |
| min_price | No | Minimum price |
| max_price | No | Maximum price |
| limit | No | Results ceiling (1–50, default: 20). Returned count may be lower after mismatch filtering. |
| offset | No | Pagination offset (max 500) |
curl -X POST "https://simlir.com/api/v1/search/image" \
-H "Authorization: Bearer sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://cdn.example.com/product.jpg",
"market": "gb",
"limit": 5
}'/v1/product1 creditLook up a single product by its stable simlir UUID — returned in every search result
| Param | Req | Description |
|---|---|---|
| id | Yes | Product UUID (from a search result) |
# Look up a product by its simlir UUID (returned from a search)
curl "https://simlir.com/api/v1/product?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "Authorization: Bearer sk_your_key"/v1/categories0 creditsList all product categories for a market
| Param | Req | Description |
|---|---|---|
| gl | Yes | Required shopper country code. Currently supporting gb (United Kingdom). |
curl "https://simlir.com/api/v1/categories?gl=gb" -H "Authorization: Bearer sk_your_key"All API calls require a Bearer token. Create your API key in the dashboard.
Authorization: Bearer sk_your_api_key_hereAPI keys are hashed on our side — we can't recover them. Store your key securely. You can create multiple keys and revoke them individually.
Use of API responses is governed by our API/Data Licence. Bulk exports and similar high-volume access require separate written permission.
| Tier | Req/min | Burst | Daily |
|---|---|---|---|
| Free | 10 | 20 | 10 |
| Standard | 1,000 | 5,000 | No cap |
| Enterprise | Custom — contact us | ||
Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.
Every product in the response includes these fields:
market echoes the shopper country you requested. Treat a mismatch between the requested country and the returned market as an integration bug.
relevance_score is only present in /v1/search results (cosine similarity, 0–1).
visual_similarity_score is only present in /v1/search/image results. It is a visual-match score and should not be compared directly to relevance_score.
For /v1/search, /v1/search/image, and the MCP search tools, limit is a ceiling, not a promise. simlir may return fewer items or zero when the post-search sanity filter removes obvious product-type mismatches from that exact result page.
For /v1/lookup and the MCP identifier lookup tool, requested_type echoes what you asked for, while resolved_type and matched_field tell you which exact field matched. When you send type=mpn, the response still uses model_number on each product.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"brand": "Optimum Nutrition",
"category": "protein powder",
"gtin": "5060245603478",
"title": "Optimum Nutrition Gold Standard Whey Protein Powder",
"description": "The Optimum Nutrition Gold Standard 100% Whey delivers 24g of protein per 30g serving with only 120 calories, using a blend of whey protein isolate, concentrate, and hydrolysed whey. Each serving provides 5.5g of naturally occurring BCAAs and 4g of glutamine for muscle recovery. The powder mixes smoothly in a shaker without clumping and is available in over 20 flavours. Positioned as a mid-range to premium whey protein, it targets serious gym-goers and athletes who want a trusted, Informed Sport certified product without paying boutique prices. Manufactured under strict quality controls with batch testing for banned substances.",
"product_description": "Premium whey protein powder with 24g protein per serving for post-workout recovery. Informed Sport certified for competitive athletes and serious gym-goers.",
"key_selling_points": [
"24g protein per serving",
"5.5g BCAAs",
"Informed Sport certified"
],
"use_cases": [
"post-workout recovery",
"muscle building",
"competitive athletes",
"casual gym-goers"
],
"spec": {
"protein_per_serving": "24g",
"servings": "29",
"calories_per_serving": 120,
"bcaa_per_serving": "5.5g",
"flavour": "Double Rich Chocolate"
},
"cosmetic_features": {
"packaging_style": "resealable tub"
},
"image_url": "https://images.optimumnutrition.co.uk/whey-front.jpg",
"images": [
"https://images.optimumnutrition.co.uk/whey-front.jpg",
"https://images.optimumnutrition.co.uk/whey-nutrition-label.jpg"
],
"visual": {
"summary": "Black whey protein tub with red and gold accents and a large Gold Standard label on the front.",
"labels": [
"protein powder",
"supplement tub",
"black packaging"
],
"detected_text": [
"Gold Standard",
"24g Protein"
],
"dominant_colours": [
"black",
"red",
"gold"
]
},
"certifications": [
"informed_sport",
"gluten_free"
],
"materials": [],
"dimensions": {
"value": {
"h": 24,
"diameter": 16
},
"unit": "cm"
},
"weight": {
"value": 0.899,
"unit": "kg"
},
"colour": {
"primary": null,
"family": null
},
"release_year": null,
"country_of_origin": "US",
"compatible_with": [],
"included_in_box": [
"scoop"
],
"model_number": "GS100W-2270G-DRC",
"retailer_sku": "ON-2270G-GB",
"product_identifiers": {
"article_number": "GSWHEY-2LB-CHOC",
"alternate_part_numbers": [
"1031660-P"
]
},
"review_score": 4.8,
"review_count": 20,
"price": {
"amount": 29.99,
"currency": "GBP",
"retailer": "Holland & Barrett",
"as_of": "2026-04-07"
},
"links": {
"buy": "https://www.hollandandbarrett.com/shop/product/optimum-nutrition-gold-standard-100-whey/...",
"retailer": "https://www.hollandandbarrett.com/shop/product/optimum-nutrition-gold-standard-100-whey/..."
},
"market": "gb",
"relevance_score": 0.923
}links.retailer — direct retailer product page when we have oneThis is the retailer product page captured for the product row. Use it when the customer wants to inspect the exact merchant page, availability, delivery terms, or checkout path. Keep treating prices as snapshots: retailer pages can change after simlir last saw them.
May be null when the row does not have a verified retailer product URL.
links.buy — compatibility alias of the direct retailer pageThis field stays in the contract for older clients that already open links.buy directly. When we have a verified retailer product page, it mirrors the same URL as links.retailer, not a separate comparison destination.
Treat links.buy links.retailer as the same public product-page URL. If the row does not have a verified retailer page, both fields are null.
price — a snapshot, not a live quoteprice.amount is the price we observed when the product was last rediscovered (price.as_of is when). Use it for ranking, sorting, and rough display. If you need a current merchant offer at purchase time, open links.retailer when it is present. If your integration already opens links.buy it resolves to the same retailer page.
image_url — the durable hero image, plus images[] for the galleryThis field is the single hero image the pipeline carries through ingestion, re-extraction, product reads, and the visual lane. It is always a retailer-hosted https:// URL. The pipeline rejects expiring thumbnail URLs and obvious non-image assets before this value reaches the visual path. The images array stays HTTPS-only and is intended for gallery rendering.
visual — a public summary of what the hero image showsWhen available, this object gives you a short visual summary, a few labels, any clearly visible text, and dominant colours. It is derived from the same hero image stored in image_url and is safe to show directly to users or pass to agents.
Internal rollout fields such as the model name and generation timestamp stay private. If a row has not been visually enriched yet, visual isnull.
| Code | Meaning |
|---|---|
| 400 | Invalid request (missing params, bad format) |
| 401 | Missing or invalid API key |
| 402 | Insufficient credits |
| 404 | Product not found |
| 405 | Method not allowed (use the documented GET or POST method) |
| 413 | Payload too large |
| 429 | Rate limit exceeded |
| 502 | Search temporarily unavailable (embedding failure) |
| 503 | Service temporarily unavailable |
We're building official SDKs for Node.js, Python, and Go. In the meantime, the REST API works with any HTTP client.
npm install @simlir/sdk # Coming soonCreate an account, generate an API key, and start with semantic search, image search, or exact lookup.