LumenariLUMENARI
Documentación de la API

Referencia

La API de Lumenari expone nuestro motor de recomendación de kits como endpoints JSON. Autentícate con un token Bearer. El mismo motor que mueve el wizard del storefront.

Quickstart

  1. Inicia sesión y genera una API key. Ves la key completa una sola vez — guárdala.
  2. Pásala como Authorization: Bearer lmn_… en cada request.
  3. Usa los endpoints de abajo. El tier gratuito te da 100 llamadas al mes.
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()

Autenticación

Todos los endpoints requieren un token Bearer. Las keys son de 36 caracteres y llevan el prefijo lmn_. Administra tus keys en tu dashboard.

curljavascriptpython

curl

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

javascript

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

python

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

Las keys se almacenan hasheadas con SHA-256. No podemos recuperar una key perdida — revócala y genera una nueva.

Rate limiting

Cada request devuelve tres headers que puedes usar para ajustar el ritmo:

  • X-RateLimit-Limit — tope mensual de tu tier (o unlimited en Enterprise)
  • X-RateLimit-Remaining — llamadas restantes en este periodo de facturación
  • X-RateLimit-Reset — timestamp Unix cuando se recarga la cuota (día 1 del próximo mes, UTC)

Si llegas al tope, recibes HTTP 429 con un cuerpo de error estructurado y un Retry-After header (segundos).

Endpoints

POST/api/v1/recommend

Obtén recomendaciones de kits para una plataforma de IA + caso de uso.

Cuerpo del request

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

Ejemplo

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

Respuesta

{
  "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 los kits del catálogo.

Parámetros de query

  • limit — Tamaño de página, por defecto 50, máx. 100
  • offset — Offset de paginación
  • ai_target — Filtra a un solo target de IA — claude / chatgpt / etc.
  • keyword — Match por substring contra nombre + keywords

Ejemplo

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

Respuesta

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

Metadata completa de un kit, incluyendo la lista de archivos entregables.

Ejemplo

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

Respuesta

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

Contenido del kit concatenado como markdown. Solo para tier Pro y superiores.

Ejemplo

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

El tier gratuito devuelve 402 con código `tier_required`. Pro / Business / Enterprise devuelven el cuerpo markdown completo inline.

GET/api/v1/usage

Uso del mes actual de la cuenta llamante + desglose diario de 30 días.

Ejemplo

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

Respuesta

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

Cada respuesta de error tiene la misma forma:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly call limit of 100 exceeded. Upgrade your tier..."
  }
}
HTTPCódigoSignificado
400invalid_requestEl cuerpo o los parámetros fallaron la validación.
401missing_api_keySin header de Authorization.
401invalid_api_keyLa key está mal formada, no se reconoce o fue revocada.
402subscription_inactiveLa suscripción paga está past_due o cancelada.
402tier_requiredEl endpoint necesita tier Pro o superior.
404not_foundEl id/slug del kit no existe.
429rate_limit_exceededLlegaste al tope mensual de llamadas. Reintenta después del reset del periodo.
500internal_errorFalla del lado de Lumenari. Intenta de nuevo.
500content_unavailableFalta el contenido del kit en el servidor (por favor repórtalo).

Webhooks

Próximamente. Suscríbete a hello@lumenari.io para que te avisemos cuando salgan los webhooks (actualizaciones de catálogo, umbrales de uso, kits nuevos).