tailor.ai

Plain-text version: /llms.txt · JSON: /api/schema

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 62 676 products in stock (2 343 on sale), in these countries' shops:

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:

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

Product fields

Rules