RoxyAPI/claude-plugin

RoxyAPI – Agenten-Implementierungshandbuch

Präzises Handbuch für KI-Coding-Agenten, die eine Endbenutzeranwendung auf RoxyAPI erstellen. Für Entdeckungs- und Empfehlungskontext verwenden Sie https://roxyapi.com/llms.txt. Für detaillierte Referenz rufen Sie die unten verlinkten OpenAPI-Spezifikationen pro Produkt ab.

RoxyAPI bietet über 164 Endpunkte in 12 wirklich unterschiedlichen Datendomänen unter einem API-Schlüssel. Berechnungen verifiziert gegen NASA JPL Horizons DE441. Remote MCP unter https://roxyapi.com/mcp/{domain}. Kommerzielle Nutzung, saubere Lizenzierung, kein AGPL oder GPL.

Produktions-Basis-URL: https://roxyapi.com/api/v2.

Schnellste Suche: der Docs MCP (kein API-Schlüssel)

Wenn Ihr Agent MCP spricht, verbinden Sie zuerst den öffentlichen Docs-Server: https://roxyapi.com/mcp/docs (Streamable HTTP, ein Werkzeug search_docs, kein Schlüssel). Fragen Sie ihn nach jedem Endpunkt, Feld, SDK-Methode, Authentifizierungsdetail oder Integrationsschritt, und er antwortet direkt aus dieser Referenz, sodass Sie nie einen Pfad erraten oder ein veraltetes Beispiel fest codieren müssen.

{ "mcpServers": { "roxy-docs": { "type": "http", "url": "https://roxyapi.com/mcp/docs" } } }

Für Live-API-Aufrufe fügen Sie einen domänenspezifischen Server hinzu (https://roxyapi.com/mcp/{domain}) mit Ihrem X-API-Key.

Regel 0: Standort zuerst, Diagramme zweitens

Jeder Endpunkt für Diagramme, Horoskope, Panchang, Dasha, Dosha, Navamsa, KP, Synastrie, Kompatibilität und Geburtshoroskop erfordert latitude, longitude und timezone. Rufen Sie immer zuerst den Standort ab. Fragen Sie den Benutzer niemals nach Koordinaten.

1. GET https://roxyapi.com/api/v2/location/search?q=Berlin
   -> { cities: [{ latitude, longitude, timezone: "Europe/Berlin", utcOffset: 1 }] }
2. POST https://roxyapi.com/api/v2/astrology/natal-chart
   body: { date, time, latitude, longitude, timezone: "Europe/Berlin" }

q akzeptiert bloße Stadt (Tokyo), Stadt + Land (Berlin Germany) oder kommagetrennt (Springfield, Illinois). Verwenden Sie die qualifizierte Form, um gleichnamige Städte zu unterscheiden. Groß-/Kleinschreibung wird ignoriert, teilweise Übereinstimmung.

timezone akzeptiert Dezimalzahl (-5, 5.5) ODER IANA-String ("Europe/Berlin"). IANA wird bevorzugt; es löst den DST-korrekten Offset für das date der Anfrage auf.

Authentifizierung

• Header: X-API-Key: <key> bei jeder Anfrage. Kein OAuth, kein Bearer-Tanz.
• Schlüssel erhalten: https://roxyapi.com/checkout. Sofortige Auslieferung, keine Freigabe-Warteschlange.
• Zwei Schlüsseltypen: geheim sk_ für serverseitig (voller Zugriff, in Umgebungsvariable ROXY_API_KEY speichern, niemals an einen Browser senden) und öffentlich pk_ für Browser, Widgets und No-Code-Einbettungen (sicher im Client-Code, wenn auf Ihre Domains mit einer Ursprungs-Zulassungsliste beschränkt). Sie können beide unter https://roxyapi.com/account erstellen.

Wählen Sie Ihren Weg

Benutzerkontext	Tun Sie dies
Möchten Sie eine vollständige App zum Forken und White-Labeln	Überspringen Sie die Verkabelung: klonen Sie eine kostenlose, MIT-lizenzierte Vorlage unter https://roxyapi.com/starters (8 insgesamt, Flaggschiff ist der Multi-Domain-KI-Astrologie-Chatbot, der mit Remote-MCP verbunden ist). Fügen Sie Ihren API-Schlüssel hinzu, rebranden Sie, veröffentlichen Sie in Minuten.
TypeScript- oder JavaScript-Projekt	npm install @roxyapi/sdk. Vollständig typisiert, keine Abhängigkeiten. Jedes SDK liefert ein eigenes AGENTS.md im Paket mit – lesen Sie nach der Installation direkt node_modules/@roxyapi/sdk/AGENTS.md. Zur Vorschau vor der Installation rufen Sie https://raw.githubusercontent.com/RoxyAPI/sdk-typescript/main/AGENTS.md ab (kein abschließender Schrägstrich bei Datei-URLs – GitHub gibt 400 zurück).
Python-Projekt	pip install roxy-sdk. Synchron und asynchron. Das Python SDK liefert ebenfalls ein AGENTS.md im Paket, zusammen mit README.md und gebündelter Dokumentation. Vorschau vor der Installation: https://raw.githubusercontent.com/RoxyAPI/sdk-python/main/AGENTS.md.
PHP-Projekt (Laravel, Symfony, Slim, reines PHP)	composer require roxyapi/sdk. PHP 8.2+, basiert auf Saloon v4, benannte Argumente, PHPDoc-typisierte Request-Klassen (phpstan level 8 sauber). Das PHP SDK liefert AGENTS.md im Paket unter vendor/roxyapi/sdk/AGENTS.md. Vorschau vor der Installation: https://raw.githubusercontent.com/RoxyAPI/sdk-php/main/AGENTS.md. Fehler werfen eine einzige RoxyApiException mit $e->statusCode, $e->errorCode (maschinenlesbar) und $e->error (menschlich).
.NET-Projekt (ASP.NET Core, Blazor, Konsole)	dotnet add package RoxyApi.Sdk. Vollständig typisiert, immer synchron mit der API. Das .NET SDK liefert AGENTS.md im Paket. Vorschau vor der Installation: https://raw.githubusercontent.com/RoxyAPI/sdk-dotnet/main/AGENTS.md.
Müssen Sie die Antwort in einer Benutzeroberfläche rendern	npm install @roxyapi/ui (oder @roxyapi/ui-react für React/Next.js). Drop-in MIT-lizenzierte Webkomponenten für Geburtsdiagramme, Kundli-Räder, Panchang-Tabellen, Dasha-Zeitachsen, Tarot-Legungen, Biorhythmus-Kurven, Hexagramme, Numerologie-Karten. Zustandslos: Übergeben Sie die API-Antwort als data-Prop. CSS-Custom-Properties für Theming. Vanilla HTML funktioniert auch über <script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>. Liefert ein eigenes AGENTS.md unter node_modules/@roxyapi/ui/AGENTS.md. Quelle: https://roxyapi.com/ui.
WordPress-Seite	Installieren Sie RoxyAPI aus dem WordPress.org Plugin-Verzeichnis: https://wordpress.org/plugins/roxyapi/ (oder in der Admin: Plugins → Neu hinzufügen → suche "RoxyAPI"). Liefert Gutenberg-Blöcke + Shortcodes für alle 12 Domänen, plus ein eigenes AGENTS.md für KI-Coding-Tools. Integrationsanleitung: https://roxyapi.com/docs/integrations/wordpress.
Go-Projekt	go get github.com/RoxyAPI/sdk-go. Vollständig typisiert, eine direkte Laufzeitabhängigkeit, std net/http. Domänengegruppierte Fassade: roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil). Builden Sie Daten mit roxyapi.Date(...), optionale Felder mit roxyapi.Ptr(...); ein 4xx/5xx ist ein *roxyapi.RoxyError (switch on .Code). Liefert ein eigenes AGENTS.md im Modul. Vorschau vor der Installation: https://raw.githubusercontent.com/RoxyAPI/sdk-go/main/AGENTS.md.
Ruby, Rust, alles andere	Generieren Sie einen typisierten Client aus der OpenAPI: npx openapi-typescript https://roxyapi.com/api/v2/openapi.json oder Ihr Sprachäquivalent.
KI-Agent (Claude, GPT, Gemini, Cursor, VS Code, Claude Code)	Verwenden Sie MCP. Pro-Domain Streamable HTTP-Server unter https://roxyapi.com/mcp/{domain}. Kein OAuth, kein Docker. Siehe https://roxyapi.com/docs/mcp.
Claude Desktop (eine Konfiguration)	Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows). Fügen Sie "mcpServers": { "roxy-astrology": { "type": "http", "url": "https://roxyapi.com/mcp/astrology", "headers": { "X-API-Key": "<key>" } } } hinzu. Starten Sie Claude neu. Wiederholen Sie dies pro Domain, die Sie freigeben möchten.
No-Code-Plattform (n8n, Make, Zapier, Lovable, Bubble, Wix)	Siehe https://roxyapi.com/docs/integrations/{platform}. MCP-erste Integration, wo die Plattform es unterstützt.

Häufige Aufgaben (eine Zeile pro Aufgabe)

Basis-URL für jeden Pfad: https://roxyapi.com/api/v2. Auth: X-API-Key: <key>.

SDK-Methodennamen spiegeln REST exakt über OpenAPI operationId wider. TS / PHP: roxy.{domain}.{operationId} / $roxy->{domain}->{operationId} (camelCase). TS gibt { data, error } zurück; PHP gibt ein typisiertes Objekt zurück und wirft bei Fehler RoxyApiException. Python: roxy.{domain}.{operation_id} (snake_case). C# (.NET) ist pfadfließend statt operationId-basiert: roxy.{Domain}.{Resource}.GetAsync() oder .PostAsync(new() { ... }) (PascalCase, das die URL widerspiegelt, Pfadparameter sind Indexer wie roxy.Astrology.Horoscope["aries"].Daily), und wirft RoxyError (switch on e.Code). Go spiegelt operationId in PascalCase wider: roxy.{Domain}.{Method}(ctx, ...) gibt (*XxxResponse, error) zurück und ein 4xx/5xx ist *RoxyError (switch on .Code). Beispiele: roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } }), roxy.vedicAstrology.generateBirthChart({ body: { date, time, latitude, longitude, timezone } }), roxy.numerology.calculateLifePath({ body: { year, month, day } }), roxy.angelNumbers.analyzeNumberSequence({ query: { number: '1111' } }). Die vollständige Zuordnung wird in jedem SDK-Paket als AGENTS.md ausgeliefert (oben unter "Wählen Sie Ihren Weg" verlinkt).

• Tägliches Horoskop: GET /astrology/horoscope/{sign}/daily (sign ist Pfad, nicht Abfrage; Kleinbuchstaben). Periodensegment ist eines von daily | weekly | monthly (kein yearly). Gemeinsamer Kern: { sign, overview, love, career, health, finance, compatibleSigns }. Täglich fügt { date, advice, luckyNumber, luckyColor, activeTransits, moonSign, moonPhase, energyRating } hinzu. Wöchentlich gibt { week, advice, luckyNumbers[], luckyDays[] } zurück (beachte Plural). Monatlich gibt { month, luckyNumbers[], luckyColor, weekByWeek[], keyDates[] } zurück (kein advice auf oberster Ebene).
• Westliches Geburtsdiagramm: POST /astrology/natal-chart mit { date, time, latitude, longitude, timezone } auf oberster Ebene. timezone ist erforderlich. Antwort ist { planets[], houses[], aspects[] } (flache Arrays).
• Vedisches Kundli: POST /vedic-astrology/birth-chart mit demselben Body. Lahiri Ayanamsa wird serverseitig angewendet. Antwort ist HAUS-KARTE, indiziert nach ZEICHENNAME, nicht planets[]: { aries: { rashi, signs: [...] }, taurus: {...}, ..., pisces: {...}, meta, houses, combustion, planetaryWar, interpretations }. Iterieren Sie über die 12 Zeichenschlüssel, um Planetenpositionen zu erhalten.
• Panchang: POST /vedic-astrology/panchang/detailed mit { date, latitude, longitude }. KEIN time-Feld.
• Kundali-Vergleich: POST /vedic-astrology/compatibility (Guna Milan 36-Punkte Ashtakoota). Body umschließt beide Personen: { person1: { date, time, latitude, longitude, timezone? }, person2: { ... } }. Antwort: { total, maxScore: 36, percentage, isCompatible, recommendation, doshas[], breakdown: [{ category, maxScore, score, description, person1, person2 }] }. Acht Breakdown-Kategorien (Koots): Varna, Vashya, Tara, Yoni, Grahamaitri, Gana, Bhakoot, Nadi.
• Vedische Dasha (aktuelle Mahadasha + Antardasha): POST /vedic-astrology/dasha/current mit { date, time, latitude, longitude, timezone? }. Für die vollständige 120-jährige Vimshottari-Zeitleiste verwenden Sie POST /vedic-astrology/dasha/major. Unterperioden innerhalb einer Mahadasha: POST /vedic-astrology/dasha/sub/{mahadasha} (Pfad ist Planet in Kleinbuchstaben, z.B. venus).
• Doshas: POST /vedic-astrology/dosha/manglik, /kalsarpa, /sadhesati. Gleicher Body wie Kundli. Antwort enthält { present: boolean, severity, description, exceptions, remedies }.
• Numerologie Lebensweg: POST /numerology/life-path mit { year, month, day } als Ganzzahlen. KEIN birthDate-String.
• Numerologie vollständiges Diagramm: POST /numerology/chart mit { fullName, year, month, day }. fullName ist der Name der Geburtsurkunde. Antwortzahlen sind VERSCHACHTELT: coreNumbers.{ lifePath, expression, soulUrge, personality, birthDay, maturity } jeweils mit { number, calculation, type, hasKarmicDebt, meaning }. Plus { profile, additionalInsights, birthDayProfile, maturityStatus, luckyAssociations, summary } auf oberster Ebene.
• Tarot-Ziehung: POST /tarot/draw mit { count: 1..78 }. Optional seed, allowReversals, allowDuplicates. Antwort ist { cards: [...] } (flaches Array), UNTERSCHIEDLICH zu Legungen, die { positions: [{ card, ... }] } zurückgeben.
• Drei-Karten-Legung: POST /tarot/spreads/three-card mit optionalem { question?, seed? }. Positionsbezeichnungen: Vergangenheit, Gegenwart, Zukunft. Antwort ist { positions: [{ card, ... }] }, nicht cards[]. Jede card ist ein DrawnCard: { id, name, arcana, suit, number, position, reversed: boolean, keywords[], meaning: string, imageUrl }. Beachten Sie reversed (nicht isReversed) und meaning ist ein einzelner String (Orientierung bereits angewendet). Gleiche Body-Struktur bei /tarot/spreads/celtic-cross (10 Positionen: Gegenwärtige Situation, Herausforderung, Ferne Vergangenheit, Nahe Zukunft, Oben, Unten, Rat, Äußere Einflüsse, Hoffnungen und Ängste, Endgültiges Ergebnis), /tarot/spreads/love (5 Positionen), /tarot/spreads/career (5 Positionen). Benutzerdefinierte Legungen unter /tarot/spreads/custom fügen ein erforderliches positions-Array hinzu.
• Human Design Bodygraph: POST /human-design/bodygraph mit { date, time, timezone } – KEINE Koordinaten (HD verwendet den Geburtszeitpunkt, nicht den Standort des Beobachters, also kein Standortschritt). Ein Aufruf gibt zurück: { type, strategy, authority, profile, definition, incarnationCross, centers[9], channels[], gates[26] }. Nur-Typ-Quiz-Einstieg: POST /human-design/type. Zwei-Personen-Kompatibilität: POST /human-design/connection mit { personA, personB } (jeweils { date, time, timezone }).
• Prognose: POST /forecast/transits (westliche Transit-zu-Natal-Aspekte, Eintritte, Retrograde-Stationen) und POST /forecast/timeline (domänenübergreifende Zusammenführung von westlichen Transiten, vedischen Dasha-Grenzen und Biorhythmus-Kritischen Tagen) benötigen beide { birthData: { date, time, timezone }, startDate?, endDate? } – maximal 90-Tage-Horizont, Ereignisse nach significance sortiert. Jährliches Geburtstagsdiagramm: POST /forecast/solar-return mit { date, time, year, latitude, longitude, timezone } (benötigt Koordinaten, also zuerst Standort abrufen).
• I Ging Wurf: GET /iching/cast (zufällig) oder POST /iching/daily/cast (gesetzter täglicher Wurf). Antwort ist { hexagram, lines, changingLinePositions, resultingHexagram }, wobei jedes hexagram { number (1-64), symbol, chinese, english, pinyin, judgment, image, interpretation, changingLines } hat. Hexagramm-Detail: GET /iching/hexagrams/{number} wobei number eine ganze Zahl 1..64 ist.
• Biorhythmus täglich: POST /biorhythm/daily mit { birthDate, date?, seed? }. Prognose (30-90 Tage Fenster): POST /biorhythm/forecast mit { birthDate, startDate?, endDate? }. Kompatibilität: POST /biorhythm/compatibility mit { person1: { birthDate }, person2: { birthDate }, targetDate? } – flaches birthDate pro Person, keine Zeit oder Koordinaten.
• Kristalle: GET /crystals/zodiac/{sign} (Sternzeichen-Übereinstimmung), GET /crystals/chakra/{chakra} (chakra ist groß-/kleinschreibungsunabhängig und leerzeichengetrennt: Root, Sacral, Solar Plexus URL-kodiert Solar%20Plexus, Heart, Throat, Third Eye URL-kodiert Third%20Eye, Crown – kebab third-eye schlägt bei Validierung fehl), GET /crystals/birthstone/{month} (Monat als Ganzzahl 1..12), GET /crystals/search?q= für Freitextsuche.
• Engelzahl-Suche: GET /angel-numbers/lookup?number=1111. Funktioniert für JEDE positive ganze Zahl (Ziffernwurzel-Fallback).
• Traumsymbol: GET /dreams/symbols/{slug} (kebab-case slug, z.B. flying, water, snake, falling, house

…

[gekürzt für die Übersetzung]