Prompt per i builder AI

Un builder scrive il codice più in fretta di te. Quello che non sa sono due cose su un’API specifica: dove mettere la chiave e perché una richiesta dal browser non passa. Entrambe costano ore di debug, ed entrambe si risolvono con un paragrafo nel prompt.

Qui sotto prima quel paragrafo, poi sette ricette.

La regola da inserire prima di qualsiasi ricetta

Copia questo blocco nel builder prima del testo della ricetta. Non riguarda lo stile del codice, riguarda ciò che altrimenti non funzionerà.

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.

Attenzione

Il punto 2 è misurato, non ipotizzato: una pagina di prova su un origin esterno riceve la risposta da /v1/public/*, mentre POST /v1/chart viene bloccato dal browser. Una chiave pubblica pk_* non cambia le cose, apre soltanto /v1/public/* e /v1/embed/*.

1. Carta natale con la ruota

Due risposte a un’unica azione dell’utente: i dati della carta e un SVG pronto.

Endpoint	Crediti
/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.

Verifica dopo la generazione: l’SVG è inserito come markup e non in <img src>; l’ora è inviata come stringa HH:mm:ss; la chiave non è finita nel bundle (una ricerca di aw_ nei file compilati non deve trovare nulla).

2. Compatibilità di due carte

Un numero e le sue componenti, senza testo esplicativo. /v1/synastry/attraction-score, 50 crediti per coppia.

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. Oroscopo giornaliero, del tutto senza chiave

L’unica ricetta in cui la rotta server non serve: questo endpoint risponde al browser e non costa crediti.

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.

Nota

Il limite qui è per IP, 30 richieste all’ora per le chiamate senza chiave. Per una pagina con un solo blocco di oroscopo basta; per un elenco di dodici segni tutti insieme no.

4. Human Design

Tipo, strategia, autorità, profilo, centri e canali con una sola chiamata a /v1/human-design, 50 crediti.

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. Report PDF con il brand dell’utente

Per chi vende report invece di mostrare schermate. /v1/reports/natal, 5000 crediti per documento, e il link vive 24 ore.

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.

Il catalogo completo dei sedici report, con il contenuto di ciascuno e il numero di pagine: Reports API.

6. Calendario dei transiti per un mese

Un elenco di eventi in una finestra di date, da cui si ricavano sia un feed sia un calendario. /v1/transit-calendar, 100 crediti per finestra.

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. Stesa dei tarocchi

Il modo più economico per aggiungere un’interazione quotidiana. /v1/tarot/rider-waite/draw/three-card, 10 crediti per stesa, oppure zero per la carta del giorno.

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.

Otto builder, una sola differenza

Le ricette sopra sono uguali per tutti. La differenza è solo dove vive la rotta server e dove mettere la chiave.

Builder	Dove vive la chiamata server	Dove mettere la chiave
Lovable	edge function in Supabase	Secrets del progetto Supabase
Bolt	server function	pannello Secrets di Bolt
v0	route handler Next.js su Vercel Functions	environment variable in Vercel, di tipo Secret
Replit	un normale processo server	Replit Secrets, e separatamente un’altra volta in Deployments
Cursor, Claude Code, Devin Desktop, Copilot	quello del tuo stack	.env fuori da git più lo storage del tuo hosting

Quattro trappole distinte, ognuna costa una serata.

• Lovable e Bolt compilano il frontend con Vite, e Vite espone al browser qualsiasi variabile con prefisso VITE_. La chiave lì non si mette nemmeno temporaneamente: finirebbe nel bundle distribuito a tutti.
• Bolt mostra l’anteprima dentro un WebContainer, che è un vero browser con un vero CORS, lì non disattivabile. La funzione server qui non è “meglio”, è l’unico modo perché la chiamata avvenga davvero.
• v0 incorpora NEXT_PUBLIC_* nel bundle in fase di build. Cambiare il valore nella dashboard non basta: finché non c’è un nuovo deploy, l’app funziona con la vecchia chiave. Ruotare la chiave significa rotazione più ricompilazione.
• Replit tiene separati i secret del workspace e quelli dei Deployments. Ciò che funzionava nell’editor, dopo la pubblicazione fallisce con una chiave vuota, finché non la aggiungi un’altra volta nel pannello Deployments.

Le ultime quattro righe della tabella non sono piattaforme, ma agenti nel tuo repository, e ognuno ha la propria allowlist di rete per la propria sandbox. Quando l’agente vorrà verificare il codice appena scritto, la chiamata a api.astroway.info potrebbe essere bloccata finché il dominio non viene aggiunto. Per loro c’è anche una via più breve: collega il nostro MCP e l’agente chiamerà l’API da solo, senza il tuo codice. Istruzioni in Configurazione dell’agente.

Nota

Dal 2 giugno 2026 Windsurf si chiama Devin Desktop, gli utenti sono stati migrati automaticamente, la documentazione si è spostata su docs.devin.ai. Tutto ciò che trovi oggi con il nome Windsurf è stato scritto prima di quella data.

Se il tuo agente parla function calling e non MCP

Prendi le definizioni degli strumenti già pronte e passale direttamente al modello. Sono generate dal documento OpenAPI, quindi lo schema che il modello compila è lo stesso che l’endpoint valida.

terminal

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

format accetta openai e anthropic, select restringe il catalogo al set iniziale invece di tutti gli strumenti.