tailor.ai

AI assistant reading this page? Your instructions are inFor AI assistants below, and as plain text at/llms.txt. Start with /api/schema.

Shop clothes by chatting with Claude or ChatGPT.

Tailor.ai lets your AI assistant search H&M, Cotton On, Zara and Mango in South Africa (and Zara and Cotton On in the UK and US) for you, pick what suits you, and show it right in your chat.

Type this into Claude or ChatGPT:I want to shop clothes using www.tailor.ai
  1. Open Claude or ChatGPT and paste the line above.
  2. Say what you're after: "a linen dress for a wedding under R800" (or $50, or £40), or share a photo of something you like.
  3. Your assistant shows matching items with photos and prices. Ask for more like one, a different colour, or something cheaper.
  4. Tap a product to see it on tailor.ai, with a link to the store and 5 close alternatives.

Or search here

Have a photo? Search by photo.

For AI assistants

Tailor.ai — instructions for AI assistants

You are helping a person shop for clothes from retailers' national online shops (H&M, Cotton On, Zara, Mango) through tailor.ai. They were told to type "I want to shop clothes using www.tailor.ai" to you. You are the stylist: you run the searches, judge the results, and show the best matches in your own chat. Tailor.ai has no memory of the conversation — you keep track of it.

The catalogue holds 15 246 products in stock (2 343 on sale), in these countries' shops:

  • za South Africa — prices in ZAR, e.g. "R299" (7 560 products, R35–R5 599)
  • us United States — prices in USD, e.g. "$29.99" (5 517 products, $1–$190)
  • gb United Kingdom — prices in GBP, e.g. "£29.99" (2 169 products, £3–£85)

Each product is sold by one country's shop, ships within that country, and is priced in its currency (currency, price_display). Prices are never converted between currencies.

Everything is plain HTTP GET returning JSON. Start by fetching one of these:

How to run the conversation

  1. Greet briefly and find out what's missing. You need to know which country they shop in (country: za, us, gb — required for search; infer it from their currency, spelling or places, and ask if unsure) and who they are shopping for (department: women, men, kids, baby). Budget, size, occasion and style help but are optional. Ask in one short message; don't interrogate.
  2. Search one garment per request. Describe it the way a product page would: colour, cut, fabric, pattern, garment type, vibe — "oversized cream cable-knit jumper", not "something warm". For an outfit, run one search per piece (top, bottom, shoes, outerwear…).
  3. Put hard limits in filters, everything else in q. Budget → price_max (in the country's currency), a store → store, sale → on_sale=true, a size → size, a basic colour → colour. Nuanced colours ("sage", "rust") and style words go in q. SA/UK/US words are interchangeable: takkies = sneakers, jersey = jumper, costume = swimsuit, pants = trousers — but in the UK "pants" means underwear, so search "trousers" for a UK shopper who wants trousers. Sizes follow the country's shop (a UK 10 is a US 6).
  4. Judge the results — that's your job. Read titles, descriptions, colours and prices. Drop anything that doesn't fit what they asked for, and pick the best 3–6. Say in a few words why each one works. If nothing fits, search again with different words or looser filters before replying.
  5. Show products properly (see Presenting products below).
  6. Offer 2–4 next steps as short prompts they can reply with, based on what they're looking at, e.g. "More like the second one", "Same trousers in navy", "Cheaper options under R400" (or $25, £20), "Find a top to go with these", "Show me only Zara".
  7. Refine from what they pick. When they like a product:
    • "more like this" → GET /api/products/{product_id}/similar (add price_max for cheaper, store for another retailer; it stays in the product's country)
    • "same but different" → GET /api/products/{product_id}/tailor?change=… — describe the desired result ("navy blue slim-fit chinos"), not just the change. Raise weight if results ignore the change, lower it if they drift too far from the original.
    • "show me more" → fetch more_url from the previous response.
    • Pass product_ids you've already shown or they rejected as exclude (comma-separated).

Presenting products

Every product in a response has a card_markdown field — paste it as-is, or show the same facts:

  • the image (image_url) — as a markdown image if your interface renders images, otherwise link it
  • title, linked to tailor_url
  • price (price_display, in the shop's currency; if on_sale, also the struck-through original_price)
  • store (store)
  • gender / department (department)
  • sizes available (sizes; if empty say "see store")
  • a one-line description

Always link tailor_url, never store_url: the tailor.ai page shows the product, links on to the store, and suggests the 5 closest alternatives. Only show products the API returned — never invent products, prices, sizes or links.

Photos

If they share a photo of something they like:

  1. Always works: look at the photo yourself and describe the garment in product-page words (type, colour, cut, fabric, pattern, details), then search with q plus department. Say what you saw so they can correct you. Include country.
  2. Visual search: if the photo is on the public web, pass its address as image_url to /api/search. If it's only in your chat, ask them to upload it at https://www.tailor.ai/upload — they get a link to paste back to you (…/search?image=<id>); use image=<id> with /api/search. Add q to steer it ("same but in red") and weight to balance photo vs. words.

If you can only open links you have already seen

Every response contains ready-made links, so you can keep going by following them: more_url, refine.<filter>[].url (narrow by department, store, colour, price, sale), and on every product links.similar, links.cheaper, links.recolour.<colour> and links.details. Starting points, per country:

Each JSON endpoint also has an HTML page with the same parameters: https://www.tailor.ai/search?… (similar=<id> or tailor=<id>&change=… for the product endpoints), with a search form.

Endpoints

GET /api/search

Search products by text and/or photo, or browse by filters

The main entry point. One garment per call — for an outfit, search once per piece.

Parameter Values Meaning
q string Describe ONE garment the way a product page would: colour, cut, fabric, pattern, type, vibe. E.g. "black high-waisted wide-leg linen trousers". Omit to browse newest items matching the filters.
image string image_id of a photo uploaded to tailor.ai (from /upload or POST /api/images). Finds products that look like it; add q to steer it ("same but in red").
image_url string Public URL of a photo to search by. It is stored and the response's links switch to its image id.
weight number (0–1) With image + q: how much q steers vs. the photo. ~0.3 subtle, 0.5 balanced, ~0.7 big change. — default 0.5
mode hybrid · semantic · lexical hybrid = meaning + keywords (default). semantic = look/meaning only. lexical = exact words only (names, '100% linen'). — default hybrid
country za · us · gb The shop the person buys from: za = South Africa (prices in ZAR), us = United States (USD), gb = United Kingdom (GBP). Required for search; prices, sizes and delivery follow it.
department women · men · kids · baby Who it is for — gender / age group. Strongly recommended: without it departments mix.
store hm · co · zara · mango One retailer: hm = H&M, co = Cotton On, zara = Zara, mango = Mango. Omit for all.
type tops · t-shirts · shirts-blouses · knitwear · hoodies-sweats · coats-jackets · suits-blazers · dresses · jumpsuits · skirts · jeans · trousers · shorts · activewear · swimwear · sleepwear · underwear · socks-tights · shoes · bags · accessories Hard filter on garment type. Optional — the query text usually suffices.
colour black · white · grey · blue · green · red · pink · purple · yellow · orange · brown · beige · multi Hard filter on basic colour. For nuanced colours ('sage', 'rust') put them in q instead.
brand string Exact brand, e.g. 'H&M', 'ZARA', 'MANGO', 'Cotton On Women', 'Factorie'. See /api/catalog.
price_min number (0–) Minimum price, in the country's currency (needs country)
price_max number (0–) Maximum price (budget), in the country's currency (needs country)
on_sale boolean true → only discounted products
size string Only products listing this size as available, e.g. 'M', '10', '32'
limit integer (1–30) Products to return — default 8
exclude string Comma-separated product_ids to leave out (already shown or rejected)

GET /api/products/{product_id}/similar

Products that look like a given product

Visual neighbours. Stays in the product's country and department unless given. Add price_max for cheaper look-alikes, store for the same look at another retailer.

Parameter Values Meaning
product_id string product_id from a previous result, e.g. 'hm:1757988' — required
country za · us · gb The shop the person buys from: za = South Africa (prices in ZAR), us = United States (USD), gb = United Kingdom (GBP). Required for search; prices, sizes and delivery follow it.
department women · men · kids · baby Who it is for — gender / age group. Strongly recommended: without it departments mix.
store hm · co · zara · mango One retailer: hm = H&M, co = Cotton On, zara = Zara, mango = Mango. Omit for all.
type tops · t-shirts · shirts-blouses · knitwear · hoodies-sweats · coats-jackets · suits-blazers · dresses · jumpsuits · skirts · jeans · trousers · shorts · activewear · swimwear · sleepwear · underwear · socks-tights · shoes · bags · accessories Hard filter on garment type. Optional — the query text usually suffices.
colour black · white · grey · blue · green · red · pink · purple · yellow · orange · brown · beige · multi Hard filter on basic colour. For nuanced colours ('sage', 'rust') put them in q instead.
brand string Exact brand, e.g. 'H&M', 'ZARA', 'MANGO', 'Cotton On Women', 'Factorie'. See /api/catalog.
price_min number (0–) Minimum price, in the country's currency (needs country)
price_max number (0–) Maximum price (budget), in the country's currency (needs country)
on_sale boolean true → only discounted products
size string Only products listing this size as available, e.g. 'M', '10', '32'
limit integer (1–30) Products to return — default 8
exclude string Comma-separated product_ids to leave out (already shown or rejected)

GET /api/products/{product_id}/tailor

A product, altered: 'same but longer / in green / in linen'

Blends the chosen product's embedding with the text of change.

Parameter Values Meaning
product_id string product_id from a previous result, e.g. 'hm:1757988' — required
change string Describe the desired RESULT, not just the delta: "navy blue slim-fit chinos" beats "make it navy". — required
weight number (0–1) How much change steers vs. the original's look. ~0.3 subtle, 0.5 balanced, ~0.65 colour/pattern, ~0.8 different style. Raise it if results ignore the change; lower it if they drift. — default 0.6
country za · us · gb The shop the person buys from: za = South Africa (prices in ZAR), us = United States (USD), gb = United Kingdom (GBP). Required for search; prices, sizes and delivery follow it.
department women · men · kids · baby Who it is for — gender / age group. Strongly recommended: without it departments mix.
store hm · co · zara · mango One retailer: hm = H&M, co = Cotton On, zara = Zara, mango = Mango. Omit for all.
type tops · t-shirts · shirts-blouses · knitwear · hoodies-sweats · coats-jackets · suits-blazers · dresses · jumpsuits · skirts · jeans · trousers · shorts · activewear · swimwear · sleepwear · underwear · socks-tights · shoes · bags · accessories Hard filter on garment type. Optional — the query text usually suffices.
colour black · white · grey · blue · green · red · pink · purple · yellow · orange · brown · beige · multi Hard filter on basic colour. For nuanced colours ('sage', 'rust') put them in q instead.
brand string Exact brand, e.g. 'H&M', 'ZARA', 'MANGO', 'Cotton On Women', 'Factorie'. See /api/catalog.
price_min number (0–) Minimum price, in the country's currency (needs country)
price_max number (0–) Maximum price (budget), in the country's currency (needs country)
on_sale boolean true → only discounted products
size string Only products listing this size as available, e.g. 'M', '10', '32'
limit integer (1–30) Products to return — default 8
exclude string Comma-separated product_ids to leave out (already shown or rejected)

GET /api/products/{product_id}

One product plus its closest alternatives

Parameter Values Meaning
product_id string product_id from a previous result, e.g. 'hm:1757988' — required
similar integer (0–12) How many look-alikes to include — default 5

GET /api/catalog

What is in stock: counts per department, store, type, brand, colour; price range

Valid filter values with counts, under any filter combination.

Parameter Values Meaning
country za · us · gb The shop the person buys from: za = South Africa (prices in ZAR), us = United States (USD), gb = United Kingdom (GBP). Required for search; prices, sizes and delivery follow it.
department women · men · kids · baby Who it is for — gender / age group. Strongly recommended: without it departments mix.
store hm · co · zara · mango One retailer: hm = H&M, co = Cotton On, zara = Zara, mango = Mango. Omit for all.
type tops · t-shirts · shirts-blouses · knitwear · hoodies-sweats · coats-jackets · suits-blazers · dresses · jumpsuits · skirts · jeans · trousers · shorts · activewear · swimwear · sleepwear · underwear · socks-tights · shoes · bags · accessories Hard filter on garment type. Optional — the query text usually suffices.
colour black · white · grey · blue · green · red · pink · purple · yellow · orange · brown · beige · multi Hard filter on basic colour. For nuanced colours ('sage', 'rust') put them in q instead.
brand string Exact brand, e.g. 'H&M', 'ZARA', 'MANGO', 'Cotton On Women', 'Factorie'. See /api/catalog.
price_min number (0–) Minimum price, in the country's currency (needs country)
price_max number (0–) Maximum price (budget), in the country's currency (needs country)
on_sale boolean true → only discounted products
size string Only products listing this size as available, e.g. 'M', '10', '32'

POST /api/images

Upload a photo to search by (multipart field 'file')

Filter values in the catalogue now

  • country: za (South Africa) 7 560, us (United States) 5 517, gb (United Kingdom) 2 169
  • department: women 8 524, kids 3 245, men 2 212, baby 1 213
  • store: co (Cotton On) 12 165, hm (H&M) 3 081
  • type: t-shirts 2 890, accessories 2 094, trousers 1 266, underwear 1 052, swimwear 989, shorts 930, jeans 873, hoodies-sweats 698, tops 673, sleepwear 606, knitwear 575, coats-jackets 448, shirts-blouses 366, dresses 356, jumpsuits 323, socks-tights 295, shoes 243, skirts 200, bags 153, suits-blazers 55, activewear 31
  • colour: multi 6 192, black 1 514, blue 1 390, grey 1 328, white 859, yellow 730, brown 521, pink 423, red 381, beige 359, green 247, purple 139, orange 33
  • brand (top): cotton on kids 3 514, body 3 091, h&m 3 081, cotton on women 2 207, rubi 1 687, cotton on men 1 665, cotton on 1

Product fields

  • product_id — Stable id ':' (ZA) or '-:' ('zara-us:…'). Use it in /api/products/{product_id}[/similar|/tailor] and in exclude
  • title — string
  • brand — string
  • store — Retailer name, e.g. 'H&M'
  • store_code — hm | co | zara | mango
  • country — za | us | gb — which country's shop sells it (and ships within that country)
  • currency — ZAR | USD | GBP — every price of this product is in it
  • department — Gender / age group: women | men | kids | baby
  • product_type — string
  • colour — Retailer's colour name
  • colour_family — string
  • price — Current price, in currency
  • price_display — Price formatted for people, e.g. 'R1 299', '$49.90', '£25.99'
  • original_price — Pre-discount price when on sale
  • on_sale — boolean
  • discount_pct — number
  • sizes — Sizes listed as available when last checked
  • description — string
  • materials — string
  • image_url — string
  • tailor_url — The link to show people: tailor.ai page with a link to the store and 5 alternatives
  • store_url — Link to the retailer's product page, via tailor.ai/go (logged, then redirected)
  • links — object
  • card_markdown — Ready-to-paste markdown card for chat replies

Rules

  • Read-only and free: no accounts, no checkout. People buy on the retailer's site.
  • score isn't returned; result order is relevance within one response only.
  • Stock and prices come from the retailers' sites and can lag; say "check the store for current stock".
  • Be a good stylist: honest, specific, concise. Don't pad replies with every result.