Konvensi URL dan endpoint gratis

Jika Anda mendapat 404 pada permintaan biasa, kemungkinan besar prefiksnya salah atau Anda mencari Swagger UI di path yang tidak standar. Halaman ini mencatat semua URL kanonis beserta aliasnya.

Prefiks path

Semua endpoint berada di bawah /v1/. Tidak ada prefiks lain.

✅ 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)

Jika Anda keliru memakai /api/<endpoint>, kami mengembalikan 404 dengan field error.code = "WRONG_PREFIX" dan petunjuk, sehingga SDK Anda bisa menanganinya dan menyarankan path yang benar.

Ini bukan proxy LLM

AstroWay adalah API perhitungan astrologi, bukan proxy untuk LLM. Jika Anda datang dengan kebiasaan OpenAI SDK dan mencoba sekadar mengganti base_url ke milik kami, itu tidak akan berhasil:

❌ 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

Kami tidak memublikasikan daftar penyedia AI karena dua alasan:

1. Tidak berguna bagi integrator. Anda memanggil /v1/interpret/natal atau /v1/horoscope/daily, dan server kami sendiri yang memilih LLM dari beberapa penyedia dengan fallback otomatis. Pergantian penyedia tidak mengubah bentuk respons, hanya latensi dan sesekali susunan kalimatnya.
2. Kebebasan operasional. Rantai penyedia berubah tanpa pemberitahuan (HuggingFace dikeluarkan pada 2026-05-18, NIM/ZAI ditambahkan). Jika kami mengumumkan models[] tertentu, daftar itu akan menjadi kontrak de facto.

AI hanya hadir sebagai detail implementasi di /v1/interpret/* (natal, sinastri, transit), /v1/horoscope/* (horoskop harian/mingguan), /v1/dev-assistant (asisten dokumentasi) dan /v1/reports/* (narasi PDF). Sisanya, 750+ endpoint, adalah Swiss Ephemeris deterministik tanpa AI.

Spesifikasi OpenAPI 3.1

Alamat kanonisnya adalah /v1/openapi.json. Untuk memudahkan integrasi, tersedia alias:

Alias	Ke mana	Mengapa ada
/v1/swagger.json	301 → /v1/openapi.json	Konvensi Swagger 2.0 / openapi-generator
/v1/api-docs/swagger.json	301 → /v1/openapi.json	default 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 interaktif tersedia di /v1/docs (juga dicerminkan dalam dokumentasi browser di /docs/api/).

Endpoint sistem gratis

Path berikut tidak memerlukan API key dan tidak memotong kredit, sehingga bisa dipanggil dari frontend mana pun, sistem monitoring, atau health-check.

Path	Yang dikembalikan
GET /v1/health	{status, version, uptime_seconds, timestamp} - liveness probe cepat
GET /v1/health/deep	Pemeriksaan keterjangkauan per database (untuk UptimeRobot / Pingdom), 503 jika setidaknya satu database tidak tersedia
GET /v1/version	{version, build_commit, started_at, uptime_seconds, docs_url} - self-check terperinci untuk SDK
GET /v1/openapi.json	Spesifikasi OpenAPI 3.1 lengkap dengan contoh + x-codeSamples
GET /v1/docs	Swagger UI interaktif
GET /v1/reference/*	Referensi kanonis (zodiak, planet, rumah, aspek) - rate limit per IP, tanpa key
GET /v1/i18n/langs, GET /v1/i18n/dict/:lang	Daftar bahasa dan kamus UI - untuk widget

Endpoint gratis yang memerlukan pendaftaran

Endpoint akun hanya bisa diakses dengan token JWT (diterbitkan saat login), tetapi tidak memotong kredit dari saldo paket.

Prefiks	Apa itu
/v1/auth/*	Pendaftaran, login, refresh, reset kata sandi
/v1/me, /v1/me/*	Profil, statistik, panggilan terakhir
/v1/keys, /v1/keys/*	Pengelolaan API key
/v1/admin/*	Panel admin (memerlukan api_role = admin)
/v1/messages	Umpan balik dari widget (anonim, rate limit)
/v1/dev-assistant, /v1/dev-assistant/stream	Asisten AI untuk dokumentasi (anonim, limit terpisah)
/v1/widget-config	Feature flag runtime untuk widget
/v1/embed/*	Widget iframe yang bisa disematkan (rate limit per IP)
/v1/oauth/*	Login Google / GitHub
/v1/books/*	Birth Book - JWT dengan scope terpisah (diterbitkan oleh mu-plugin WordPress)

Endpoint perhitungan berbayar

Semua perhitungan astrologi memotong kredit dari paket tarif Anda. Biaya pasti tiap endpoint ada di halaman Biaya endpoint. Ringkasnya:

Tier	Kredit	Contoh
0	0	/v1/reference/* - referensi publik, tanpa key
½	5	/v1/kabbalah/sephiroth, /v1/fixed-stars/catalog - tabel statis
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, narasi AI /v1/reports/ai/*
6	500	/v1/rectification
7	5000	Laporan PDF: /v1/reports/natal, /v1/reports/synastry

Diskon cache: X-Cache: HIT (cache idempotensi 5 menit) - 0 kredit. Endpoint AI (/interpret/*) - diskon 50% saat cache hit.

Header respons berisi X-Credits-Used, X-Credits-Remaining, X-Credits-Limit, sehingga SDK bisa melacak saldo secara otomatis.

Bahasa dalam respons

Bahasa ditentukan lewat ?lang= atau header Accept-Language. Tersedia 21 bahasa.

Field dari himpunan tertutup (zodiak, planet, hari dalam seminggu, fase Bulan, kosakata Human Design, nama Arkana Mayor Tarot) dikembalikan dua kali: identifikator bahasa Inggris tetap di tempatnya sebagai kontrak yang stabil, dan di sebelahnya datang objek localized berisi terjemahan:

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

Bandingkan nilai bahasa Inggris, tampilkan localized. Nama-nama ini diambil dari tabel istilah eksplisit di dalam kode, bukan dari terjemahan mesin: terminologi tidak boleh diterjemahkan kata per kata, kalau tidak fase Bulan bisa berubah menjadi istilah keuangan.

Di Human Design, pusat dalam localized.centers memakai kunci yang sama dengan centers[].name, sehingga pencocokan dilakukan berdasarkan kunci, bukan string terjemahan. Di Tarot hal yang sama dilakukan oleh localized.cards, dengan kunci berupa slug kartu.

Field dari himpunan terbuka untuk saat ini masih berbahasa Inggris dan didokumentasikan demikian: themes[] pada planet hari ini, kata kunci dan makna kartu Tarot, nama channel dan gate Human Design. Nama Arkana Minor disusun dari bentuk baku peringkat dan setelan kartu, jadi seluruh dek 78 kartu sudah terlokalisasi dan nameLocalized bernilai true; field ini tetap false hanya jika tabel tidak bisa memberikan nama. Terjemahkan himpunan terbuka di sisi Anda atau tunggu kamus terpisah.

Respons ringkas: fields dan precision

Agen membayar setiap token yang dibacanya. POST /v1/chart mengembalikan sekitar 32 KB, padahal model biasanya hanya butuh dua kolom darinya, dan setiap longitude datang dengan empat belas angka di belakang koma, padahal tidak ada yang membangun lebih presisi dari satu menit busur.

Dua parameter query menyelesaikan ini di langkah terakhir, sehingga berlaku di semua endpoint:

• fields - daftar path yang dipisahkan koma, relatif terhadap data. Path diterapkan ke setiap elemen array, jadi planets.name berarti nama setiap planet, bukan kunci array.
• precision - bilangan bulat dari 0 sampai 15, membulatkan semua angka non-bulat dalam respons. Bilangan bulat tidak disentuh: identifikator bukan besaran ukur.

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

Pasangan parameter ini pada peta natal menghasilkan 511 byte, bukan 32 410, artinya respons enam puluh kali lebih kecil.

Path yang tidak menemukan apa pun tidak hilang diam-diam. Path itu muncul di field _fields_unmatched di samping respons: sebagian field memang opsional dan tidak ada dalam respons tertentu, jadi ini bukan error. Namun daftar yang tidak satu pun path-nya cocok adalah salah ketik, dan mengembalikan 400 FIELDS_UNKNOWN beserta daftarnya. Objek kosong sebagai ganti peta adalah jawaban salah yang terlihat meyakinkan.

Kedua parameter dikirim lewat query, bukan header, dan ini disengaja: cache respons diberi kunci berdasarkan metode, path, body, query yang diurutkan, dan paket. Mode lewat header akan mengulang insiden 2026-08-22, ketika Accept-Language tidak masuk ke kunci dan respons berbahasa Jerman diberikan ke pengguna berikutnya sebagai respons berbahasa Ukraina.

Pembentukan ini hanya berlaku untuk data. Envelope, _footer, dan _warning tetap utuh.

Hal yang sama berlaku lewat MCP. Setiap tool di mcp.astroway.info menerima fields dan precision di samping parameternya sendiri dan meneruskannya ke API sebagai query yang sama. Peta natal lewat MCP dulu berukuran 91 737 byte, karena datanya datang dua kali: sebagai blok teks dengan indentasi dan sebagai field terstruktur. Dengan tiga path yang sama dan precision: 2, ukurannya 1 182 byte.

Panggilan peta natal	Byte
MCP, seperti sebelum 21.09.2026	91 737
MCP, tanpa indentasi di blok teks	72 484
MCP, precision: 2	61 356
MCP, tiga path di fields plus precision: 2	1 182
REST, tiga path di fields plus precision=2	559

Waktu lahir tidak diketahui

Sebagian besar pengguna akhir tidak tahu waktu lahir yang tepat. Jika Anda mengisi tengah hari sebagai perkiraan dan menghitung peta seperti biasa, respons akan berisi ascendant dan cusp rumah yang tampak meyakinkan, padahal meleset sekitar satu zodiak untuk setiap dua jam selisih.

Karena itu, sebagai ganti time Anda bisa mengirim 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}'

Yang dikembalikan API dalam mode ini:

Field	Nilai
planets	dihitung untuk tengah hari lokal
aspects	dihitung, tetapi aspek dengan Bulan tidak dapat diandalkan (lihat di bawah)
houses	null
houseAspects	null
chartSect	null
siderealTime	null
timeUnknown	blok berisi penjelasan: apa saja yang dilewati dan di mana Bulan mungkin berada

Blok timeUnknown.moon berisi longitude Bulan di awal dan akhir hari, busur yang ditempuh dalam sehari (11.8-15.4°), daftar zodiak yang dilaluinya, dan flag changesSign. Dalam sehari Bulan bisa berpindah zodiak, jadi rentang ini sebaiknya ditampilkan kepada pengguna, bukan disembunyikan di balik satu angka.

Flag ini diterima oleh /v1/chart dan /v1/synastry (dalam sinastri, flag bisa diset untuk masing-masing pasangan secara terpisah). Endpoint lain bergantung pada rumah atau sudut dan menjawab 400 TIME_UNKNOWN_UNSUPPORTED: error yang eksplisit lebih baik daripada flag yang diabaikan diam-diam dan ascendant karangan dalam respons.

Versioning API

Versi major ada di URL (/v1/). Perubahan breaking hanya datang bersama /v2/, tidak di tempat. Detailnya di Versioning.

GET /v1/version mengembalikan deploy saat ini:

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 bisa memanggil ini saat startup untuk men-debug “kenapa tiba-tiba perilakunya berbeda”: field build_commit mengidentifikasi deploy secara tepat.

Panggilan keliru yang paling sering kami lihat

Dari analisis log produksi selama 90 hari, 5 kesalahan integrator yang umum:

1. /api/<endpoint> alih-alih /v1/<endpoint>: kebiasaan dari wp-json WordPress. Sekarang kami mengembalikan JSON 404 dengan petunjuk.
2. /v1/v1/<endpoint>: SDK dikonfigurasi dengan baseUrl = .../v1 lalu menambahkan /v1/X di atasnya. Sekarang redirect 308.
3. /swagger.json alih-alih /v1/openapi.json: auto-probe Postman/Insomnia. Sekarang redirect 301.
4. /v1/me, /v1/auth/keys/me tanpa Authorization: Bearer <jwt> → 401. Periksa apakah token dikirim di header.
5. /v1/embed/natal dengan API key alih-alih embed token → 401. Endpoint embed menerima embed token publik dari dashboard, bukan API key.

Terkait

• Mulai cepat: permintaan pertama dalam 5 menit
• Autentikasi: JWT, API key, embed token
• Biaya endpoint: tabel kredit yang lengkap
• Error: daftar kode error
• OpenAPI 3.1: spesifikasi lengkap