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.
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 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 Google Shopping links.
| 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 | No | Country code (default: "gb") |
| limit | number | No | Results 1–50 (default: 10) |
simlir_search_products_by_image3 creditsVisual search across the same product database. Pass a hosted image, data URL, or uploaded image bytes and get structured product results back with avisual_similarity_score.
| Parameter | Type | Req | Description |
|---|---|---|---|
| image_url | string | No | HTTPS image URL or data:image payload |
| image_base64 | string | No | Base64 image bytes when your client forwards an upload |
| image_mime_type | string | No | Required with image_base64 |
| 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 | No | Country code (default: "gb") |
| limit | number | No | Results 1–50 (default: 10) |
Send either an image_url or the pair image_base64 + image_mime_type. This lets tool-using assistants stay text-only: the model does not need to inspect the image itself before calling simlir.
When a user asks your agent about a product, the agent calls simlir automatically:
What's the best protein powder under $30?
I'll search simlir for protein powders under $30...
simlir_search_products({ query: "protein powder", max_price: 30, market: "gb" })
Based on our product database, here are the top options: Optimum Nutrition Gold Standard Whey ($27.99, 24g protein/serving), MyProtein Impact Whey ($23.99, 21g protein/serving)...
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, lookups, and integrations that don't use MCP. All requests require an API key in the Authorization: Bearer header.
/v1/searchYour primary endpoint. Send a natural language query, get up to 50 semantically-ranked products with full specs, prices, and retailer links. This is the core product.
/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 an uploaded image. Send a product photo, pack shot, or screenshot as multipart form data and get visually similar products back with the same structured product shape plus a visual_similarity_score. Costs 3 credits.
/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 | No | Market/country code (default: gb) |
| category | No | Filter by category |
| brand | No | Filter by brand |
| min_price | No | Minimum price |
| max_price | No | Maximum price |
| limit | No | Results to return (1–50, default: 20) |
| 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/search/image3 creditsUpload multipart/form-data with an image file in the image field to find visually similar products
| Param | Req | Description |
|---|---|---|
| image | Yes | JPEG, PNG, WEBP, GIF, or AVIF file up to 5 MB |
| gl | No | Market/country code (default: gb) |
| category | No | Filter by category |
| brand | No | Filter by brand |
| min_price | No | Minimum price |
| max_price | No | Maximum price |
| limit | No | Results to return (1–50, default: 20) |
| offset | No | Pagination offset (max 500) |
curl -X POST "https://simlir.com/api/v1/search/image" \
-H "Authorization: Bearer sk_your_key" \
-F "image=@./product.jpg" \
-F "gl=gb" \
-F "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 | No | Market/country code (default: gb) |
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.
| 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:
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.
{
"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": 27.99,
"currency": "GBP",
"retailer": "Currys",
"as_of": "2026-04-07"
},
"links": {
"buy": "https://www.google.com/shopping/product/..."
},
"market": "gb",
"relevance_score": 0.923
}links.buy — Google Shopping comparison page, not direct checkoutThis is the canonical comparison page for the product. We deliberately do not expose retailer URLs — they go stale, get hotlink-blocked, and lock you into one merchant. Google Shopping aggregates current prices across all retailers stocking the item, so always send users (or your agent’s purchase intent) here.
May be null on rare rows where the listing was discovered without a Google Shopping link.
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.buy when it is present. That URL opens the live Google Shopping comparison page for the product, not a direct retailer checkout link.
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 can be either a self-contained data:image/... URI or a retailer-hosted https:// URL. The pipeline rejects expiring Google Shopping 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 (image uploads must be 5 MB or smaller) |
| 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 soonSign up for free, grab your API key, and start querying. 100 credits included.