Prompts για AI builders

Ο builder θα γράψει κώδικα πιο γρήγορα από εσάς. Αυτό που δεν ξέρει είναι δύο πράγματα για το συγκεκριμένο API: πού να βάλει το κλειδί και γιατί το αίτημα από τον browser δεν περνά. Και τα δύο κοστίζουν ώρες αποσφαλμάτωσης, και τα δύο λύνονται με μία παράγραφο στο prompt.

Παρακάτω πρώτα αυτή η παράγραφος και μετά επτά συνταγές.

Ο κανόνας που μπαίνει πριν από κάθε συνταγή

Αντιγράψτε αυτό το μπλοκ στον builder πριν από το κείμενο της συνταγής. Δεν αφορά το στυλ του κώδικα, αφορά αυτά που αλλιώς δεν θα δουλέψουν.

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.

Προσοχή

Το σημείο 2 είναι μετρημένο, όχι υπόθεση: μια δοκιμαστική σελίδα σε ξένο origin παίρνει απάντηση από το /v1/public/*, ενώ το POST /v1/chart μπλοκάρεται από τον browser. Ένα δημόσιο κλειδί pk_* δεν το αλλάζει αυτό, ανοίγει μόνο τα /v1/public/* και /v1/embed/*.

1. Γενέθλιος χάρτης με τροχό

Δύο απαντήσεις σε μία ενέργεια του χρήστη: τα δεδομένα του χάρτη και έτοιμο SVG.

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

Ελέγξτε μετά τη δημιουργία: το SVG έχει μπει ως markup και όχι σε <img src>, η ώρα στάλθηκε ως συμβολοσειρά HH:mm:ss, το κλειδί δεν κατέληξε στο bundle (μια αναζήτηση για aw_ στα αρχεία του build δεν πρέπει να βρει τίποτα).

2. Συμβατότητα δύο χαρτών

Ένας αριθμός και οι συνιστώσες του, χωρίς επεξηγηματικό κείμενο. /v1/synastry/attraction-score, 50 credits ανά ζευγάρι.

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. Ημερήσιο ωροσκόπιο, χωρίς κανένα κλειδί

Η μόνη συνταγή όπου δεν χρειάζεται διαδρομή στον server: αυτό το endpoint απαντά στον browser και δεν κοστίζει credits.

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.

Σημείωση

Το όριο εδώ είναι ανά IP, 30 αιτήματα την ώρα για κλήσεις χωρίς κλειδί. Για μια σελίδα με ένα μπλοκ ωροσκοπίου αρκεί. Για λίστα με και τα δώδεκα ζώδια ταυτόχρονα, όχι.

4. Human Design

Τύπος, στρατηγική, αυθεντία, προφίλ, κέντρα και κανάλια με μία κλήση στο /v1/human-design, 50 credits.

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. Αναφορά PDF με το brand του χρήστη

Για όσους πουλούν αναφορές και όχι οθόνες. /v1/reports/natal, 5000 credits ανά έγγραφο, και ο σύνδεσμος ισχύει 24 ώρες.

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.

Ο πλήρης κατάλογος με τις δεκαέξι αναφορές, τι περιέχει η καθεμία και πόσες σελίδες έχει: Reports API.

6. Ημερολόγιο διελεύσεων για τον μήνα

Λίστα γεγονότων σε ένα παράθυρο ημερομηνιών, από την οποία βγαίνει και ροή και ημερολόγιο. /v1/transit-calendar, 100 credits ανά παράθυρο.

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. Άνοιγμα ταρώ

Ο φθηνότερος τρόπος να προσθέσετε καθημερινή αλληλεπίδραση. /v1/tarot/rider-waite/draw/three-card, 10 credits ανά άνοιγμα, ή μηδέν για την κάρτα της ημέρας.

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.

Οκτώ builders, μία διαφορά

Οι παραπάνω συνταγές είναι ίδιες για όλους. Η διαφορά είναι μόνο πού ζει η διαδρομή του server και πού μπαίνει το κλειδί.

Builder	Πού ζει η κλήση στον server	Πού μπαίνει το κλειδί
Lovable	edge function στο Supabase	Secrets του project στο Supabase
Bolt	server function	πάνελ Secrets στο Bolt
v0	route handler του Next.js σε Vercel Functions	environment variable στο Vercel, τύπου Secret
Replit	κανονική διεργασία server	Replit Secrets, και ξανά ξεχωριστά στα Deployments
Cursor, Claude Code, Devin Desktop, Copilot	όποια υπάρχει στο stack σας	.env εκτός git, συν ο χώρος secrets του hosting σας

Τέσσερις ξεχωριστές παγίδες, η καθεμία κοστίζει ένα βράδυ.

• Τα Lovable και Bolt κάνουν build το frontend με Vite, και το Vite δίνει στον browser κάθε μεταβλητή με πρόθεμα VITE_. Το κλειδί δεν μπαίνει εκεί ούτε προσωρινά: θα καταλήξει σε ένα bundle που μοιράζεται σε όλους.
• Το Bolt δείχνει την προεπισκόπηση μέσα σε WebContainer, που είναι πραγματικός browser με πραγματικό CORS, το οποίο εκεί δεν απενεργοποιείται. Η server function εδώ δεν είναι “καλύτερη”, είναι ο μόνος τρόπος να γίνει καν η κλήση.
• Το v0 ενσωματώνει τα NEXT_PUBLIC_* στο bundle κατά το build. Δεν αρκεί να αλλάξετε την τιμή στο dashboard: μέχρι να γίνει νέο deploy, η εφαρμογή τρέχει με το παλιό κλειδί. Εναλλαγή κλειδιού σημαίνει εναλλαγή συν νέο build.
• Το Replit κρατά χωριστά τα secrets του workspace και τα secrets των Deployments. Ό,τι δούλευε στον editor, μετά τη δημοσίευση αποτυγχάνει με κενό κλειδί, μέχρι να το προσθέσετε ξανά στο πάνελ Deployments.

Οι τέσσερις τελευταίες γραμμές του πίνακα δεν είναι πλατφόρμες αλλά agents μέσα στο repository σας, και ο καθένας έχει δική του λίστα επιτρεπόμενων δικτύων για το sandbox του. Όταν ο agent θελήσει να ελέγξει τον κώδικα που μόλις έγραψε, η κλήση στο api.astroway.info μπορεί να μπλοκαριστεί μέχρι να προστεθεί το domain. Για αυτούς υπάρχει και συντομότερος δρόμος: συνδέστε το MCP μας και ο agent θα καλέσει το API μόνος του, χωρίς τον δικό σας κώδικα. Οδηγίες στη σελίδα Ρύθμιση agent.

Σημείωση

Το Windsurf από τις 2 Ιουνίου 2026 λέγεται Devin Desktop, οι χρήστες μεταφέρθηκαν αυτόματα και η τεκμηρίωση μετακόμισε στο docs.devin.ai. Ό,τι βρίσκετε σήμερα με το όνομα Windsurf γράφτηκε πριν από αυτή την ημερομηνία.

Αν ο agent σας μιλά function calling και όχι MCP

Πάρτε τους έτοιμους ορισμούς εργαλείων και δώστε τους απευθείας στο μοντέλο. Παράγονται από το έγγραφο OpenAPI, οπότε το schema που συμπληρώνει το μοντέλο είναι το ίδιο που ελέγχει το endpoint.

terminal

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

Το format δέχεται openai και anthropic, το select περιορίζει τον κατάλογο σε ένα αρχικό σύνολο αντί για όλα τα εργαλεία.