LumenariLUMENARI
API-Dokumentation

Referenz

Die Lumenari API stellt unsere Kit-Empfehlungs-Engine als JSON-Endpunkte bereit. Authentifizierung per Bearer-Token. Dieselbe Engine, die auch den Storefront-Wizard antreibt.

Quickstart

  1. Einloggen und einen API-Key erzeugen. Sie sehen den vollständigen Key nur einmal — speichern Sie ihn.
  2. Übergeben Sie ihn als Authorization: Bearer lmn_… bei jeder Anfrage.
  3. Nutzen Sie die unten beschriebenen Endpunkte. Der kostenlose Tarif gibt Ihnen 100 Aufrufe pro Monat.
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()

Authentifizierung

Alle Endpunkte erfordern ein Bearer-Token. Keys haben 36 Zeichen und beginnen mit lmn_. Keys verwalten Sie unter Ihrem Dashboard.

curljavascriptpython

curl

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

javascript

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

python

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

Keys werden im Ruhezustand mit SHA-256 gehasht. Einen verlorenen Key können wir nicht wiederherstellen — widerrufen Sie ihn und erzeugen Sie einen neuen.

Rate Limiting

Jede Anfrage liefert drei Header, mit denen Sie zurückregulieren können:

  • X-RateLimit-Limit — monatliches Limit Ihres Tarifs (oder unlimited bei Enterprise)
  • X-RateLimit-Remaining — verbleibende Aufrufe in diesem Abrechnungszeitraum
  • X-RateLimit-Reset — Unix-Zeitstempel, wenn das Kontingent zurückgesetzt wird (1. des Folgemonats, UTC)

Wenn Sie das Limit erreichen, erhalten Sie HTTP 429 mit einem strukturierten Fehlerbody und einem Retry-After Header (in Sekunden).

Endpunkte

POST/api/v1/recommend

Kit-Empfehlungen für eine KI-Plattform und einen Anwendungsfall holen.

Request Body

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

Beispiel

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

Response

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

Paginierte Liste aller Kits im Katalog.

Query-Parameter

  • limit — Seitengröße, Standard 50, Maximum 100
  • offset — Offset für die Paginierung
  • ai_target — Filter auf ein einzelnes KI-Ziel — claude / chatgpt / etc.
  • keyword — Teilstring-Treffer in Name und Keywords

Beispiel

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

Response

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

Vollständige Metadaten zu einem einzelnen Kit, inklusive Dateiliste.

Beispiel

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

Response

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

Zusammengeführter Kit-Inhalt als Markdown. Nur ab Pro-Tarif.

Beispiel

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

Der kostenlose Tarif liefert 402 mit dem Code `tier_required`. Pro / Business / Enterprise liefern den vollständigen Markdown-Body inline aus.

GET/api/v1/usage

Aktuelle Monatsnutzung des aufrufenden Accounts plus tägliche Aufschlüsselung der letzten 30 Tage.

Beispiel

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

Response

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

Fehlercodes

Jede Fehlerantwort hat dieselbe Form:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly call limit of 100 exceeded. Upgrade your tier..."
  }
}
HTTPCodeBedeutung
400invalid_requestBody oder Parameter haben die Validierung nicht bestanden.
401missing_api_keyKein Authorization-Header.
401invalid_api_keyKey ist fehlerhaft, unbekannt oder widerrufen.
402subscription_inactiveBezahltes Abo ist past_due oder gekündigt.
402tier_requiredEndpunkt erfordert Pro-Tarif oder höher.
404not_foundKit-ID/Slug existiert nicht.
429rate_limit_exceededMonatliches Aufruflimit erreicht. Nach Reset erneut versuchen.
500internal_errorFehler auf Lumenari-Seite. Bitte erneut versuchen.
500content_unavailableKit-Inhalt fehlt auf dem Server (bitte melden).

Webhooks

In Kürze. Abonnieren Sie hello@lumenari.io, um benachrichtigt zu werden, sobald Webhooks ausgeliefert werden (Katalog-Updates, Nutzungs-Schwellen, neue Kits).