Loading documentation…
Loading documentation…
Give a shopping agent a product contract
Give your application a way to turn an ordinary-language or image-based product need into a structured shortlist a shopping agent can use. Use hosted MCP when a compatible tool client should discover the operations, or use the public REST API from any server or runtime. The guides show the task each path solves, the exact request shape and what is available in the beta today.
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 public contract accepts the technical codes gb, us, de, fr, es, it, au, and ca. United Kingdom currently live. United States planned next.Other technical codes are not beta catalogue availability claims.
Availability
Available now
REST API, hosted MCP, the TypeScript and Python SDKs, the Node MCP package, and the public OpenAPI contract are available through their documented routes.
Coming soon
The corrected Python MCP package is published on PyPI. MCP directory acceptance, a hosted Smithery connection, framework adapters, VS Code distribution, and ChatGPT distribution still need their separate external publication or acceptance evidence.
Guides are public
Every page in this developer docs section is public. A “Coming soon” channel refers to its external package, listing, or review gate—not to access to these guides.
This is the current availability summary. The guides below are public customer documentation; “Coming soon” refers only to an external package, listing, or review gate, not to access to these guides.
Developer channels
REST, hosted MCP, the published SDKs, the Node MCP package, and the public contract are available now. The status summary above identifies the remaining external publication and acceptance gates so the guides do not imply that an unreleased package or marketplace listing is live.
The Model Context Protocol (MCP) exposes the same product search contract as discoverable tools. Your compatible client can call Simlir without a custom adapter; authentication, credits, market scope and response limits remain the same as REST.
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_products1 creditSemantic 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 display ceiling: Simlir ranks a bounded candidate window against the complete request and can return fewer items or zero when candidates are clearly the wrong product type or fail a stated hard constraint.
| 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. Technical contract values: gb, us, de, fr, es, it, au, ca. Beta catalogue availability is database-backed. |
| limit | number | No | Results ceiling 1–50 (default: 10). Returned count can be lower after mismatch filtering. |
simlir_search_products_by_image2 creditsVisual search across the same product database. Pass a hosted HTTPS image URL and optionally add a natural-language query when the shopper has requirements the image cannot establish, such as product role, size, compatibility, or intended use. Simlir fuses both signals and gets structured product results back with avisual_similarity_score. The requested limit is a display ceiling: Simlir ranks a bounded candidate window using the image evidence and complete request, and can return fewer items or zero when candidates are clearly the wrong product type or fail a hard constraint.
| Parameter | Type | Req | Description |
|---|---|---|---|
| image_url | string | No | Hosted HTTPS image URL |
| query | string | No | Optional natural-language context or hard requirement combined with the image |
| 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. Technical contract values: gb, us, de, fr, es, it, au, ca. Beta catalogue availability is database-backed. |
| limit | number | No | Results ceiling 1–50 (default: 10). Returned count can be lower after mismatch filtering. |
Send a hosted image_url . Add query for context such as “slim fridge freezer for a small flat”. The image remains the visual signal; Simlir combines it with the shopper's semantic intent before ranking. This keeps tool calls text-only: the calling 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. Technical contract values: gb, us, de, fr, es, it, au, ca. Beta catalogue availability is database-backed. |
| 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. catalogue 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, and /v1/lookup. 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, catalogue synchronisation, 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 with optional context. Send a hosted HTTPS product photo, pack shot, or screenshot URL. Add the optional natural-language query when the shopper also specifies a role, size, compatibility, or use case. Simlir combines the visual and semantic signals and returns the same structured product shape plus a visual_similarity_score. Costs 2 credits, and the returned list can be shorter than the requested limit when the mismatch filter removes obviously wrong products.
/v1/search1 creditSemantic search across products — same engine as the MCP tool
| Param | Req | Description |
|---|---|---|
| q | Yes | Natural language search query |
| gl | Yes | Required shopper country code. Technical contract values: gb, us, de, fr, es, it, au, ca. Beta catalogue availability is database-backed. |
| 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 catalogue 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. Technical contract values: gb, us, de, fr, es, it, au, ca. Beta catalogue availability is database-backed. |
| 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/image2 creditsSend JSON with a hosted HTTPS image_url and optional query context to find products by image and semantic intent
| Param | Req | Description |
|---|---|---|
| image_url | Yes | Hosted HTTPS image URL |
| query | No | Optional natural-language context or hard requirement |
| market | Yes | Required shopper country code. Technical contract values: gb, us, de, fr, es, it, au, ca. Beta catalogue availability is database-backed. |
| 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",
"query": "a slim fridge freezer with a front water dispenser for a small flat",
"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"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.
Dashboard signup uses Google OAuth. A successful OAuth callback creates or opens the account; there is no separate email-confirmation step in the current flow. v1 does not currently expose selectable scopes or sandbox environments.
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 | Concurrent | Credit-use guard |
|---|---|---|---|---|---|
| Free account | 60 | 20 | No cap | 5 | 100 credits/min |
| Standard | 5,000 | 750 | No cap | 50 | 2,500 credits/min |
| Enterprise | Custom — contact us | ||||
These are request ceilings, not an unmetered data allowance. Paid operations still require credits; the public demo is a separate keyless, lower-rate surface.
The concurrent and credit-use safeguards are account-wide and apply before expensive work starts. Credit-use limits count the operation cost, so image search uses more of that allowance than an exact lookup. The Free daily cap resets at 00:00 UTC; other windows return a Retry-After value.
Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After.
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.
Image search is visual-first when no context is supplied. When query is present, the image and natural-language intent are fused before the shared product-fit guard ranks the bounded candidate window. Use the context to express nuance that a photo cannot prove; do not treat the visual score alone as a product-role or hard-constraint decision.
For /v1/search, /v1/search/image, and the MCP search tools, limit is a display ceiling, not a promise. Simlir ranks up to 50 valid candidates against the complete request and may return fewer items or zero when candidates are clearly the wrong product type or fail a stated hard constraint.
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 galleryUse this as the primary product image in a product response. It is a stable, retailer-hosted https:// URL selected for product cards and visual flows; temporary thumbnails and non-image assets are excluded. 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 |
The published TypeScript and Python SDKs and the Node MCP package are documented separately. Framework adapters are coming soon; all channels share the same public API contract and retain their own registry, ownership, licensing, and rollback status.
Create an account, generate an API key, and start with semantic search, image search, or exact lookup.