# looks.nyc

> The style index of New York menswear: an API and MCP server that maps menswear boutiques in SoHo, Nolita, Williamsburg, East Williamsburg and Bushwick — what each shop sells, its point of view, and real prices — for AI agents and apps.

looks.nyc is an API, not a store. It answers questions like "where can I find a heavyweight chore coat under $300?" or "which shops carry Japanese selvedge denim?" with items that link straight to each shop's own product page.

- Every indexed item has: category, subcategory, materials, colors, fit, season weight, details, origin, price, sale price, sizes in stock.
- Every boutique has: aesthetics (weighted, from a fixed 19-label vocabulary), four character scales (refined↔rugged, quiet↔loud, serious↔playful, classic↔experimental), store model, a price tier computed from observed prices, socials, and a readable markdown profile.
- Style labels are model judgments with dates; prices and stock come from shop catalogs and change. Always check the shop link before telling a user something is available.
- Requests are strict: unknown parameters or enum values return a 400 that names the allowed values (never silently ignored); `retailer` accepts slugs or display names; every search echoes `applied_filters` so you can verify what was applied.
- Defaults keep results useful: only menswear-relevant shops (`relevance` core+plausible; override with `relevance=`), no duplicates, fee/gift-card lines or bad-price rows (`include_flagged=true` to see them). Prices are as listed in each item's `currency`; non-USD items stay visible but `min_price`/`max_price` and price sorts cover USD-priced items only (`price_usd` is null for the others).
- Free to use (independently funded). **Get a key yourself, no account:** `POST https://api.looks.nyc/v1/keys` (no auth, no body) returns `201 {"key": "lk_…", "key_id": N, ...}` with REST/MCP usage. The key is shown once; store it. Free keys: 30 requests/minute and 3,000/month. Humans: https://looks.nyc/keys. Requests use `Authorization: Bearer lk_…`.
- Privacy by design: queries are never stored or logged. The API keeps only anonymous per-day counts of vocabulary terms (query intent such as "corduroy" or "outerwear") for trends, deleted automatically after at most 90 days — no query text, no IP addresses, no per-key history.

## API

- `POST /v1/keys`: get a free key (no auth, no body; 201 → `key`, `key_id`, limits, usage)
- [OpenAPI 3.1 spec](https://looks.nyc/openapi.json): full REST contract (base URL https://api.looks.nyc)
- [API catalog (RFC 9727)](https://looks.nyc/.well-known/api-catalog): machine-readable discovery
- `GET /v1/products/search`: items; `q` (web-search syntax) + filters relevance, include_flagged, category, gender, min_price, max_price, material, color, brand, retailer, aesthetic, in_stock, on_sale, sort, limit, cursor
- `GET /v1/retailers`: boutiques by aesthetic, store_model, price_tier
- `GET /v1/retailers/{slug}`: full profile (profile_md)
- `GET /v1/products/{retailer}/{id}`: one item with price history
- `GET /v1/vocab`: the vocabulary (aesthetic definitions, scales, categories)

## MCP

- Remote MCP server: https://mcp.looks.nyc (streamable HTTP, bearer auth)
- Tools: `search_products`, `search_retailers`, `get_retailer`, `get_product`, `get_vocab`

## Aesthetics vocabulary

American workwear, French workwear, Japanese Americana, artisanal craft, Ivy/prep, British country, heritage sportswear, streetwear, skate, surf/coastal, outdoor/gorpcore, techwear, Parisian minimal, quiet luxury, sartorial tailoring, relaxed tailoring, avant-garde, vintage/archive, western.

## Optional

- [Home](https://looks.nyc/)
- [Privacy policy](https://looks.nyc/privacy)
- [Terms of use](https://looks.nyc/terms)
- Contact: hello@looks.nyc