SakeMe 공개 데이터 API
에이전트가 사케 이름과 음식 페어링을 조회하고, 사용자가 근거를 확인할 수 있는 페이지로 연결하도록 만든 읽기 전용 API입니다. 로그인 없이 공개 카탈로그만 제공합니다.
질문으로 찾기
GET /api/v1/discover?q=방어회에 먹을 사케 추천해줘
q는 1~200자입니다. 음식 별칭을 인식하면 guides에 설명·제품 후보·출처를 반환합니다. catalog_results는 별도의 이름 검색 결과이며, 음식과 어울린다고 판정한 목록이 아닙니다. “오늘의 사케 추천”처럼 조건이 없으면 음식과 취향을 묻는 clarification을 제공합니다. 임의의 모든 질문을 이해하는 언어 모델은 아닙니다.
제품 조회
GET /api/v1/products/35767
제품 ID와 원문 URL, 이름, 확인된 별칭의 출처, 공개 속성을 반환합니다. 모르는 가격·재고는 null 또는 unknown입니다. is_nama=false였던 과거 데이터는 확인된 화입으로 단정하지 않고 nama=null로 제공합니다.
정보를 해석하는 방법
- 추천 이유는 editorial_inference, 제조사 설명은 별도 필드입니다. 직접 시음이나 제조사 보증으로 바꾸어 설명하지 마세요.
- 응답의 guide/product URL을 출처로 연결하면 사용자가 근거와 상세 정보를 확인할 수 있습니다.
- 브랜드 평점·맛을 모든 제품의 평점·맛으로 옮기지 마세요. 가격·국내 판매처·재고는 현재 확인하지 않습니다.
- 만 19세 이상을 위한 사케 정보입니다. API는 구매·발주를 처리하지 않으며 개인 기록을 제공하지 않습니다.
연동과 운영
응답은 schema_version 1.0이며 JSON·UTF-8 형식입니다. GET만 지원하고 최대 8개 카탈로그 후보를 반환합니다. CORS는 공개 읽기를 허용합니다. 캐시 지시를 지키고, 503에는 Retry-After에 따라 재시도하세요. 잘못된 요청은 400, 없는 제품은 404입니다. 웹 조회를 사람의 수요 이벤트로 기록하지 않습니다.
현재 서비스는 일반 HTTP API입니다. A2A 작업·메시지 처리 서버나 MCP 서버는 구현하지 않았습니다. 해당 규격을 지원하는 것처럼 Agent Card를 게시하지 않습니다. API 추가만으로 특정 AI 서비스의 추천·인용이 보장되는 것도 아닙니다.