URL कन्वेंशन्स और मुफ़्त एंडपॉइंट

अगर किसी सामान्य अनुरोध पर आपको 404 मिल रहा है, तो सबसे ज़्यादा संभावना है कि प्रीफ़िक्स गलत है या आप Swagger UI को किसी ग़ैर-मानक पाथ पर ढूँढ रहे हैं। यह पेज सभी कैनॉनिकल URL और एलियास दर्ज करता है।

पाथ प्रीफ़िक्स

सभी एंडपॉइंट /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> इस्तेमाल किया, तो हम error.code = "WRONG_PREFIX" फ़ील्ड और एक संकेत के साथ 404 लौटाते हैं - आपका SDK इसे हैंडल करके सही पाथ सुझा सकता है।

यह LLM प्रॉक्सी नहीं है

AstroWay एक ज्योतिषीय गणनाओं का API है, 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 प्रोवाइडर्स की सूची दो कारणों से प्रकाशित नहीं करते:

इंटीग्रेटर के लिए इस पर करने को कुछ नहीं। आप /v1/interpret/natal या /v1/horoscope/daily कॉल करते हैं - हमारा सर्वर ख़ुद कई प्रोवाइडर्स में से LLM चुनता है, स्वचालित फ़ॉलबैक के साथ। प्रोवाइडर बदलने से रिस्पॉन्स का आकार नहीं बदलता, सिर्फ़ latency और कभी-कभार शब्दों का चुनाव।
ऑपरेशनल आज़ादी। चेन बिना पूर्व सूचना के बदलती है (2026-05-18 को HuggingFace हटाया गया, NIM/ZAI जोड़े गए)। अगर हम कोई ठोस models[] घोषित करते, तो वह वास्तव में एक कॉन्ट्रैक्ट बन जाता।

AI सिर्फ़ एक implementation detail के रूप में मौजूद है /v1/interpret/* (जन्म कुंडली, सिनेस्ट्री, गोचर), /v1/horoscope/* (दैनिक/साप्ताहिक राशिफल), /v1/dev-assistant (डॉक्यूमेंटेशन सहायक) और /v1/reports/* (PDF नैरेटिव) में। बाक़ी 750+ एंडपॉइंट बिना AI के नियतात्मक Swiss Ephemeris हैं।

OpenAPI 3.1 स्पेसिफ़िकेशन

कैनॉनिकल पता है /v1/openapi.json। इंटीग्रेशन की सुविधा के लिए एलियास जोड़े गए हैं:

एलियास	कहाँ	क्यों मौजूद है
`/v1/swagger.json`	301 → `/v1/openapi.json`	Swagger 2.0 / openapi-generator convention
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	springdoc default
`/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`	Swagger UI होस्ट

इंटरैक्टिव Swagger UI /v1/docs पर उपलब्ध है (ब्राउज़र डॉक्यूमेंटेशन में /docs/api/ पर भी मिरर किया गया है)।

मुफ़्त सिस्टम एंडपॉइंट

इन पाथ्स को API कुंजी की ज़रूरत नहीं होती और ये क्रेडिट नहीं काटते - इन्हें किसी भी फ़्रंटएंड, मॉनिटरिंग या health-check से कॉल किया जा सकता है।

पाथ	क्या लौटाता है
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - तेज़ liveness probe
`GET /v1/health/deep`	हर DB की पहुँच की जाँच (UptimeRobot / Pingdom के लिए), अगर कम से कम एक DB उपलब्ध नहीं तो 503
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - SDK के लिए विस्तृत self-check
`GET /v1/openapi.json`	उदाहरणों और `x-codeSamples` के साथ पूरा OpenAPI 3.1 स्पेसिफ़िकेशन
`GET /v1/docs`	इंटरैक्टिव Swagger UI
`GET /v1/reference/*`	कैनॉनिकल संदर्भ (राशियाँ, ग्रह, भाव, दृष्टियाँ) - IP rate-limit, बिना कुंजी
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	भाषाओं की सूची और UI शब्दकोश - विजेट्स के लिए

मुफ़्त endpoints जिनके लिए रजिस्ट्रेशन ज़रूरी है

अकाउंट एंडपॉइंट सिर्फ़ JWT टोकन के साथ उपलब्ध हैं (लॉगिन पर जारी होता है), लेकिन प्लान के बैलेंस से क्रेडिट नहीं काटते।

प्रीफ़िक्स	यह क्या है
`/v1/auth/*`	रजिस्ट्रेशन, लॉगिन, refresh, password reset
`/v1/me`, `/v1/me/*`	प्रोफ़ाइल, आँकड़े, recent calls
`/v1/keys`, `/v1/keys/*`	API कुंजियों का प्रबंधन
`/v1/admin/*`	एडमिन पैनल (`api_role = admin` ज़रूरी)
`/v1/messages`	विजेट से फ़ीडबैक (गुमनाम, rate-limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	डॉक्यूमेंटेशन के लिए AI सहायक (गुमनाम, अलग लिमिट)
`/v1/widget-config`	विजेट के लिए Runtime feature-flags
`/v1/embed/*`	Embeddable iframe विजेट (IP rate-limit)
`/v1/oauth/*`	Google / GitHub login
`/v1/books/*`	Birth Book - अलग scope-JWT (WordPress mu-plugin जारी करता है)

पेड गणना एंडपॉइंट

सभी ज्योतिषीय गणनाएँ आपके टैरिफ़ प्लान से क्रेडिट काटती हैं। हर एक की सटीक लागत एंडपॉइंट्स की लागत पेज पर है। संक्षेप में:

Tier	क्रेडिट	उदाहरण
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`

कैश छूट: X-Cache: HIT (5 मिनट का idempotency-cache) - 0 क्रेडिट। AI एंडपॉइंट (/interpret/*) - cache hit पर 50% छूट।

रिस्पॉन्स हेडर में 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`

एजेंट हर पढ़े गए टोकन का भुगतान करता है। POST /v1/chart लगभग 32 KB लौटाता है, जबकि मॉडल को आमतौर पर उनमें से दो कॉलम चाहिए, और हर देशांतर दशमलव के बाद चौदह अंकों के साथ आता है, जबकि कोई भी एक कोणीय मिनट से ज़्यादा सटीक नहीं बनाता।

दो क्वेरी पैरामीटर इसे आख़िरी चरण पर हल करते हैं, इसलिए ये सभी एंडपॉइंट्स पर काम करते हैं:

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}'

जन्म कुंडली पर यह पैरामीटर जोड़ी 32 410 की जगह 511 बाइट देती है, यानी रिस्पॉन्स साठ गुना छोटा।

जो पाथ कुछ नहीं ढूँढ पाया, वह चुपचाप ग़ायब नहीं होता। वह रिस्पॉन्स के साथ _fields_unmatched फ़ील्ड में आता है: कुछ फ़ील्ड सच में वैकल्पिक होते हैं और किसी ख़ास रिस्पॉन्स में नहीं होते, इसलिए यह त्रुटि नहीं है। लेकिन जिस सूची में एक भी पाथ मेल नहीं खाया, वह टाइपिंग की गलती है, और वह सूची के साथ 400 FIELDS_UNKNOWN लौटाती है। चार्ट की जगह ख़ाली ऑब्जेक्ट एक आत्मविश्वास भरा गलत जवाब होता।

दोनों पैरामीटर query में जाते हैं, हेडर में नहीं, और यह जानबूझकर है: रिस्पॉन्स कैश की कुंजी मेथड, पाथ, बॉडी, क्रमबद्ध query और प्लान से बनती है। हेडर में मोड 2026-08-22 की घटना को दोहराता, जब Accept-Language कुंजी में शामिल नहीं था और जर्मन रिस्पॉन्स अगले उपयोगकर्ता को यूक्रेनी के रूप में दे दिया गया।

शेपिंग सिर्फ़ data पर लागू होती है। एनवेलप, _footer और _warning पूरे रहते हैं।

यही MCP के ज़रिए भी काम करता है। mcp.astroway.info पर हर टूल अपने पैरामीटर्स के साथ fields और precision स्वीकार करता है और उन्हें उसी query से API को भेजता है। MCP के ज़रिए जन्म कुंडली 91 737 बाइट की थी, क्योंकि डेटा दो बार आता था: इंडेंटेशन वाले टेक्स्ट ब्लॉक में और स्ट्रक्चर्ड फ़ील्ड में। उन्हीं तीन पाथ और precision: 2 के साथ यह 1 182 बाइट है।

जन्म कुंडली की कॉल	बाइट
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 स्वीकार करते हैं (सिनेस्ट्री में इसे किसी भी साथी के लिए अलग से सेट किया जा सकता है)। बाक़ी एंडपॉइंट भावों या कोणों पर निर्भर हैं और 400 TIME_UNKNOWN_UNSUPPORTED लौटाते हैं: चुपचाप अनदेखा किए गए फ़्लैग और रिस्पॉन्स में गढ़े गए लग्न से स्पष्ट त्रुटि बेहतर है।

API वर्ज़निंग

Major वर्ज़न URL में है (/v1/)। Breaking बदलाव सिर्फ़ /v2/ के साथ आते हैं, in-place नहीं। विवरण - वर्ज़निंग।

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 इसे स्टार्ट पर “व्यवहार अचानक अलग क्यों है” की डीबगिंग के लिए कॉल कर सकते हैं - build_commit फ़ील्ड डिप्लॉय की सटीक पहचान करता है।

गलत कॉल जो हम सबसे ज़्यादा देखते हैं

90 दिनों के प्रोडक्शन लॉग के विश्लेषण से, इंटीग्रेटर की 5 आम गलतियाँ:

/v1/<endpoint> की जगह /api/<endpoint>: WordPress wp-json की आदत। अब हम hint के साथ JSON 404 लौटाते हैं।
/v1/v1/<endpoint>: SDK baseUrl = .../v1 के साथ कॉन्फ़िगर है और ऊपर से /v1/X जोड़ देता है। अब 308 redirect।
/v1/openapi.json की जगह /swagger.json: Postman/Insomnia auto-probe। अब 301 redirect।
Authorization: Bearer <jwt> के बिना /v1/me, /v1/auth/keys/me → 401। जाँचें कि टोकन हेडर में भेजा जा रहा है या नहीं।
embed टोकन की जगह API कुंजी के साथ /v1/embed/natal → 401। Embed एंडपॉइंट dashboard से सार्वजनिक embed-token स्वीकार करते हैं, API कुंजी नहीं।