Seraphic Styler · Public API

For agents

Seraphic Styler keeps an editorially curated directory of 300 Vietnamese fashion houses — boutiques, ateliers, designer labels, tailors and markets, walked and recorded in person in Ho Chi Minh City. This page describes the public, read-only API that serves it, and the rules for quoting it honestly. It is written for AI agents and developers; a person browsing should use the directory itself.

Base URL

https://api.seraphicstyler.com

Machine-readable description: openapi.json (OpenAPI 3.1, includes these rules as info.x-agent-rules). Everything is GET only — POST, PUT and DELETE return 405. There is no write path and no authentication: the whole surface is public reference data.

Endpoints

Endpoint	Returns
`GET /v1/health`	Service status, dataset date, house count.
`GET /v1/houses`	Filter by `category`, `district`, `area`, `city`, `tier`, `access`, `occasion`, `material`, `status`, `priceMin`, `priceMax`. Paged with `limit` (max 300) and `offset`.
`GET /v1/houses/:id`	One house. An Instagram handle or domain works in place of the id.
`GET /v1/search?q=`	Plain-language search. Every result carries `reason` — the list of things it actually matched.
`GET /v1/resolve?url=`	Identify the house behind a pasted link, handle or id.
`GET /openapi.json`	This API, described for tooling.

Search explains itself

Known phrases become structured filters; anything left over is matched literally against the house name, notes and subcategory. Terms combine with AND. No language model is involved, so the same query always gives the same answer, and nothing is recommended that the data does not support.

GET /v1/search?q=premium+feminine+birthday+D3

{
  "query": "premium feminine birthday D3",
  "matchedOn": ["District 3", "Birthdays & celebrations", "Premium"],
  "textTerms": ["feminine"],
  "total": 3,
  "results": [
    { "id": "cocosin", "name": "Cocosin",
      "reason": ["District 3", "Premium", "Birthdays & celebrations", "Mentions feminine"] }
  ]
}

When a query matches nothing, the response says why rather than returning a bare zero: blockingTerms names any single constraint whose removal would rescue the search, and constraintSupport gives the number of houses behind each constraint on its own. Offer to drop a constraint; do not quietly substitute a different query.

Resolving a pasted link

/v1/resolve reads the URL it is given. It never requests it — no page is fetched, so a client's link is never replayed against a shop. A profile URL, a product URL, a bare handle and a house id all work; an Instagram post or reel link does not identify a house and returns matched: false with an explanation.

GET /v1/resolve?url=https://instagram.com/cocosin.official
{ "matched": true, "how": "instagram", "confidence": "high", "house": { … } }

confidence is high for an exact website, handle or id, and medium when the match came from the registrable domain rather than the exact hostname. Where two houses would claim the same domain, the directory returns no match instead of guessing between them.

Rules for agents

Treat status: "confirm-first" records as unverified. Say so when you present them. The address, hours or trading status is known to move.
Never claim current inventory, opening hours or an exact price unless the record contains it. Most records do not.
priceHint is a curated range in free text, sometimes scoped to one product type — "tees 300–700k₫" is the price of tees, not of everything. Quote priceHint.raw alongside any number you use.
An empty field means not recorded, not zero and not absent in reality. style is recorded for only a handful of houses; do not read its absence as a judgement.
lastVerified is null on every record: the source carries no per-record verification dates. Use sourceUpdated for dataset freshness, and do not present it as a per-house check.
Link back to Seraphic Styler and to the house's own sourceUrl.
Do not contact houses, make purchases, place orders or book appointments without explicit, visible approval from the person you are acting for. This API cannot do any of those things; neither should you on the strength of it.
Cache politely — responses carry Cache-Control: public, max-age=300.

On why these rules exist. Every record here was compiled by one person on foot. Saigon boutiques move, share addresses inside multi-brand buildings, and trade partly through direct messages. The data is deliberately honest about that uncertainty, and an agent that launders a "confirm first" record into a confident recommendation sends someone across a city to a closed door.

Field reference

Field	Values
`category`	`women`, `men`, `bridal`, `vintage`, `luxury`, `tailor`, `active`, `access`, `sleep`, `market`
`tier`	`mid`, `premium`, `luxury`, `couture`, or `null`
`access`	`walk-in`, `appointment`, `stockist`, `pop-up`, `online`
`status`	`listed` or `confirm-first`. Never an assertion that a shop is open right now.
`occasions`	`birthdays-celebrations`, `balls-formal`, `nightlife-parties`
`materials`	`cotton`, `silk`, `linen`, `hemp`, `tencel`
`city`	`SGN`, `HAN`, `VN`, `INTL`
`districts` / `areas`	Numbered districts as `D1`…`D12`; named areas such as Thảo Điền and Bình Thạnh in `areas`.

Terms

Free to read and to build on, for people and for agents alike. Attribute the directory to Seraphic Styler and link back. Please do not republish the dataset wholesale as your own, and do not use it to contact houses at scale — they are small businesses, and several are one person answering their own messages.

Something wrong in a record, or want a house added? seraphicstyler@gmail.com. Corrections are genuinely welcome; the directory is only as good as its last walk.

Seraphic Styler · The Saigon Fashion Directory · openapi.json · llms.txt