Συμβάσεις URL και δωρεάν endpoints

Αν βλέπεις 404 σε ένα τυπικό αίτημα, το πιθανότερο είναι ότι το πρόθεμα είναι λάθος ή ότι ψάχνεις το Swagger UI σε μη τυπική διαδρομή. Αυτή η σελίδα καταγράφει όλα τα κανονικά URL και τα aliases.

Πρόθεμα διαδρομής

Όλα τα endpoints βρίσκονται κάτω από το /v1/. Άλλα προθέματα δεν υπάρχουν.

✅ https://api.astroway.info/v1/chart
✅ https://api.astroway.info/v1/health
❌ https://api.astroway.info/api/chart        - 404 (missing /v1/ prefix)
❌ https://api.astroway.info/api/v1/chart     - 404 (our internal path, not exposed)
❌ https://api.astroway.info/v1/v1/chart      - 308 redirect to /v1/chart (typical SDK base-URL bug fix)

Αν κατά λάθος χρησιμοποίησες /api/<endpoint>, επιστρέφουμε 404 με το πεδίο error.code = "WRONG_PREFIX" και μια υπόδειξη: το SDK σου μπορεί να το χειριστεί και να προτείνει τη σωστή διαδρομή.

Δεν είναι LLM proxy

Το AstroWay είναι API αστρολογικών υπολογισμών, όχι proxy για LLM. Αν έρχεσαι με τη μυϊκή μνήμη του OpenAI SDK και δοκιμάσεις απλώς να αλλάξεις το base_url στο δικό μας, δεν θα λειτουργήσει:

❌ POST /v1/chat/completions            - doesn't exist
❌ POST /v1/completions                 - doesn't exist
❌ GET  /v1/models                      - doesn't exist (deliberately)
❌ POST /v1/embeddings                  - doesn't exist

Δεν δημοσιεύουμε τη λίστα των AI providers για δύο λόγους:

Δεν είναι αξιοποιήσιμη για τον integrator. Καλείς /v1/interpret/natal ή /v1/horoscope/daily και ο server μας επιλέγει μόνος του LLM από αρκετούς providers με αυτόματο fallback. Η αλλαγή provider δεν αλλάζει τη μορφή της απάντησης, μόνο το latency και περιστασιακά τη διατύπωση.
Λειτουργική ελευθερία. Η αλυσίδα αλλάζει χωρίς προειδοποίηση (αφαίρεση του HuggingFace 2026-05-18, προσθήκη NIM/ZAI). Αν ανακοινώναμε ένα συγκεκριμένο models[], θα γινόταν de facto συμβόλαιο.

Το AI υπάρχει μόνο ως λεπτομέρεια υλοποίησης στα /v1/interpret/* (γενέθλιος χάρτης, συναστρία, διελεύσεις), /v1/horoscope/* (ημερήσιο/εβδομαδιαίο ωροσκόπιο), /v1/dev-assistant (βοηθός τεκμηρίωσης) και /v1/reports/* (αφηγήσεις PDF). Τα υπόλοιπα 750+ endpoints είναι ντετερμινιστικό Swiss Ephemeris χωρίς AI.

Προδιαγραφή OpenAPI 3.1

Η κανονική διεύθυνση είναι /v1/openapi.json. Για ευκολία στις ενσωματώσεις προστέθηκαν aliases:

Alias	Πού οδηγεί	Γιατί υπάρχει
`/v1/swagger.json`	301 → `/v1/openapi.json`	Σύμβαση Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Προεπιλογή springdoc
`/v1/v3/api-docs`	301 → `/v1/openapi.json`	Spring Boot 3
`/v1/v2/api-docs`	301 → `/v1/openapi.json`	Spring Boot 2
`/v1/swagger/v1/swagger.json`	301 → `/v1/openapi.json`	ASP.NET Core
`/v1/swagger`, `/v1/swagger-ui`, `/v1/swagger-ui.html`	302 → `/v1/docs`	Host του Swagger UI

Το διαδραστικό Swagger UI είναι διαθέσιμο στο /v1/docs (και αντικατοπτρίζεται στην τεκμηρίωση του browser στο /docs/api/).

Δωρεάν endpoints συστήματος

Αυτές οι διαδρομές δεν απαιτούν κλειδί API και δεν χρεώνουν credits: μπορούν να κληθούν από οποιοδήποτε frontend, monitoring ή health-check.

Διαδρομή	Τι επιστρέφει
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - γρήγορο liveness probe
`GET /v1/health/deep`	Έλεγχος προσβασιμότητας ανά βάση δεδομένων (για UptimeRobot / Pingdom), 503 αν έστω και μία βάση δεν είναι διαθέσιμη
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - λεπτομερής self-check για SDK
`GET /v1/openapi.json`	Πλήρης προδιαγραφή OpenAPI 3.1 με παραδείγματα + `x-codeSamples`
`GET /v1/docs`	Διαδραστικό Swagger UI
`GET /v1/reference/*`	Κανονικοί κατάλογοι αναφοράς (ζώδια, πλανήτες, οίκοι, όψεις) - IP rate limit, χωρίς κλειδί
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Λίστα γλωσσών και λεξικά UI - για widgets

Δωρεάν endpoints που απαιτούν εγγραφή

Τα endpoints λογαριασμού είναι διαθέσιμα μόνο με JWT token (εκδίδεται κατά τη σύνδεση), αλλά δεν χρεώνουν credits από το υπόλοιπο του πλάνου.

Πρόθεμα	Τι είναι
`/v1/auth/*`	Εγγραφή, σύνδεση, refresh, επαναφορά κωδικού
`/v1/me`, `/v1/me/*`	Προφίλ, στατιστικά, πρόσφατες κλήσεις
`/v1/keys`, `/v1/keys/*`	Διαχείριση κλειδιών API
`/v1/admin/*`	Πίνακας διαχείρισης (απαιτεί `api_role = admin`)
`/v1/messages`	Ανατροφοδότηση από το widget (ανώνυμα, rate limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	AI βοηθός τεκμηρίωσης (ανώνυμα, ξεχωριστό όριο)
`/v1/widget-config`	Runtime feature flags για το widget
`/v1/embed/*`	Ενσωματώσιμα iframe widgets (IP rate limit)
`/v1/oauth/*`	Σύνδεση με Google / GitHub
`/v1/books/*`	Birth Book - ξεχωριστό scope JWT (εκδίδεται από το WordPress mu-plugin)

Επί πληρωμή endpoints υπολογισμών

Όλοι οι αστρολογικοί υπολογισμοί χρεώνουν credits από το πλάνο σου. Το ακριβές κόστος καθενός βρίσκεται στη σελίδα Κόστος endpoints. Συνοπτικά:

Tier	Credits	Παραδείγματα
0	0	`/v1/reference/*` - δημόσιοι κατάλογοι αναφοράς, χωρίς κλειδί
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog` - στατικοί πίνακες
1	10	`/v1/planets`, `/v1/sun-times`, `/v1/moon-phase`
2	20	`/v1/chart`, `/v1/harmonics`, `/v1/horary`
3	50	`/v1/synastry`, `/v1/progressions`, `/v1/acg`
4	100	`/v1/transit-calendar`, `/v1/group-synastry`
5	250	`/v1/rectification/trutine`, AI αφηγήσεις `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	Αναφορές PDF: `/v1/reports/natal`, `/v1/reports/synastry`

Εκπτώσεις cache: X-Cache: HIT (idempotency cache 5 λεπτών) - 0 credits. AI endpoints (/interpret/*) - 50% έκπτωση σε cache hit.

Οι κεφαλίδες της απάντησης περιέχουν X-Credits-Used, X-Credits-Remaining, X-Credits-Limit: τα SDK μπορούν να παρακολουθούν αυτόματα το υπόλοιπο.

Γλώσσα στις απαντήσεις

Η γλώσσα ορίζεται με ?lang= ή με την κεφαλίδα Accept-Language. Υποστηρίζονται 21 γλώσσες.

Τα πεδία από κλειστά σύνολα (ζώδια, πλανήτες, ημέρες της εβδομάδας, φάσεις της Σελήνης, λεξιλόγιο Human Design, ονόματα των Μεγάλων Αρκάνων του Ταρώ) επιστρέφονται δύο φορές: το αγγλικό αναγνωριστικό μένει στη θέση του ως σταθερό συμβόλαιο, και δίπλα έρχεται ένα αντικείμενο localized με τη μετάφραση:

{
  "phaseName": "Waxing Gibbous",
  "moonSign": "Capricorn",
  "localized": { "phaseName": "Zunehmender Mond", "moonSign": "Steinbock", "sunSign": "Löwe" }
}

Σύγκρινε τις αγγλικές τιμές, εμφάνιζε το localized. Αυτά τα ονόματα προέρχονται από ρητό πίνακα όρων στον κώδικα, όχι από μηχανική μετάφραση: η ορολογία δεν μεταφράζεται λέξη προς λέξη, αλλιώς μια φάση της Σελήνης γίνεται οικονομικός όρος.

Στο Human Design τα κέντρα στο localized.centers έχουν ως κλειδιά τα ίδια αναγνωριστικά με το centers[].name, οπότε η αντιστοίχιση γίνεται με βάση το κλειδί και όχι με βάση τη μεταφρασμένη συμβολοσειρά. Στο Ταρώ το ίδιο κάνει το localized.cards, με κλειδί το slug της κάρτας.

Τα πεδία από ανοιχτά σύνολα είναι προς το παρόν αγγλικά και τεκμηριωμένα ως τέτοια: τα themes[] του πλανήτη της ημέρας, οι λέξεις-κλειδιά και οι σημασίες των καρτών Ταρώ, τα ονόματα των καναλιών και των πυλών του Human Design. Τα ονόματα των Μικρών Αρκάνων συντίθενται από παγιωμένες μορφές βαθμού και χρώματος, οπότε ολόκληρη η τράπουλα των 78 καρτών είναι μεταφρασμένη και το nameLocalized γι’ αυτήν είναι true. Το πεδίο μένει false μόνο όπου ο πίνακας δεν μπορεί να δώσει όνομα. Τα ανοιχτά σύνολα μετάφρασέ τα στη δική σου πλευρά ή περίμενε τα ξεχωριστά λεξικά.

Συμπαγής απάντηση: `fields` και `precision`

Ένας agent πληρώνει για κάθε token που διαβάζει. Το POST /v1/chart επιστρέφει περίπου 32 KB, ενώ το μοντέλο συνήθως χρειάζεται δύο στήλες από αυτά, και κάθε μήκος έρχεται με δεκατέσσερα δεκαδικά ψηφία εκεί όπου κανείς δεν χρειάζεται ακρίβεια καλύτερη από ένα λεπτό της μοίρας.

Δύο παράμετροι του αιτήματος το λύνουν στο τελευταίο βήμα, γι’ αυτό λειτουργούν σε όλα τα endpoints:

fields - λίστα διαδρομών χωρισμένων με κόμμα, σχετικά με το data. Η διαδρομή εφαρμόζεται σε κάθε στοιχείο πίνακα, οπότε το planets.name σημαίνει το όνομα κάθε πλανήτη, όχι κλειδί του πίνακα.
precision - ακέραιος από 0 έως 15, στρογγυλοποιεί όλους τους μη ακέραιους αριθμούς της απάντησης. Τους ακέραιους δεν τους αγγίζει: ένα αναγνωριστικό δεν είναι μέτρηση.

curl -X POST "https://api.astroway.info/v1/chart?fields=planets.name,planets.longitude&precision=2" \
  -H "X-Api-Key: aw_live_..." -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezone":"Europe/Kyiv","latitude":50.45,"longitude":30.52}'

Αυτό το ζεύγος παραμέτρων σε έναν γενέθλιο χάρτη δίνει 511 bytes αντί για 32 410, δηλαδή απάντηση εξήντα φορές μικρότερη.

Μια διαδρομή που δεν βρήκε τίποτα δεν εξαφανίζεται σιωπηλά. Επιστρέφεται στο πεδίο _fields_unmatched δίπλα στην απάντηση: κάποια πεδία είναι πράγματι προαιρετικά και λείπουν από μια συγκεκριμένη απάντηση, οπότε δεν είναι σφάλμα. Αντίθετα, μια λίστα όπου δεν ταίριαξε καμία διαδρομή είναι τυπογραφικό λάθος και επιστρέφει 400 FIELDS_UNKNOWN με την αναλυτική λίστα. Ένα κενό αντικείμενο αντί για χάρτη θα ήταν μια σίγουρη λανθασμένη απάντηση.

Και οι δύο παράμετροι πηγαίνουν στο query, όχι σε κεφαλίδα, και αυτό είναι σκόπιμο: η cache των απαντήσεων έχει κλειδί τη μέθοδο, τη διαδρομή, το body, το ταξινομημένο query και το πλάνο. Μια λειτουργία σε κεφαλίδα θα επαναλάμβανε το περιστατικό της 2026-08-22, όταν το Accept-Language δεν ήταν μέρος του κλειδιού και μια γερμανική απάντηση δόθηκε στον επόμενο ως ουκρανική.

Η διαμόρφωση αφορά μόνο το data. Ο φάκελος, το _footer και το _warning μένουν ακέραια.

Το ίδιο λειτουργεί και μέσω MCP. Κάθε εργαλείο στο mcp.astroway.info δέχεται fields και precision δίπλα στις δικές του παραμέτρους και τις περνά στο API με το ίδιο query. Ένας γενέθλιος χάρτης μέσω MCP ζύγιζε 91 737 bytes, γιατί τα δεδομένα έρχονταν δύο φορές: ως μπλοκ κειμένου με εσοχές και ως δομημένο πεδίο. Με τις ίδιες τρεις διαδρομές και precision: 2 είναι 1 182 bytes.

Κλήση γενέθλιου χάρτη	Bytes
MCP, όπως ήταν πριν από τις 21.09.2026	91 737
MCP, χωρίς εσοχές στο μπλοκ κειμένου	72 484
MCP, `precision: 2`	61 356
MCP, τρεις διαδρομές στο `fields` μαζί με `precision: 2`	1 182
REST, τρεις διαδρομές στο `fields` μαζί με `precision=2`	559

Άγνωστη ώρα γέννησης

Ένα σημαντικό μέρος των τελικών χρηστών δεν γνωρίζει την ακριβή ώρα γέννησής του. Αν βάλεις ένα υποθετικό μεσημέρι και υπολογίσεις τον χάρτη κανονικά, η απάντηση θα έχει ωροσκόπο και ακμές οίκων που φαίνονται αξιόπιστα, αλλά σφάλλουν περίπου κατά ένα ζώδιο για κάθε δύο ώρες απόκλισης.

Γι’ αυτό, αντί για time μπορείς να περάσεις timeUnknown: true:

curl -X POST https://api.astroway.info/v1/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-03-15","timeUnknown":true,"timezoneOffset":2,"latitude":50.45,"longitude":30.52}'

Τι επιστρέφει το API σε αυτή τη λειτουργία:

Πεδίο	Τιμή
`planets`	υπολογισμένοι για το τοπικό μεσημέρι
`aspects`	υπολογισμένες, αλλά οι όψεις με τη Σελήνη δεν είναι αξιόπιστες (βλ. παρακάτω)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	μπλοκ με εξήγηση: τι ακριβώς παραλείφθηκε και πού μπορεί να βρίσκεται η Σελήνη

Το μπλοκ timeUnknown.moon περιέχει το μήκος της Σελήνης στην αρχή και στο τέλος της ημέρας, το τόξο που διανύθηκε μέσα στην ημέρα (11.8-15.4°), τη λίστα των ζωδίων στα οποία βρέθηκε και τη σημαία changesSign. Η Σελήνη μπορεί να αλλάξει ζώδιο μέσα σε μια ημέρα, γι’ αυτό αυτό το εύρος αξίζει να εμφανίζεται στον χρήστη και όχι να κρύβεται πίσω από έναν αριθμό.

Τη σημαία τη δέχονται τα /v1/chart και /v1/synastry (στη συναστρία μπορεί να οριστεί ξεχωριστά για οποιονδήποτε από τους δύο συντρόφους). Τα υπόλοιπα endpoints εξαρτώνται από τους οίκους ή τις γωνίες και απαντούν 400 TIME_UNKNOWN_UNSUPPORTED: καλύτερα ένα ρητό σφάλμα παρά μια σιωπηλά αγνοημένη σημαία και ένας επινοημένος ωροσκόπος στην απάντηση.

Εκδόσεις του API

Major έκδοση στο URL (/v1/). Οι breaking changes έρχονται μόνο με /v2/, όχι επί τόπου. Λεπτομέρειες: Εκδόσεις.

Το GET /v1/version επιστρέφει το τρέχον deploy:

curl https://api.astroway.info/v1/version
# {
#   "version": "2.71.0",
#   "build_commit": "abc1234",
#   "started_at": "2026-05-27T10:42:00Z",
#   "uptime_seconds": 12345,
#   "docs_url": "https://api.astroway.info/docs/api/"
# }

Τα SDK μπορούν να το καλούν κατά την εκκίνηση για debugging του τύπου “γιατί ξαφνικά η συμπεριφορά είναι διαφορετική”: το πεδίο build_commit αναγνωρίζει με ακρίβεια το deploy.

Λανθασμένες κλήσεις που βλέπουμε συχνότερα

Από την ανάλυση των logs του production για 90 ημέρες, 5 τυπικά λάθη των integrators:

/api/<endpoint> αντί για /v1/<endpoint>: συνήθεια από το WordPress wp-json. Τώρα επιστρέφουμε JSON 404 με υπόδειξη.
/v1/v1/<endpoint>: το SDK είναι ρυθμισμένο με baseUrl = .../v1 και προσθέτει από πάνω /v1/X. Τώρα 308 redirect.
/swagger.json αντί για /v1/openapi.json: αυτόματος έλεγχος του Postman/Insomnia. Τώρα 301 redirect.
/v1/me, /v1/auth/keys/me χωρίς Authorization: Bearer <jwt> → 401. Έλεγξε ότι το token περνά στην κεφαλίδα.
/v1/embed/natal με κλειδί API αντί για embed token → 401. Τα embed endpoints δέχονται δημόσιο embed token από το dashboard, όχι κλειδί API.