Prompts pour les builders IA

Un builder écrira le code plus vite que vous. Ce qu’il ignore, ce sont deux choses propres à une API donnée: où placer la clé et pourquoi une requête depuis le navigateur ne passe pas. Les deux coûtent des heures de débogage, et les deux se règlent avec un seul paragraphe dans le prompt.

Ci-dessous, d’abord ce paragraphe, puis sept recettes.

La règle à insérer avant chaque recette

Copiez ce bloc dans le builder avant le texte de la recette. Il ne concerne pas le style du code, mais ce qui sinon ne fonctionnera pas.

house rules

AstroWay API house rules. Apply these to every request you generate.

1. The API key is a server secret. Never put aw_live_* or aw_test_* into client
   code, into a VITE_* or NEXT_PUBLIC_* variable, or into a fetch that runs in
   the browser. Create a server route and call the API from there.
2. The browser cannot call https://api.astroway.info/v1/* with that key.
   The one exception is a publishable pk_live_* key created for your app's
   origin: responses to that origin carry access-control-allow-origin, and
   the key works only from origins on its own list. Two prefixes answer any
   browser with no key: /v1/public/* returns JSON you can use, and
   /v1/embed/* returns a finished HTML page meant for an iframe, not for fetch.
3. The auth header is exactly "X-Api-Key: <key>". Authorization: Bearer is
   rejected with 401, and so is an api_key query parameter.
4. Send the birth time zone as an IANA name: "timezone": "Europe/Kyiv". Do not
   compute a UTC offset yourself. Kyiv in May 1990 was UTC+4, not the +3 it is
   today, and a wrong offset moves every house cusp.
5. Every response is {"ok": true, "data": {...}} or {"ok": false, "error":
   {"code": "...", "message": "..."}}. Read data on success and show
   error.message to the user on failure. Do not assume a bare object.
6. Planet positions arrive as ecliptic longitude in degrees, with no sign name.
   Derive it: SIGNS[Math.floor(longitude / 30)] where SIGNS runs Aries,
   Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius,
   Capricorn, Aquarius, Pisces. Degrees inside the sign are longitude % 30.
7. Responses carry X-Credits-Used and X-Credits-Remaining. Log both on the
   server so the cost of a feature is visible before the bill is.
8. Ask for the fields you will render. Every endpoint takes ?fields= as a
   comma-separated list of dotted paths and ?precision= as decimal places:
   POST /v1/chart?fields=planets.name,planets.longitude,houses.cusp&precision=2
   answers in 559 bytes where the full response is 32,410. Same credits, and
   the tokens are yours to pay either way.
9. Get a free key at https://api.astroway.info/dashboard/sign-up and use an
   aw_test_* sandbox key while building: it spends no credits.

Attention

Le point 2 est mesuré, pas supposé: une page de test sur un origin tiers obtient une réponse de /v1/public/*, tandis que POST /v1/chart est bloqué par le navigateur. Une clé publique pk_* n’y change rien, elle n’ouvre que /v1/public/* et /v1/embed/*.

1. Carte natale avec roue

Deux réponses pour une seule action de l’utilisateur: les données de la carte et un SVG prêt à l’emploi.

Endpoint	Crédits
/v1/chart	20
/v1/render/wheel-western	10

prompt

Build a single-page app: a birth data form (date, time, city with latitude and
longitude, IANA time zone) that renders a natal chart.

Server route POST /api/chart does two calls to AstroWay, in parallel:
  POST https://api.astroway.info/v1/chart
  POST https://api.astroway.info/v1/render/wheel-western
Both take the same body:
  { "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
    "latitude": 50.45, "longitude": 30.52 }
Both need the X-Api-Key header.

/v1/chart returns data.planets (array with name, longitude, isRetrograde),
data.houses.cusps (array of 12 longitudes) and data.aspects (array with
planet1, planet2 and a type object carrying name, symbol and color).
/v1/render/wheel-western returns data.svg as a string.

The page shows the SVG at the top, then a table of planets with sign and
degree derived from longitude, then the aspect list using type.symbol and
type.color. Mark retrograde planets with an R.

Do not call AstroWay from the browser. The page calls /api/chart only.

À vérifier après la génération: le SVG est inséré comme balisage, et non dans <img src>; l’heure est envoyée comme chaîne HH:mm:ss; la clé ne s’est pas retrouvée dans le bundle (une recherche de aw_ dans les fichiers compilés ne doit rien trouver).

2. Compatibilité de deux cartes

Un seul nombre et ses composantes, sans texte explicatif. /v1/synastry/attraction-score, 50 crédits par paire.

prompt

Build a compatibility page: two birth-data forms side by side, one button.

Server route POST /api/compat calls
  POST https://api.astroway.info/v1/synastry/attraction-score
with body { "chart1": {...}, "chart2": {...} }, where each chart is
  { "date", "time", "timezone", "latitude", "longitude" }.

The response has data.score (a number), data.components (the parts that made
it) and data.notes. Render score as a large number with a progress ring, then
components as labelled bars, then notes as a list.

Never show the score without the components: a single number with no reason
behind it is the thing users distrust.

3. Horoscope quotidien, sans aucune clé

La seule recette où une route serveur n’est pas nécessaire: cet endpoint répond au navigateur et ne coûte aucun crédit.

prompt

Add a daily horoscope block to the page. Call this directly from the browser,
no key and no server route needed:

  GET https://api.astroway.info/v1/public/horoscope/daily?sign=leo&lang=en

Response: data.sign, data.date, data.period, data.horoscope (the text),
data.disclaimer and data.language. Render a sign picker with the twelve signs,
remember the choice in localStorage, and always show data.disclaimer under the
text.

The first request for a date that has not been generated yet can take a while,
so show a skeleton, not a spinner that looks stuck.

Note

La limite est ici par IP, 30 requêtes par heure pour les appels sans clé. Pour une page avec un seul bloc d’horoscope, c’est suffisant; pour une liste des douze signes d’un coup, non.

4. Human Design

Type, stratégie, autorité, profil, centres et canaux en un seul appel /v1/human-design, 50 crédits.

prompt

Build a Human Design page: birth data form, then the chart summary.

Server route POST /api/hd calls
  POST https://api.astroway.info/v1/human-design
with { "date", "time", "timezone", "latitude", "longitude" }.

The response has data.type, data.strategy, data.notSelfTheme, data.authority,
data.profile, data.definition, data.cross, data.centers, and the activation
arrays data.personalityActivations and data.designActivations.

Lay it out as: type and strategy as the headline, authority and profile as two
cards, centers as a list with defined ones filled and undefined ones outlined,
activations in a collapsible table. Birth time matters here more than anywhere
else, so refuse to submit without it and say why.

5. Rapport PDF à la marque de l’utilisateur

Pour ceux qui vendent des rapports plutôt que d’afficher des écrans. /v1/reports/natal, 5000 crédits par document, et le lien reste valide 24 heures.

prompt

Build a report generator: birth data form plus a branding form (company name,
report title, accent colour), and a Generate button.

Server route POST /api/report calls
  POST https://api.astroway.info/v1/reports/natal
with
  { "chart": { "date", "time", "timezone", "latitude", "longitude" },
    "whitelabel": { "companyName": "...", "reportName": "...",
                    "themeColor": "#7c3aed", "footerText": "..." } }

The response has data.url, data.page_count, data.byte_length and
data.expires_at. The URL is valid for 24 hours only, so the server must
download the PDF immediately and store it on your side, then hand the user
your own link. Never give the AstroWay URL to the end user.

Show page_count and a download button. One report costs 5000 credits: put a
confirmation step before the call, not after.

Le catalogue complet des seize rapports, avec le contenu et le nombre de pages de chacun: Reports API.

6. Calendrier des transits sur un mois

Une liste d’événements dans une fenêtre de dates, dont on tire à la fois un fil et un calendrier. /v1/transit-calendar, 100 crédits par fenêtre.

prompt

Build a month view of transits.

Server route POST /api/transits calls
  POST https://api.astroway.info/v1/transit-calendar
with
  { "natal": { "date", "time", "timezone", "latitude", "longitude" },
    "startDate": "2026-10-01", "endDate": "2026-10-31" }

The response has data.count and data.events, plus the echoed startDate,
endDate and maxOrb. Render events on a month grid, one dot per day with
events, and a day panel listing that day's events.

One call covers the whole window, so fetch the month once and filter in the
client. Do not call the API per day: that is thirty-one calls and thirty-one
times the credits for the same answer.

7. Tirage de tarot

Le moyen le moins cher d’ajouter une interaction quotidienne. /v1/tarot/rider-waite/draw/three-card, 10 crédits par tirage, ou zéro pour la carte du jour.

prompt

Add a three-card tarot spread.

Server route POST /api/tarot calls
  POST https://api.astroway.info/v1/tarot/rider-waite/draw/three-card
with an optional { "seed": 7 }. The response has data.spread, data.seed and
data.drawn.

Pass a seed derived from the user id and today's date, so the same person gets
the same spread all day and a new one tomorrow. Without a seed every reload
deals a new hand, which reads as a slot machine.

For a zero-cost daily card the browser can call
  GET https://api.astroway.info/v1/public/tarot/daily
directly, no key.

Huit builders, une seule différence

Les recettes ci-dessus sont les mêmes pour tous. La seule différence est l’endroit où vit la route serveur et où placer la clé.

Builder	Où vit l’appel serveur	Où placer la clé
Lovable	edge function dans Supabase	Secrets du projet Supabase
Bolt	server function	panneau Secrets de Bolt
v0	route handler Next.js sur Vercel Functions	environment variable dans Vercel, de type Secret
Replit	processus serveur ordinaire	Replit Secrets, et une seconde fois séparément dans Deployments
Cursor, Claude Code, Devin Desktop, Copilot	celui de votre stack	.env hors de git plus le stockage de secrets de votre hébergeur

Quatre pièges distincts, chacun coûte une soirée.

• Lovable et Bolt compilent le frontend avec Vite, et Vite transmet au navigateur toute variable au préfixe VITE_. N’y mettez jamais la clé, même temporairement: elle finirait dans un bundle distribué à tout le monde.
• Bolt affiche l’aperçu dans un WebContainer, qui est un vrai navigateur avec un vrai CORS, impossible à désactiver. Ici, la fonction serveur n’est pas “mieux”, c’est le seul moyen pour que l’appel ait lieu tout court.
• v0 intègre NEXT_PUBLIC_* dans le bundle au moment du build. Changer la valeur dans le dashboard ne suffit pas: tant qu’il n’y a pas de nouveau déploiement, l’application tourne avec l’ancienne clé. Faire une rotation de clé, c’est la rotation plus un nouveau build.
• Replit garde séparément les secrets de l’espace de travail et ceux de Deployments. Ce qui fonctionnait dans l’éditeur échoue après publication avec une clé vide, tant que vous ne l’ajoutez pas une seconde fois dans le panneau Deployments.

Les quatre outils de la dernière ligne du tableau ne sont pas des plateformes, mais des agents dans votre dépôt, et chacun a sa propre liste d’autorisations réseau pour son bac à sable. Quand l’agent voudra tester le code qu’il vient d’écrire, l’appel à api.astroway.info pourra être bloqué tant que le domaine n’est pas ajouté. Pour eux, il existe aussi un chemin plus court: connectez notre MCP et l’agent appellera l’API lui-même, sans votre code. Instructions sur Configuration de l’agent.

Note

Depuis le 2 juin 2026, Windsurf s’appelle Devin Desktop, les utilisateurs ont été migrés automatiquement et la documentation a déménagé sur docs.devin.ai. Tout ce que vous trouverez aujourd’hui sous le nom Windsurf a été écrit avant cette date.

Si votre agent parle function calling et non MCP

Prenez les définitions d’outils prêtes à l’emploi et passez-les directement au modèle. Elles sont générées à partir du document OpenAPI, donc le schéma que remplit le modèle est le même que celui que vérifie l’endpoint.

terminal

curl "https://api.astroway.info/v1/agent/tools?format=openai&select=starter" \
-H "X-Api-Key: aw_live_YOUR_KEY"

format accepte openai et anthropic, select réduit le catalogue à un ensemble de démarrage au lieu de tous les outils.