Get Started
最初の 1 リクエストまで
サインアップして API キーを発行し、八訂準拠の食品データを叩くまでを なぞります。各ステップに cURL / JavaScript / Python のコピペ例が あります。
例のベース URL は http://localhost:8787（pnpm dev のローカル）です。本番では、デプロイした成分 API のベース URL に 置き換えてください。
サインアップ
メール＋パスワードでアカウントを作成します。 メール検証は無効なので、サインアップ成功で即ログイン状態になります（成功応答の
Set-Cookie がセッション）。次の キー発行で使うので、Cookie を必ず保存してください。# -c でセッション Cookie を cookies.txt に保存（次のキー発行で使う）
curl -i -c cookies.txt -X POST http://localhost:8787/api/auth/sign-up/email \
-H 'content-type: application/json' \
-d '{"email":"me@example.com","password":"password1234","name":"me"}'API キーを発行
ログイン状態（セッション Cookie）で
POST /v1/keys を叩くとキーを発行できます。 平文キー（key）は発行時の応答に 1 度だけ含まれます。サーバは SHA-256 ハッシュしか保存しないため、 控え忘れた場合は失効させて再発行してください。# -b で保存済み Cookie を送信。応答の "key"（平文）は**この 1 度だけ**返る。
curl -X POST http://localhost:8787/v1/keys -b cookies.txt \
-H 'content-type: application/json' \
-d '{"name":"my first key"}'
# → {"id":"...","name":"my first key","keyPrefix":"fnk_xxxx","tier":"free","key":"fnk_<平文>"}最初のリクエスト
発行したキーを
X-API-Key ヘッダに付けて、データルートを叩きます。栄養値は種別（kind）を保持していて、測定値は { kind, value, unit }、微量・未測定は値を持たず{ kind, unit } で返ります。# 発行したキーを X-API-Key ヘッダに付けてデータルートを叩く。
curl "http://localhost:8787/v1/foods/01001" \
-H "X-API-Key: fnk_xxxxxxxxxxxxxxxx"応答（抜粋・GET /v1/foods/01001・既定の core）:
{
"foodNumber": "01001",
"name": "アマランサス 玄穀",
"groupId": "01",
"nutrients": {
"energy_kcal": { "kind": "measured", "value": 343, "unit": "kcal" },
"protein": { "kind": "measured", "value": 12.7, "unit": "g" },
"fat": { "kind": "measured", "value": 6, "unit": "g" },
"dietaryFiber": { "kind": "measured", "value": 7.4, "unit": "g" },
"carbohydrate": { "kind": "measured", "value": 64.9, "unit": "g" },
"salt": { "kind": "measured", "value": 0, "unit": "g" }
},
"portions": []
}kind は種別を保持します（数値に潰しません）。値を持つ 種別と持たない種別があります:
// 測定値（value あり）
{ "kind": "measured", "value": 7.4, "unit": "g" }
// 推定値（括弧付き）も value あり
{ "kind": "estimated", "value": 11.3, "unit": "g" }
// 微量 Tr は value を持たない
{ "kind": "trace", "unit": "mg" }
// 未測定（- または空欄）も value なし
{ "kind": "notMeasured", "unit": "µg" }お試しトークン（認証なしで試す）
アカウントを作らずに試したいときは、お試しトークンが使えます。
POST /v1/trial-token に Turnstile の ウィジェットトークンを渡すと短命トークン（24 時間／生涯 30 リクエスト）が返るので、Authorization: Bearer で渡します。※ Turnstile のフロント側ウィジェットは今後対応予定です。 現在は取得済みのウィジェットトークンを差し込んでお試しください。# 1) Turnstile を 1 回解いて得たウィジェットトークンを渡し、短命トークンを得る。
curl -X POST http://localhost:8787/v1/trial-token \
-H 'content-type: application/json' \
-d '{"turnstileToken":"<widget token>"}'
# → {"token":"<payload>.<sig>","expiresAt":"..."}
# 2) 得たトークンを Authorization: Bearer で渡してデータルートを叩く。
curl "http://localhost:8787/v1/foods?q=アマ&limit=5" \
-H 'Authorization: Bearer <payload>.<sig>'