LumenariLUMENARI
API 文档

参考手册

Lumenari API 以 JSON 接口的形式提供我们的工具包推荐引擎。使用 Bearer Token 鉴权。与驱动商店向导的是同一引擎。

快速开始

  1. 登录 并生成一个 API 密钥。完整密钥只显示一次——请妥善保存。
  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 Token。密钥长度为 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 哈希存储。我们无法找回丢失的密钥——请撤销并重新生成。

速率限制

每次请求都会返回三个响应头,便于您退避重试:

  • 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 — 对名称 + 关键词进行子串匹配

示例

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

免费套餐会返回 402,错误代码 `tier_required`。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_key缺少 Authorization 请求头。
401invalid_api_key密钥格式错误、未知或已撤销。
402subscription_inactive付费订阅状态为 past_due 或已取消。
402tier_required该接口需要 Pro 套餐或更高版本。
404not_found工具包 id/slug 不存在。
429rate_limit_exceeded月度调用上限已达。请在周期重置后重试。
500internal_errorLumenari 端故障。请稍后重试。
500content_unavailable服务器上工具包内容缺失(请告知我们)。

Webhook

即将上线。订阅 hello@lumenari.io,当 Webhook 上线(目录更新、用量阈值、新工具包)时,我们会通知您。