LumenariLUMENARI
APIドキュメント

リファレンス

Lumenari APIは、キット推薦エンジンをJSONエンドポイントとして提供します。Bearerトークンで認証します。ストアフロントのウィザードを支えるのと同じエンジンです。

クイックスタート

  1. サインインしてAPIキーを発行してください。完全なキーは1度だけ表示されます — 必ず保存してください。
  2. すべてのリクエストで Authorization: Bearer lmn_… として送信します。
  3. 下記のエンドポイントを使ってください。無料プランでは月100コールまでご利用いただけます。
curljavascriptpython

curl

curl https://lumenari.io/api/v1/recommend \
  -H "Authorization: Bearer lmn_..." \
  -H "Content-Type: application/json" \
  -d '{"ai_platform":"claude","use_case":"shipping a SaaS on Next.js"}'

javascript

const res = await fetch("https://lumenari.io/api/v1/recommend", {
  method: "POST",
  headers: {
    "Authorization": "Bearer lmn_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ai_platform: "claude",
    use_case: "shipping a SaaS on Next.js",
  }),
});
const data = await res.json();

python

import requests

res = requests.post(
    "https://lumenari.io/api/v1/recommend",
    headers={"Authorization": "Bearer lmn_..."},
    json={
        "ai_platform": "claude",
        "use_case": "shipping a SaaS on Next.js",
    },
)
data = res.json()

認証

すべてのエンドポイントでBearerトークンが必要です。キーは36文字で、 lmn_ から始まります。キーの管理は ダッシュボード から行えます。

curljavascriptpython

curl

# Header on every request
Authorization: Bearer lmn_a1b2c3d4e5f6...

javascript

headers: { "Authorization": "Bearer lmn_a1b2c3d4..." }

python

headers={"Authorization": "Bearer lmn_a1b2c3d4..."}

キーはSHA-256でハッシュ化して保存しています。紛失したキーは復元できません — 失効させて新しいキーを発行してください。

レート制限

各リクエストには、バックオフに使える3つのヘッダーが返されます:

  • X-RateLimit-Limit — 契約プランの月間上限(Enterpriseの場合は unlimited)
  • X-RateLimit-Remaining — 当該請求期間に残っているコール数
  • X-RateLimit-Reset — クォータがリセットされるUnixタイムスタンプ(翌月1日、UTC)

上限に達するとHTTP 429が返り、構造化エラーボディと Retry-After ヘッダー(秒単位)が含まれます。

エンドポイント

POST/api/v1/recommend

AIプラットフォーム + ユースケースに対するキット推薦を取得します。

リクエストボディ

{
  "ai_platform": "claude",   // or chatgpt | codex | gemini | cursor | any
  "use_case": "shipping a SaaS on Next.js",
  "max_results": 3          // optional, default 3, max 10
}

例

curljavascriptpython

curl

curl https://lumenari.io/api/v1/recommend \
  -H "Authorization: Bearer lmn_..." \
  -H "Content-Type: application/json" \
  -d '{"ai_platform":"claude","use_case":"shipping a SaaS","max_results":3}'

javascript

const r = await fetch("https://lumenari.io/api/v1/recommend", {
  method: "POST",
  headers: {
    "Authorization": "Bearer lmn_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ai_platform: "claude",
    use_case: "shipping a SaaS",
    max_results: 3,
  }),
}).then(r => r.json());

python

r = requests.post(
    "https://lumenari.io/api/v1/recommend",
    headers={"Authorization": "Bearer lmn_..."},
    json={
        "ai_platform": "claude",
        "use_case": "shipping a SaaS",
        "max_results": 3,
    },
).json()

レスポンス

{
  "recommendations": [
    {
      "kit_id": "ts-next-production",
      "kit_slug": "ts-next-production",
      "kit_name": "TypeScript + Next.js Production Pack",
      "score": 1.0,
      "reasoning": "Your stack matches this kit directly — App Router patterns and Supabase wiring."
    }
  ],
  "fallback": false
}
GET/api/v1/kits

カタログ内のすべてのキットのページネーション付き一覧。

クエリパラメータ

  • limit — ページサイズ、デフォルト50、最大100
  • offset — ページネーションのオフセット
  • ai_target — 単一のAIターゲットで絞り込み — claude / chatgpt など。
  • keyword — name + keywordsに対する部分一致

例

curljavascriptpython

curl

curl 'https://lumenari.io/api/v1/kits?limit=10&ai_target=claude' \
  -H "Authorization: Bearer lmn_..."

javascript

const r = await fetch(
  "https://lumenari.io/api/v1/kits?limit=10&ai_target=claude",
  { headers: { Authorization: "Bearer lmn_..." } },
).then(r => r.json());

python

r = requests.get(
    "https://lumenari.io/api/v1/kits",
    headers={"Authorization": "Bearer lmn_..."},
    params={"limit": 10, "ai_target": "claude"},
).json()

レスポンス

{
  "kits": [
    {
      "id": "ts-next-production",
      "slug": "ts-next-production",
      "name": "TypeScript + Next.js Production Pack",
      "tagline": "RLS-aware App Router patterns...",
      "description": "...",
      "price_cents": 1900,
      "currency": "cad",
      "ai_targets": ["claude-code", "claude", "cursor"],
      "personas": [...],
      "keywords": [...],
      "whats_inside": [...],
      "deliverables": ["SKILL.md", ...]
    }
  ],
  "pagination": { "total": 20, "limit": 50, "offset": 0 }
}
GET/api/v1/kits/{id_or_slug}

単一キットの完全なメタデータ(納品ファイル一覧を含む)。

例

curljavascriptpython

curl

curl https://lumenari.io/api/v1/kits/ts-next-production \
  -H "Authorization: Bearer lmn_..."

javascript

const r = await fetch(
  "https://lumenari.io/api/v1/kits/ts-next-production",
  { headers: { Authorization: "Bearer lmn_..." } },
).then(r => r.json());

python

r = requests.get(
    "https://lumenari.io/api/v1/kits/ts-next-production",
    headers={"Authorization": "Bearer lmn_..."},
).json()

レスポンス

{
  "kit": {
    "id": "ts-next-production",
    "slug": "ts-next-production",
    "name": "TypeScript + Next.js Production Pack",
    ...
    "deliverables": ["SKILL.md", "memory.md", ...]
  }
}
GET/api/v1/kits/{id_or_slug}/download

Markdown形式で連結されたキット内容。Pro以上のプランでのみ利用可能。

例

curljavascriptpython

curl

curl https://lumenari.io/api/v1/kits/ts-next-production/download \
  -H "Authorization: Bearer lmn_..." \
  -o ts-next-production.md

javascript

const r = await fetch(
  "https://lumenari.io/api/v1/kits/ts-next-production/download",
  { headers: { Authorization: "Bearer lmn_..." } },
);
const markdown = await r.text();

python

r = requests.get(
    "https://lumenari.io/api/v1/kits/ts-next-production/download",
    headers={"Authorization": "Bearer lmn_..."},
)
markdown = r.text

無料プランでは `tier_required` コードで402が返されます。Pro / Business / Enterpriseでは完全なMarkdown本文がそのまま返ります。

GET/api/v1/usage

呼び出し元アカウントの今月の利用状況 + 過去30日間の日次内訳。

例

curljavascriptpython

curl

curl https://lumenari.io/api/v1/usage \
  -H "Authorization: Bearer lmn_..."

javascript

const r = await fetch("https://lumenari.io/api/v1/usage", {
  headers: { Authorization: "Bearer lmn_..." },
}).then(r => r.json());

python

r = requests.get(
    "https://lumenari.io/api/v1/usage",
    headers={"Authorization": "Bearer lmn_..."},
).json()

レスポンス

{
  "tier": "pro",
  "tier_name": "Pro",
  "period_start": "2026-05-01T00:00:00.000Z",
  "period_end":   "2026-06-01T00:00:00.000Z",
  "calls_used": 1240,
  "calls_remaining": 8760,
  "monthly_limit": 10000,
  "daily_breakdown": [
    { "date": "2026-05-01", "calls": 12 },
    { "date": "2026-05-02", "calls": 89 }
  ]
}

エラーコード

すべてのエラーレスポンスは同じ構造です:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly call limit of 100 exceeded. Upgrade your tier..."
  }
}
HTTPコード意味
400invalid_requestボディまたはパラメータのバリデーションに失敗しました。
401missing_api_keyAuthorizationヘッダーがありません。
401invalid_api_keyキーの形式が不正、不明、または失効しています。
402subscription_inactive有料サブスクリプションが past_due または canceled です。
402tier_requiredこのエンドポイントはPro以上のプランが必要です。
404not_foundキットid / slugが存在しません。
429rate_limit_exceeded月間コール上限に到達しました。期間リセット後に再試行してください。
500internal_errorLumenari側の障害です。再試行してください。
500content_unavailableサーバー上にキットコンテンツが見つかりません(ご報告ください)。

Webhook

近日提供予定です。hello@lumenari.io を購読いただくと、Webhook(カタログ更新、利用状況のしきい値、新キット情報)が利用可能になった際にお知らせします。