Entwicklerdokumentation

Drei Wege, auf den Modelldatenbestand zuzugreifen: die öffentliche REST-API, ein MCP-Server für Agentensysteme, und API-Schlüssel zur Authentifizierung gegen beide.

API-Schlüssel

Ein API-Schlüssel authentifiziert sowohl gegen POST /api/v1/recommend als auch gegen den MCP-Server, jeweils per Header „Authorization: Bearer <schlüssel>“.

Jeder Schlüssel hat ein Kontingent pro Kalendermonat (Default: 1.000 Anfragen). Eine Anfrage, die das Kontingent überschreitet, bekommt 429 — sie zählt dabei bereits mit.

Der volle Schlüsselwert wird nur einmal bei der Erzeugung angezeigt und danach nirgends gespeichert. Ein verlorener Schlüssel lässt sich nicht wiederherstellen, nur widerrufen und neu erstellen.

Schlüssel erstellen und verwalten

POST /api/v1/recommend

Strukturierte Anfrage, kein Freitext. Ohne „Authorization“-Header läuft die Anfrage anonym und ohne Kontingent; mit gültigem Schlüssel zählt sie gegen dein Monatskontingent.

Felder im Anfrage-Body

required_modalities

Pflicht-Modalitäten (Slugs, z. B. „text“, „image“).

required_capabilities

Pflicht-Capability-Slugs.

required_languages

Pflicht-Sprach-Slugs.

max_budget_amount / max_budget_currency

Monats-/Pauschalbudget — Betrag und Währung (EUR oder USD) nur zusammen, nie einzeln.

compliance_interests

Compliance-Fakt-Slugs. Die aktuell aktive Gewichtung zeigt /ranking.

exclude_deprecated

Abgekündigte Modelle aus dem Ergebnis ausschließen.

Fehlercodes

• 401: Schlüssel unbekannt oder widerrufen (nur bei gesendetem, aber ungültigem Schlüssel — ohne Header bleibt die Anfrage anonym).
• 429: Monatskontingent überschritten.
• 422: Anfrage entspricht nicht dem erwarteten Format.

Im Playground ausprobieren

Vollständige OpenAPI-Referenz unter /docs (Swagger) — aktuell nur aus dem internen Netz erreichbar, nicht über die öffentliche Domain.

MCP-Server (/mcp)

Für Agentensysteme wie Hermes: ein MCP-Server per Streamable-HTTP-Transport unter /mcp. Authentifizierung ist hier Pflicht, über denselben API-Schlüssel wie oben.

Tool: recommend_model

Nimmt „task“ (Freitext, keyword-basiert ausgewertet wie bei /search) und optional „constraints“ entgegen.

Vier Constraints aus dem Flaggschiff-Beispiel: processing_region, dpa_required, training_on_input, max_eur_per_1k.

Jedes angefragte Kriterium kommt in der Antwort mit einem eigenen Status zurück: „filtered“ (schließt Modelle hart aus) oder „informational_only“ (wird nur angezeigt, filtert nicht). Nach heutigem Datenbestand filtert nur dpa_required hart — die anderen drei sind informativ.