LumenariLUMENARI
Documentação da API

Referência

A API Lumenari expõe nosso motor de recomendação de kits como endpoints JSON. Autenticação por Bearer token. Mesmo motor que alimenta o wizard da loja.

Quickstart

  1. Faça login e gere uma API key. Você vê a key completa uma vez — salve.
  2. Passe como Authorization: Bearer lmn_… em toda requisição.
  3. Use os endpoints abaixo. O plano grátis te dá 100 chamadas por mês.
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()

Autenticação

Todos os endpoints exigem Bearer token. As keys têm 36 caracteres e prefixo lmn_. Gerencie keys no seu painel.

curljavascriptpython

curl

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

javascript

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

python

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

As keys são armazenadas como hash SHA-256. Não conseguimos recuperar uma key perdida — revogue e gere uma nova.

Rate limiting

Cada requisição devolve três headers que você pode usar para fazer back off:

  • X-RateLimit-Limit — limite mensal do seu plano (ou unlimited no Enterprise)
  • X-RateLimit-Remaining — chamadas restantes no período de cobrança
  • X-RateLimit-Reset — Unix timestamp de quando a cota renova (1º do próximo mês, UTC)

Se bater no limite, você recebe HTTP 429 com um corpo de erro estruturado e um header Retry-After (em segundos).

Endpoints

POST/api/v1/recommend

Recebe recomendações de kit para uma plataforma de IA + caso de uso.

Corpo da requisição

{
  "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
}

Exemplo

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()

Resposta

{
  "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

Lista paginada de todos os kits do catálogo.

Parâmetros de query

  • limit — Tamanho da página, padrão 50, máximo 100
  • offset — Offset de paginação
  • ai_target — Filtra por um único alvo de IA — claude / chatgpt / etc.
  • keyword — Match de substring contra nome + keywords

Exemplo

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()

Resposta

{
  "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}

Metadados completos de um único kit, incluindo a lista de arquivos entregáveis.

Exemplo

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()

Resposta

{
  "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

Conteúdo concatenado do kit em markdown. Apenas plano Pro ou superior.

Exemplo

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

O plano grátis devolve 402 com código `tier_required`. Pro / Business / Enterprise devolvem o corpo markdown completo inline.

GET/api/v1/usage

Uso do mês atual da conta que chama + detalhamento diário dos últimos 30 dias.

Exemplo

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()

Resposta

{
  "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 }
  ]
}

Códigos de erro

Toda resposta de erro tem a mesma forma:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly call limit of 100 exceeded. Upgrade your tier..."
  }
}
HTTPCódigoSignificado
400invalid_requestCorpo ou parâmetros falharam na validação.
401missing_api_keySem header Authorization.
401invalid_api_keyKey malformada, desconhecida ou revogada.
402subscription_inactiveAssinatura paga está past_due ou cancelada.
402tier_requiredEndpoint exige plano Pro ou superior.
404not_foundKit id/slug não existe.
429rate_limit_exceededLimite mensal de chamadas atingido. Tente após o reset do período.
500internal_errorFalha do lado Lumenari. Tente de novo.
500content_unavailableConteúdo do kit ausente no servidor (por favor, reporte).

Webhooks

Em breve. Inscreva-se em hello@lumenari.io para ser avisado quando os webhooks chegarem (atualizações de catálogo, limites de uso, novos kits).