00API · MCP

어떤 로거를 쓰셔도 기록은 여기로

직접 만든 프로그램, 아티산, AI 비서 — 무엇으로 로스팅하셔도 키 하나로 기록을 보내면 로스팅 일지가 알아서 쌓이고, 생두·로트를 지정하면 재고·원료수불부까지 채워집니다.

REST · MCP

01WHY

로그는 어디서 찍어도 됩니다

온도를 읽는 프로그램은 이제 누구나 만듭니다. 그다음이 귀찮죠. 보내 주시면 이것들이 알아서 됩니다.

로스팅 일지

날짜별 배치 수·투입량·배출량·감량률이 자동으로 쌓입니다.

재고 · 원료수불부

생두를 지정해서 보내면 생두는 빠지고 원두는 늘어나고, 출고 기록이 원장에 남습니다.

평소 범위 · 비교

앱에서 로스팅한 것과 똑같이 그래프·평소 범위·기록 비교를 쓸 수 있습니다.

02KEYS

API 키

키는 비밀번호와 같습니다. 만들 때 한 번만 보여 드리니 바로 복사해 두세요.

03QUICK START

3분 만에 보내 보기

아래에서 hl_로 시작하는 부분을 방금 만든 키로 바꾸세요. 온도는 °C, 무게는 그램, 시간은 투입 기준 초입니다.

curl -X POST https://www.hyper-log.cloud/api/v1/roasts \
  -H "Authorization: Bearer hl_여기에_키" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "에티오피아 구지 1.2kg",
    "bean": "Ethiopia Guji",
    "input_g": 1200, "output_g": 1020,
    "samples": [
      {"t": 0, "bt": 200.1, "et": 230.4},
      {"t": 60, "bt": 118.5, "et": 226.0},
      {"t": 300, "bt": 162.3, "et": 229.8},
      {"t": 690, "bt": 214.7, "et": 238.1}
    ],
    "events": {"turning_point": 76, "first_crack": 508, "drop": 690},
    "client_id": "batch-2026-09-29-01"
  }'

성공하면 201과 기록 주소가 돌아옵니다. 같은 client_id로 다시 보내면 새로 만들지 않고 같은 기록을 돌려줍니다 — 전송이 끊겨 다시 보내도 두 번 저장되지 않습니다.

04AI · MCP

AI 비서에 연결하기 (MCP)

Claude 같은 AI가 내 로스팅 기록을 직접 읽고 쓰게 할 수 있습니다.

Claude Code

claude mcp add --transport http hyper-log https://www.hyper-log.cloud/api/mcp \
  --header "Authorization: Bearer hl_여기에_키"

Claude 데스크톱 (설정 → 개발자 → 설정 편집)

{
  "mcpServers": {
    "hyper-log": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://www.hyper-log.cloud/api/mcp",
        "--header", "Authorization: Bearer hl_여기에_키"
      ]
    }
  }
}

Windows에서 연결이 안 되면 헤더의 공백 문제일 수 있습니다. mcp-remote 안내대로 "--header", "Authorization:${AUTH}" 로 바꾸고 env 에 "AUTH": "Bearer hl_…" 를 넣어 보세요.

이렇게 물어보세요

“지난주 에티오피아 배치들의 1차 크랙 시간과 감량률을 비교해 줘”
“방금 로스팅한 거 기록해 줘. 투입 1.2kg, 배출 1,020g, 1차 크랙 8분 25초, 배출 11분 30초”
“지금 생두 재고 중에 3kg 안 남은 거 알려 줘”
“국내에서 1kg에 2만 원 이하인 게이샤 찾아 줘”

쓸 수 있는 도구: 기록 목록 · 기록 하나(곡선) · 기록 저장 · 재고 · 생두 검색 · 다른 로스터와 비교

05FIELDS

보내는 값

이름	뜻
name	기록 이름
bean	원두 이름
machine	로스터기 이름
input_g / output_g	투입량 · 배출량 (그램)
samples	[{ "t": 초, "bt": 원두 온도, "et": 배기 온도 }] — 투입 전 예열은 음수 초("time" 도 됨). 최대 6,000점
events	{ "turning_point": 76, "dry_end": 277, "first_crack": 508, "drop": 692 } — 초. 아티산 이름(TP, DRY, FCs, FCe, SCs, DROP)도 됩니다. charge 가 0초가 아니면 모든 시간을 투입 기준으로 옮겨 저장합니다
unit	"C"(기본) 또는 "F"(대소문자 무관) — 화씨로 보내면 섭씨로 바꿔 저장합니다
roasted_at	로스팅한 시각. 시간대가 없으면 한국 시간으로 봅니다(예: 2026-09-28T09:10:00). 예전 기록을 옮길 때 쓰세요
coffee_id	재고의 원두 id — 투입·배출량과 함께 보내면 생두→원두 재고가 움직이고, 그 생두의 짝 로트로 원료수불부 출고가 남습니다. 지금 재고에서 빠지니 오래된 기록을 옮길 땐 빼고 보내세요
green_bean_lot_id	생두 로트 id — 원료수불부에 출고가 남습니다
client_id	내 프로그램의 기록 번호. 같은 값으로 다시 보내면 중복 저장되지 않습니다
notes	메모

06ENDPOINTS

주소 목록

POST	/api/v1/roasts	기록 하나 보내기
GET	/api/v1/roasts?limit=20&q=	내 기록 목록(최신순)
GET	/api/v1/roasts/{id}	기록 하나(온도 곡선 포함)
GET	/api/v1/inventory	원두 재고 · 생두 로트 (coffee_id·lot id 찾기)
GET	/api/v1/green-beans?q=	국내 공급사 생두 카탈로그(1kg 단가)
GET	/api/v1/benchmark	다른 로스터들의 보통 범위(3명 이상일 때)
GET	/api/v1/me	키 연결 확인
POST	/api/mcp	AI 비서 연결(MCP)

키 하나당 분당 120번 · 한 사람당 하루 500건 · 본문 1MB까지. AI 연결은 한 번에 20개 요청까지. 오류가 나면 무엇이 틀렸는지 details에 적어 돌려드립니다.