{"info":{"description":"Search live authenticated Herm\u00e8s Birkin resale inventory, resolve buy URLs, get recommendations, market prices, and multilingual news.","title":"BirkinBagStock API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/.well-known/source-index.json":{"get":{"operationId":"getBirkinWellKnownSourceIndex","responses":{"200":{"description":"Alias of /data/source-index.json for tool and crawler discovery."}},"summary":"Get well-known source page index"}},"/api/v1/alternatives/search":{"get":{"operationId":"searchBirkinAlternatives","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":8,"maximum":20,"minimum":1,"type":"integer"}}],"responses":{"200":{"description":"Source spec, live stats, and ranked alternatives."},"400":{"description":"Missing q"}},"summary":"Resolve a Birkin spec and return comparable alternatives"}},"/api/v1/alternatives/{slug}":{"get":{"operationId":"getBirkinAlternativeProfile","parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":8,"maximum":20,"minimum":1,"type":"integer"}}],"responses":{"200":{"description":"Source spec, live stats, and ranked alternatives."},"404":{"description":"Unknown profile"}},"summary":"Get alternatives for a canonical Birkin spec profile"}},"/api/v1/buy/{id}":{"get":{"operationId":"getBuyUrl","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Buy URL and merchant handoff instructions."}},"summary":"Resolve a listing to its canonical buy URL"}},"/api/v1/freshness":{"get":{"operationId":"getInventoryFreshness","responses":{"200":{"description":"Latest scrape summary and per-source health contract."}},"summary":"Get inventory source freshness and latest scrape health"}},"/api/v1/inventory":{"get":{"operationId":"searchBirkinBags","parameters":[{"in":"query","name":"size","schema":{"enum":[25,30,35,40],"type":"integer"}},{"in":"query","name":"color","schema":{"type":"string"}},{"in":"query","name":"leather","schema":{"type":"string"}},{"in":"query","name":"min_price","schema":{"type":"integer"}},{"in":"query","name":"max_price","schema":{"type":"integer"}},{"in":"query","name":"condition","schema":{"type":"string"}},{"in":"query","name":"merchant","schema":{"type":"string"}},{"in":"query","name":"sort","schema":{"enum":["best","newest","price_asc","price_desc"],"type":"string"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":500,"type":"integer"}}],"responses":{"200":{"description":"Live Birkin listings with detail_url and buy_url."}},"summary":"Search Birkin bag inventory"}},"/api/v1/listing/{id}":{"get":{"operationId":"getBirkinListing","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Listing specs, merchant, image, detail_url, and buy_url."}},"summary":"Get one Birkin listing"}},"/api/v1/listing/{id}/alternatives":{"get":{"operationId":"getBirkinListingAlternatives","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":6,"maximum":12,"minimum":1,"type":"integer"}}],"responses":{"200":{"description":"Listing, cohort stats, lower-priced alternatives, similar listings, and spec profile context."},"404":{"description":"Listing not found"}},"summary":"Get alternatives for one Birkin listing"}},"/api/v1/news":{"get":{"operationId":"getBirkinNews","parameters":[{"in":"query","name":"locale","schema":{"enum":["en","es","fr","de","it","pt","ja","zh","ko","nl","tr","ar"],"type":"string"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":50,"type":"integer"}}],"responses":{"200":{"description":"Cached multilingual news briefs with internal URLs."}},"summary":"Get multilingual Birkin market news"}},"/api/v1/recommend":{"get":{"operationId":"recommendBirkin","parameters":[{"in":"query","name":"budget","schema":{"type":"integer"}},{"in":"query","name":"use","schema":{"enum":["everyday","evening","investment","travel","gift","work"],"type":"string"}}],"responses":{"200":{"description":"Recommended specs and matching live listings."}},"summary":"Recommend a Birkin by budget and use case"}},"/data/api-directory.json":{"get":{"operationId":"getBirkinApiDirectory","responses":{"200":{"description":"Agent and CLI integration map."}},"summary":"Get API directory"}},"/data/birkin-alternatives.json":{"get":{"operationId":"getBirkinAlternativesIndex","responses":{"200":{"description":"Canonical Birkin alternative profiles with live stats."}},"summary":"Get Birkin alternatives profile index"}},"/data/birkin-price-appreciation-index.json":{"get":{"operationId":"getBirkinMatchedPriceIndex","responses":{"200":{"description":"Same-SKU repeat-listing price index and time series."}},"summary":"Get matched repeat-listing price index"}},"/data/dataset-card.md":{"get":{"operationId":"getBirkinDatasetCard","responses":{"200":{"description":"Markdown dataset card for GitHub, Kaggle, HuggingFace, and registry submissions."}},"summary":"Get markdown dataset card"}},"/data/dataset-metadata.json":{"get":{"operationId":"getBirkinDatasetMetadata","responses":{"200":{"description":"Schema.org/DataPackage metadata for dataset mirrors, crawlers, and citation tools."}},"summary":"Get dataset metadata"}},"/data/listing-price-history/{listing_id}.json":{"get":{"operationId":"getBirkinListingPriceHistory","parameters":[{"in":"path","name":"listing_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Observed daily price path and cuts/increases for one listing."},"404":{"description":"Listing not found"}},"summary":"Get listing-level price history"}},"/data/new-arrivals.json":{"get":{"operationId":"getNewBirkinArrivals","responses":{"200":{"description":"Newest and recently updated product rows with timestamps."}},"summary":"Get newest and recently updated Birkin products"}},"/data/news-locales.json":{"get":{"operationId":"getBirkinNewsLocales","responses":{"200":{"description":"Locale map with API URLs, crawlable HTML pages, and recent examples for each news language."}},"summary":"Get multilingual news locale index"}},"/data/price-history/{spec_slug}.json":{"get":{"operationId":"getBirkinSpecPriceHistory","parameters":[{"in":"path","name":"spec_slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Median asking-price history and observed listing cuts for one Birkin spec."},"404":{"description":"Spec not found"}},"summary":"Get spec-level price history"}},"/data/source-index.json":{"get":{"operationId":"getBirkinSourceIndex","responses":{"200":{"description":"Machine-readable source-page groups for listings, sponsored pages, content, comparisons, and data endpoints."}},"summary":"Get source page index"}},"/data/spec-index.json":{"get":{"operationId":"getBirkinSpecIndex","responses":{"200":{"description":"High-intent merchant, budget, size, color, leather, and hardware page map."}},"summary":"Get grouped Birkin spec landing-page index"}},"/datapackage.json":{"get":{"operationId":"getBirkinDataPackage","responses":{"200":{"description":"Frictionless Data Package resources for BirkinBagStock public datasets."}},"summary":"Get Frictionless Data Package"}},"/feed.json":{"get":{"operationId":"getBirkinJsonFeed","responses":{"200":{"description":"JSON Feed v1.1 of recent BirkinBagStock content."}},"summary":"Get JSON Feed"}},"/llm-source.json":{"get":{"operationId":"getBirkinLlmSource","responses":{"200":{"description":"Small source manifest for ChatGPT, Claude, Codex, CLIs, and vibecoders."}},"summary":"Get compact LLM source manifest"}},"/source-pages":{"get":{"operationId":"getBirkinSourcePages","responses":{"200":{"description":"HTML source hub for crawlers, retrievers, CLIs, and builders."}},"summary":"Get crawlable source page hub"}},"/source.json":{"get":{"operationId":"getBirkinSourcePack","responses":{"200":{"description":"Source pack for retrievers and data products."}},"summary":"Get source pack"}}},"servers":[{"url":"https://birkinbagstock.com"}]}