RoxyAPI/plugin-claude

RoxyAPI – Guide d'implémentation pour agents

Guide concis pour les agents d'IA codant une application utilisateur finale sur RoxyAPI. Pour le contexte de découverte et de recommandation, utilisez https://roxyapi.com/llms.txt. Pour une référence détaillée, récupérez les spécifications OpenAPI par produit ci-dessous.

RoxyAPI propose plus de 164 endpoints couvrant 12 domaines de données véritablement distincts sous une seule clé d'API. Calculs vérifiés par rapport aux éphémérides JPL Horizons DE441 de la NASA. MCP à distance à https://roxyapi.com/mcp/{domain}. Licence commerciale, propre, pas d'AGPL ou de GPL.

URL de base de production : https://roxyapi.com/api/v2.

Recherche la plus rapide : le serveur MCP Docs (sans clé d'API)

Si votre agent parle MCP, connectez d'abord le serveur Docs public : https://roxyapi.com/mcp/docs (HTTP Streamable, un outil search_docs, sans clé). Posez-lui des questions sur n'importe quel endpoint, champ, méthode SDK, détail d'authentification ou étape d'intégration, et il répond directement à partir de cette référence, vous évitant ainsi de deviner un chemin ou de coder en dur un exemple obsolète.

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

Pour les appels API en direct, ajoutez un serveur par domaine (https://roxyapi.com/mcp/{domain}) avec votre X-API-Key.

Règle 0 : Localisation d'abord, thèmes après

Chaque endpoint de thème, horoscope, panchanga, dasha, dosha, navamsa, KP, synastrie, compatibilité et thème natal nécessite latitude, longitude et timezone. Appelez toujours Localisation en premier. Ne demandez jamais les coordonnées à l'utilisateur.

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

q accepte une ville seule (Tokyo), ville + pays (Berlin Germany), ou séparée par une virgule (Springfield, Illinois). Utilisez la forme qualifiée pour lever l'ambiguïté sur les villes homonymes. Insensible à la casse, correspondance partielle.

timezone accepte un nombre décimal (-5, 5.5) OU une chaîne IANA ("America/New_York"). IANA est préféré ; il résout le décalage correct avec l'heure d'été (DST) pour la date de la requête.

Authentification

• En-tête : X-API-Key: <key> sur chaque requête. Pas d'OAuth, pas de Bearer.
• Obtenir une clé : https://roxyapi.com/checkout. Livraison instantanée, pas de file d'approbation.
• Deux types de clés : secrète sk_ pour le côté serveur (accès complet, stockez dans l'env ROXY_API_KEY, ne l'envoyez jamais au navigateur) et publiable pk_ pour les navigateurs, widgets et intégrations no-code (sûre dans le code client lorsqu'elle est verrouillée à vos domaines avec une liste d'autorisation d'origine). Créez l'une ou l'autre à https://roxyapi.com/account.

Choisissez votre chemin

Contexte utilisateur	Faites ceci
Vous voulez une application complète à forker et à marque blanche	Sautez le câblage : clonez un modèle libre sous licence MIT à https://roxyapi.com/starters (8 au total, le produit phare est le Chatbot IA d'astrologie multi-domaines câblé au MCP distant). Ajoutez votre clé d'API, re-brandez, déployez en quelques minutes.
Projet TypeScript ou JavaScript	npm install @roxyapi/sdk. Entièrement typé, zéro dépendance. Chaque SDK embarque son propre AGENTS.md dans le paquet — après installation, lisez node_modules/@roxyapi/sdk/AGENTS.md directement. Pour prévisualiser avant installation, récupérez https://raw.githubusercontent.com/RoxyAPI/sdk-typescript/main/AGENTS.md (pas de barre oblique à la fin sur les URLs de fichier — GitHub renvoie 400).
Projet Python	pip install roxy-sdk. Synchrone et asynchrone. Le SDK Python embarque également un AGENTS.md dans le paquet, avec README.md et la documentation intégrée. Prévisualisation avant installation : https://raw.githubusercontent.com/RoxyAPI/sdk-python/main/AGENTS.md.
Projet PHP (Laravel, Symfony, Slim, PHP pur)	composer require roxyapi/sdk. PHP 8.2+, construit sur Saloon v4, arguments nommés, classes de requêtes typées PHPDoc (phpstan niveau 8 propre). Le SDK PHP embarque AGENTS.md dans le paquet à vendor/roxyapi/sdk/AGENTS.md. Prévisualisation avant installation : https://raw.githubusercontent.com/RoxyAPI/sdk-php/main/AGENTS.md. Les erreurs lèvent une seule RoxyApiException avec $e->statusCode, $e->errorCode (lisible par machine), et $e->error (humain).
Projet .NET (ASP.NET Core, Blazor, console)	dotnet add package RoxyApi.Sdk. Entièrement typé, toujours synchronisé avec l'API. Le SDK .NET embarque AGENTS.md dans le paquet. Prévisualisation avant installation : https://raw.githubusercontent.com/RoxyAPI/sdk-dotnet/main/AGENTS.md.
Besoin d'afficher la réponse dans une UI	npm install @roxyapi/ui (ou @roxyapi/ui-react pour React/Next.js). Composants web prêts à l'emploi sous licence MIT pour les thèmes natals, roues kundli, tableaux panchanga, chronologies dasha, tirages de tarot, courbes bio-rythme, hexagrammes, cartes de numérologie. Sans état : passez la réponse de l'API comme propriété data. Propriétés CSS personnalisées pour le thème. Le HTML vanille fonctionne aussi via <script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>. Embarque son propre AGENTS.md à node_modules/@roxyapi/ui/AGENTS.md. Source : https://roxyapi.com/ui.
Site WordPress	Installez RoxyAPI à partir de l'annuaire des plugins WordPress.org : https://wordpress.org/plugins/roxyapi/ (ou dans l'admin : Plugins → Add New → recherchez "RoxyAPI"). Fournit des blocs Gutenberg + shortcodes couvrant les 12 domaines, ainsi que son propre AGENTS.md pour les outils de codage IA. Guide d'intégration : https://roxyapi.com/docs/integrations/wordpress.
Projet Go	go get github.com/RoxyAPI/sdk-go. Entièrement typé, une dépendance d'exécution directe, std net/http. Façade groupée par domaine : roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil). Construisez les dates avec roxyapi.Date(...), les champs optionnels avec roxyapi.Ptr(...) ; une 4xx/5xx est une *roxyapi.RoxyError (switch sur .Code). Embarque son propre AGENTS.md dans le module. Prévisualisation avant installation : https://raw.githubusercontent.com/RoxyAPI/sdk-go/main/AGENTS.md.
Ruby, Rust, autre	Générez un client typé à partir de l'OpenAPI : npx openapi-typescript https://roxyapi.com/api/v2/openapi.json ou l'équivalent pour votre langage.
Agent IA (Claude, GPT, Gemini, Cursor, VS Code, Claude Code)	Utilisez MCP. Serveurs HTTP Streamable par domaine à https://roxyapi.com/mcp/{domain}. Pas d'OAuth, pas de Docker. Voir https://roxyapi.com/docs/mcp.
Claude Desktop (une seule configuration)	Éditez ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\\Claude\\claude_desktop_config.json (Windows). Ajoutez "mcpServers": { "roxy-astrology": { "type": "http", "url": "https://roxyapi.com/mcp/astrology", "headers": { "X-API-Key": "<key>" } } }. Redémarrez Claude. Répétez pour chaque domaine que vous souhaitez exposer.
Plateforme No-code (n8n, Make, Zapier, Lovable, Bubble, Wix)	Voir https://roxyapi.com/docs/integrations/{platform}. Intégration MCP en priorité là où la plateforme le supporte.

Tâches courantes (une ligne chacune)

URL de base pour chaque chemin : https://roxyapi.com/api/v2. Auth : X-API-Key: <key>.

Les noms des méthodes SDK reflètent exactement REST via l'OpenAPI operationId. TS / PHP : roxy.{domain}.{operationId} / $roxy->{domain}->{operationId} (camelCase). TS renvoie { data, error } ; PHP renvoie un objet typé et lève RoxyApiException en cas d'échec. Python : roxy.{domain}.{operation_id} (snake_case). C# (.NET) est fluent par chemin plutôt que basé sur operationId : roxy.{Domain}.{Resource}.GetAsync() ou .PostAsync(new() { ... }) (PascalCase reflétant l'URL, les paramètres de chemin sont des indexeurs comme roxy.Astrology.Horoscope["aries"].Daily), et lève RoxyError (switch sur e.Code). Go reflète operationId en PascalCase : roxy.{Domain}.{Method}(ctx, ...) renvoie (*XxxResponse, error) et une 4xx/5xx est *RoxyError (switch sur .Code). Exemples : 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' } }). Le mappage complet est embarqué dans chaque paquet SDK sous forme de AGENTS.md (lié ci-dessus dans Choisissez votre chemin).

• Horoscope quotidien : GET /astrology/horoscope/{sign}/daily (sign est un paramètre de chemin, pas de requête ; en minuscules). Le segment de période est l'un de daily | weekly | monthly (pas de yearly). Noyau commun : { sign, overview, love, career, health, finance, compatibleSigns }. Quotidien ajoute { date, advice, luckyNumber, luckyColor, activeTransits, moonSign, moonPhase, energyRating }. Hebdomadaire renvoie { week, advice, luckyNumbers[], luckyDays[] } (notez le pluriel). Mensuel renvoie { month, luckyNumbers[], luckyColor, weekByWeek[], keyDates[] } (pas de advice au niveau supérieur).
• Thème astral occidental : POST /astrology/natal-chart avec { date, time, latitude, longitude, timezone } au niveau supérieur. timezone est obligatoire. La réponse est { planets[], houses[], aspects[] } (tableaux plats).
• Kundli védique : POST /vedic-astrology/birth-chart avec le même corps. Ayanamsa de Lahiri appliqué côté serveur. La réponse est MAPÉE PAR MAISON et par NOM DE SIGNE, pas par planets[] : { aries: { rashi, signs: [...] }, taurus: {...}, ..., pisces: {...}, meta, houses, combustion, planetaryWar, interpretations }. Itérez sur les 12 clés de signe pour obtenir les positions planétaires.
• Panchanga : POST /vedic-astrology/panchang/detailed avec { date, latitude, longitude }. PAS de champ time.
• Compatibilité Kundali : POST /vedic-astrology/compatibility (Guna Milan 36 points Ashtakoota). Le corps enveloppe les deux personnes : { person1: { date, time, latitude, longitude, timezone? }, person2: { ... } }. Réponse : { total, maxScore: 36, percentage, isCompatible, recommendation, doshas[], breakdown: [{ category, maxScore, score, description, person1, person2 }] }. Huit catégories de décomposition (Koots) : Varna, Vashya, Tara, Yoni, Grahamaitri, Gana, Bhakoot, Nadi.
• Dasha védique (Mahadasha actuelle + Antardasha) : POST /vedic-astrology/dasha/current avec { date, time, latitude, longitude, timezone? }. Pour la chronologie complète de 120 ans Vimshottari, utilisez POST /vedic-astrology/dasha/major. Sous-périodes dans un Mahadasha : POST /vedic-astrology/dasha/sub/{mahadasha} (le chemin est la planète en minuscule, ex. venus).
• Doshas : POST /vedic-astrology/dosha/manglik, /kalsarpa, /sadhesati. Même corps que le kundli. La réponse contient { present: boolean, severity, description, exceptions, remedies }.
• Chemin de vie en numérologie : POST /numerology/life-path avec { year, month, day } entiers. PAS une chaîne birthDate.
• Thème complet en numérologie : POST /numerology/chart avec { fullName, year, month, day }. fullName est le nom de l'acte de naissance. Les numéros de réponse sont IMBRIQUÉS : coreNumbers.{ lifePath, expression, soulUrge, personality, birthDay, maturity } chacun avec { number, calculation, type, hasKarmicDebt, meaning }. Plus les niveaux supérieurs { profile, additionalInsights, birthDayProfile, maturityStatus, luckyAssociations, summary }.
• Tirage de tarot : POST /tarot/draw avec { count: 1..78 }. seed, allowReversals, allowDuplicates optionnels. Réponse : { cards: [...] } (tableau plat), DIFFÉRENT des spreads qui renvoient { positions: [{ card, ... }] }.
• Spread trois cartes : POST /tarot/spreads/three-card avec { question?, seed? } optionnel. Étiquettes de position : Passé, Présent, Futur. Réponse : { positions: [{ card, ... }] }, pas cards[]. Chaque card est un DrawnCard : { id, name, arcana, suit, number, position, reversed: boolean, keywords[], meaning: string, imageUrl }. Notez reversed (pas isReversed) et meaning est une chaîne unique (l'orientation déjà appliquée). Même forme de corps pour /tarot/spreads/celtic-cross (10 positions : Situation Présente, Défi, Passé Lointain, Futur Proche, Au-dessus, En dessous, Conseil, Influences Extérieures, Espoirs et Peurs, Résultat Final), /tarot/spreads/love (5 positions), /tarot/spreads/career (5 positions). Les spreads personnalisés sur /tarot/spreads/custom ajoutent un tableau positions obligatoire.
• Bodygraph Design Humain : POST /human-design/bodygraph avec { date, time, timezone } — PAS de coordonnées (HD utilise l'instant de naissance, pas l'emplacement de l'observateur, donc pas d'étape de localisation). Un seul appel renvoie { type, strategy, authority, profile, definition, incarnationCross, centers[9], channels[], gates[26] }. Quiz de type uniquement : POST /human-design/type. Compatibilité deux personnes : POST /human-design/connection avec { personA, personB } (chacun { date, time, timezone }).
• Prévisions : POST /forecast/transits (aspects transit-natal occidentaux, ingressions, stations rétrogrades) et POST /forecast/timeline (fusion inter-domaines des transits occidentaux, limites de dasha védique et jours critiques de bio-rythme) prennent tous deux { birthData: { date, time, timezone }, startDate?, endDate? } — horizon de 90 jours max, événements classés par significance. Thème d'anniversaire annuel : POST /forecast/solar-return avec { date, time, year, latitude, longitude, timezone } (nécessite des coordonnées, donc appelez Localisation d'abord).
• Tirage Yi Jing : GET /iching/cast (aléatoire) ou POST /iching/daily/cast (tirage quotidien basé sur une graine). Réponse : { hexagram, lines, changingLinePositions, resultingHexagram } où chaque hexagram a { number (1-64), symbol, chinese, english, pinyin, judgment, image, interpretation, changingLines }. Détail d'un hexagramme : GET /iching/hexagrams/{number} où number est un entier de 1 à 64.
• Bio-rythme quotidien : POST /biorhythm/daily avec { birthDate, date?, seed? }. Prévisions (fenêtre de 30 à 90 jours) : POST /biorhythm/forecast avec { birthDate, startDate?, endDate? }. Compatibilité : POST /biorhythm/compatibility avec { person1: { birthDate }, person2: { birthDate }, targetDate? } — birthDate plat par personne, pas d'heure ni de coordonnées.
• Cristaux : GET /crystals/zodiac/{sign} (correspondance zodiacale), GET /crystals/chakra/{chakra} (chakra est insensible à la casse et séparé par des espaces : Root, Sacral, Solar Plexus encodé en URL Solar%20Plexus, Heart, Throat, Third Eye encodé en URL Third%20Eye, Crown — le kebab third-eye échoue la validation), GET /crystals/birthstone/{month} (mois entier 1..12), GET /crystals/search?q= pour du texte libre.
• Recherche de nombre angélique : GET /angel-numbers/lookup?number=1111. Fonctionne pour TOUT entier positif (fallback racine numérique).
• Symbole de rêve : GET /dreams/symbols/{slug} (slug en kebab-case, ex. flying, water, snake, falling, house

...

[tronqué pour la traduction]