LumenariLUMENARI
Documentation API

Référence

L'API Lumenari expose notre moteur de recommandation de kits sous forme d'endpoints JSON. Authentifiez-vous avec un Bearer token. Même moteur que celui qui anime le wizard de la boutique.

Quickstart

  1. Connectez-vous et générez une clé API. Vous voyez la clé complète une seule fois — sauvegardez-la.
  2. Passez-la en tant que Authorization: Bearer lmn_… sur chaque requête.
  3. Utilisez les endpoints ci-dessous. Le palier gratuit vous donne 100 appels par mois.
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()

Authentification

Tous les endpoints requièrent un Bearer token. Les clés font 36 caractères et sont préfixées par lmn_. Gérez vos clés depuis votre dashboard.

curljavascriptpython

curl

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

javascript

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

python

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

Les clés sont hachées au repos avec SHA-256. Nous ne pouvons pas récupérer une clé perdue — révoquez-la et générez-en une nouvelle.

Rate limiting

Chaque requête renvoie trois headers que vous pouvez utiliser pour ralentir :

  • X-RateLimit-Limit — quota mensuel de votre palier (ou unlimited en Enterprise)
  • X-RateLimit-Remaining — appels restants sur la période de facturation
  • X-RateLimit-Reset — timestamp Unix de réinitialisation du quota (1er du mois suivant, UTC)

Si vous atteignez le plafond, vous obtiendrez un HTTP 429 avec un corps d'erreur structuré et un header Retry-After (en secondes).

Endpoints

POST/api/v1/recommend

Obtenir des recommandations de kits pour une plateforme IA + un cas d'usage.

Corps de la requête

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

Exemple

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

Réponse

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

Liste paginée de tous les kits du catalogue.

Paramètres de requête

  • limit — Taille de page, par défaut 50, max 100
  • offset — Offset de pagination
  • ai_target — Filtrer par une cible IA — claude / chatgpt / etc.
  • keyword — Recherche de sous-chaîne dans le nom + les mots-clés

Exemple

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

Réponse

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

Métadonnées complètes d'un kit, incluant la liste des fichiers livrés.

Exemple

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

Réponse

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

Contenu du kit concaténé en markdown. Palier Pro et plus uniquement.

Exemple

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

Le palier gratuit renvoie 402 avec le code `tier_required`. Pro / Business / Enterprise renvoient le corps markdown complet inline.

GET/api/v1/usage

Usage du mois en cours du compte appelant + détail journalier sur 30 jours.

Exemple

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

Réponse

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

Codes d'erreur

Toutes les réponses d'erreur ont la même forme :

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly call limit of 100 exceeded. Upgrade your tier..."
  }
}
HTTPCodeSignification
400invalid_requestLe corps ou les paramètres ont échoué à la validation.
401missing_api_keyAucun header Authorization.
401invalid_api_keyClé mal formée, inconnue ou révoquée.
402subscription_inactiveAbonnement payant en past_due ou annulé.
402tier_requiredL'endpoint requiert le palier Pro ou plus.
404not_foundL'id/slug du kit n'existe pas.
429rate_limit_exceededPlafond mensuel d'appels atteint. Réessayez après réinitialisation.
500internal_errorErreur côté Lumenari. Réessayez.
500content_unavailableContenu du kit manquant sur le serveur (merci de le signaler).

Webhooks

Bientôt disponible. Abonnez-vous à hello@lumenari.io pour être notifié dès que les webhooks sortent (mises à jour du catalogue, seuils d'usage, nouveaux kits).