{"openapi":"3.1.0","info":{"title":"SakeMe public discovery API","version":"1.0.0","description":"Read-only public sake catalog and editorial food pairings. No A2A task protocol, transactions, stock guarantees or user data."},"servers":[{"url":"https://sakeme.kr"}],"security":[],"paths":{"/api/v1/discover":{"get":{"operationId":"discoverSake","summary":"Find food pairing guides and separate sake-name matches","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"example":"방어회에 먹을 사케 추천해줘"}],"responses":{"200":{"description":"Guides, catalog matches, or clarification; an empty result is valid","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"const":"1.0"},"intent":{"enum":["food_pairing","recommendation","catalog_search"]},"guides":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"food":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"summary":{"type":"string"},"style":{"type":"string"},"reason":{"type":"string"},"temperature":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"text":{"type":"string"}},"required":[]}},"tags":{"type":"array","items":{"type":"string"}},"evidence_type":{"const":"editorial_inference"},"method":{"type":"string"},"reviewed_at":{"type":"string","format":"date"},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["title","url"]}},"candidates":{"type":"array","items":{"type":"object","properties":{"entity_type":{"const":"product"},"id":{"type":"integer"},"name":{"type":"string"},"name_ja":{"type":"string"},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"},"reason":{"type":"string"},"evidence_type":{"const":"editorial_inference"},"manufacturer_description":{"type":"string"},"manufacturer_source":{"type":"string","format":"uri"},"price":{"type":"null"},"availability":{"const":"unknown"}},"required":["id","url","reason","evidence_type","manufacturer_source","availability"]}}},"required":["id","url","summary","evidence_type","reviewed_at","sources","candidates"]}},"suggested_queries":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"url":{"type":"string","format":"uri"},"reason":{"const":"similar_spelling"},"requires_confirmation":{"const":true}},"required":["query","url","reason","requires_confirmation"]}},"clarification":{"anyOf":[{"type":"null"},{"type":"object","properties":{"question":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["question","url"]}]},"catalog_result_count":{"type":"integer"},"catalog_results":{"type":"array","items":{"type":"object","properties":{"entity_type":{"enum":["product","brand","brewery"]},"id":{"type":"integer"},"name":{"type":["string","null"]},"names":{"type":"object","properties":{"ko":{"type":["string","null"]},"ja":{"type":["string","null"]},"kana":{"type":["string","null"]},"romanization":{"type":["string","null"]}},"required":[]},"brand_id":{"type":["integer","null"]},"grade":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"}},"required":["entity_type","id","url"]}},"limitations":{"type":"array","items":{"type":"string"}},"attribution":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"instruction":{"type":"string"}},"required":[]}},"required":["schema_version","intent","guides","catalog_results","catalog_result_count","limitations"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":[]}}}},"503":{"description":"Temporary catalog error; retry after Retry-After seconds","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":[]}}}}}}},"/api/v1/products/{id}":{"get":{"operationId":"getSakeProduct","summary":"Read a canonical product and sourced aliases","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":35767}],"responses":{"200":{"description":"Public product","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"const":"1.0"},"entity_type":{"const":"product"},"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"names":{"type":"object","properties":{"ko":{"type":["string","null"]},"ja":{"type":["string","null"]}},"required":[]},"food_pairings":{"type":"array","items":{"type":"object","properties":{"food":{"type":"string"},"url":{"type":"string","format":"uri"},"reason":{"type":"string"},"evidence_type":{"const":"editorial_inference"},"method":{"type":"string"},"reviewed_at":{"type":"string","format":"date"},"manufacturer_description":{"type":"string"},"manufacturer_source":{"type":"string","format":"uri"}},"required":["food","url","reason","evidence_type","method","reviewed_at","manufacturer_source"]}},"verified_names":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"locale":{"type":"string"},"kind":{"type":"string"},"source_url":{"type":"string","format":"uri"},"verified_at":{"type":"string","format":"date-time"}},"required":[]}},"attributes":{"type":"object","properties":{"grade":{"type":["string","null"]},"polishing_ratio":{"type":["number","null"]},"alcohol_percentage":{"type":["number","null"]},"rice":{"type":["string","null"]},"nama":{"type":["boolean","null"]}},"required":[]},"brand":{"type":["object","null"],"description":"Public brand, brewery and area identifiers and names."},"evidence":{"type":"object","properties":{"catalog":{"type":"string"},"names":{"type":"string"},"taste":{"type":"string"}},"required":[]},"price":{"type":"null"},"availability":{"const":"unknown"}},"required":["schema_version","entity_type","id","url","attributes","verified_names","availability"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":[]}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":[]}}}},"503":{"description":"Temporary catalog error; retry after Retry-After seconds","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":[]}}}}}}}},"externalDocs":{"description":"Usage, evidence and attribution","url":"https://sakeme.kr/developers"}}