URL kuralları ve ücretsiz endpoint'ler

Tipik bir istekte 404 görüyorsanız, büyük olasılıkla önek yanlıştır ya da Swagger UI’ı standart dışı bir yolda arıyorsunuzdur. Bu sayfa tüm kanonik URL’leri ve takma adları sabitler.

Yol öneki

Tüm endpoint’ler /v1/ altında bulunur. Başka önek yoktur.

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

Yanlışlıkla /api/<endpoint> kullandıysanız, error.code = "WRONG_PREFIX" alanı ve bir ipucuyla birlikte 404 döndürürüz: SDK’nız bunu işleyip doğru yolu önerebilir.

Bu bir LLM proxy’si değildir

AstroWay bir astrolojik hesaplama API’sidir, LLM için bir proxy değildir. OpenAI SDK alışkanlığıyla gelip yalnızca base_url’i bizimkiyle değiştirmeyi denerseniz, bu çalışmaz:

❌ 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 sağlayıcılarının listesini iki nedenle yayınlamıyoruz:

Entegratör için eyleme dönüştürülebilir değildir. Siz /v1/interpret/natal veya /v1/horoscope/daily çağırırsınız, sunucumuz otomatik fallback ile birkaç sağlayıcı arasından LLM’i kendisi seçer. Sağlayıcı değişikliği yanıtın yapısını değiştirmez, yalnızca gecikmeyi ve ara sıra ifade farklılıklarını etkiler.
Operasyonel özgürlük. Zincir önceden haber verilmeden değişir (2026-05-18’de HuggingFace’in çıkarılması, NIM/ZAI’nin eklenmesi). Belirli bir models[] ilan etseydik, bu fiilen bir sözleşmeye dönüşürdü.

AI yalnızca bir uygulama ayrıntısı olarak /v1/interpret/* (doğum haritası, sinastri, transitler), /v1/horoscope/* (günlük/haftalık burç yorumu), /v1/dev-assistant (dokümantasyon asistanı) ve /v1/reports/* (PDF anlatıları) içinde bulunur. Geriye kalan 750+ endpoint, AI içermeyen deterministik Swiss Ephemeris’tir.

OpenAPI 3.1 spesifikasyonu

Kanonik adres /v1/openapi.json’dur. Entegrasyon kolaylığı için takma adlar eklenmiştir:

Takma ad	Nereye	Neden var
`/v1/swagger.json`	301 → `/v1/openapi.json`	Swagger 2.0 / openapi-generator kuralı
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	springdoc varsayılanı
`/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 sunucusu

Etkileşimli Swagger UI /v1/docs adresinde bulunur (ayrıca /docs/api/ adresindeki tarayıcı dokümantasyonuna da yansıtılmıştır).

Ücretsiz sistem endpoint’leri

Bu yollar API anahtarı gerektirmez ve kredi düşmez: herhangi bir frontend’den, izleme aracından veya health-check’ten çağrılabilirler.

Yol	Ne döndürür
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}`: hızlı liveness probe
`GET /v1/health/deep`	Veritabanı başına erişilebilirlik kontrolü (UptimeRobot / Pingdom için), en az bir veritabanı erişilemezse 503
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}`: SDK için ayrıntılı öz denetim
`GET /v1/openapi.json`	Örnekler + `x-codeSamples` içeren tam OpenAPI 3.1 spesifikasyonu
`GET /v1/docs`	Etkileşimli Swagger UI
`GET /v1/reference/*`	Kanonik başvuru tabloları (burçlar, gezegenler, evler, açılar): IP bazlı rate limit, anahtarsız
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Dil listesi ve UI sözlükleri: widget’lar için

Kayıt gerektiren ücretsiz endpoint’ler

Hesap endpoint’lerine yalnızca JWT token ile (girişte verilir) erişilebilir, ancak plan bakiyesinden kredi düşmezler.

Önek	Nedir
`/v1/auth/*`	Kayıt, giriş, refresh, parola sıfırlama
`/v1/me`, `/v1/me/*`	Profil, istatistikler, son çağrılar
`/v1/keys`, `/v1/keys/*`	API anahtarı yönetimi
`/v1/admin/*`	Yönetim paneli (`api_role = admin` gerektirir)
`/v1/messages`	Widget’tan geri bildirim (anonim, rate limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	Dokümantasyon için AI asistanı (anonim, ayrı limit)
`/v1/widget-config`	Widget için çalışma zamanı özellik bayrakları
`/v1/embed/*`	Gömülebilir iframe widget’ları (IP bazlı rate limit)
`/v1/oauth/*`	Google / GitHub ile giriş
`/v1/books/*`	Birth Book: ayrı bir scope JWT’si (WordPress mu-plugin tarafından verilir)

Ücretli hesaplama endpoint’leri

Tüm astrolojik hesaplamalar plan kredilerinizden düşer. Her birinin tam maliyeti Endpoint maliyetleri sayfasındadır. Kısaca:

Tier	Kredi	Örnekler
0	0	`/v1/reference/*`: herkese açık başvuru tabloları, anahtarsız
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog`: statik tablolar
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 anlatıları `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	PDF raporları: `/v1/reports/natal`, `/v1/reports/synastry`

Önbellek indirimleri: X-Cache: HIT (5 dakikalık idempotency önbelleği): 0 kredi. AI endpoint’leri (/interpret/*): cache hit durumunda %50 indirim.

Yanıt başlıkları X-Credits-Used, X-Credits-Remaining, X-Credits-Limit içerir: SDK’lar bakiyeyi otomatik olarak takip edebilir.

Yanıtlarda dil

Dil ?lang= veya Accept-Language başlığı ile belirlenir. 21 dil desteklenir.

Kapalı kümelerden gelen alanlar (burçlar, gezegenler, haftanın günleri, Ay evreleri, Human Design sözlüğü, Tarot’un Büyük Arkana adları) iki kez döndürülür: İngilizce tanımlayıcı kararlı bir sözleşme olarak yerinde kalır, yanına ise çeviriyi içeren bir localized nesnesi gelir:

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

İngilizce değerleri karşılaştırın, localized’ı gösterin. Bu adlar makine çevirisinden değil, koddaki açık bir terim tablosundan alınır: terminoloji kelimesi kelimesine çevrilemez, aksi hâlde bir Ay evresi finansal bir kelimeye dönüşür.

Human Design’da localized.centers içindeki merkezlerin anahtarları centers[].name ile aynı tanımlayıcılardır, bu yüzden eşleştirme çevrilmiş dizeye göre değil, anahtara göre yapılır. Tarot’ta aynı işi localized.cards yapar, anahtar kartın slug’ıdır.

Açık kümelerden gelen alanlar şimdilik İngilizcedir ve bu şekilde belgelenmiştir: günün gezegenindeki themes[], Tarot kartlarının anahtar kelimeleri ve anlamları, Human Design kanal ve kapı adları. Küçük Arkana adları rütbe ve takımın dondurulmuş biçimlerinden oluşturulur, bu yüzden 78 kartlık destenin tamamı yerelleştirilmiştir ve onun için nameLocalized true’dur; alan yalnızca tablonun bir ad veremediği yerlerde false kalır. Açık kümeleri kendi tarafınızda çevirin ya da ayrı sözlükleri bekleyin.

Kompakt yanıt: `fields` ve `precision`

Bir ajan okuduğu her token için ödeme yapar. POST /v1/chart yaklaşık 32 KB döndürür, oysa modelin genellikle bunlardan iki sütuna ihtiyacı vardır ve her boylam, kimsenin bir yay dakikasından daha hassas çizim yapmadığı bir yerde virgülden sonra on dört basamakla gelir.

İki sorgu parametresi bunu son adımda çözer, bu yüzden tüm endpoint’lerde çalışırlar:

fields: data’ya göre, virgülle ayrılmış yol listesi. Bir yol dizinin her öğesine uygulanır, yani planets.name dizinin bir anahtarı değil, her gezegenin adı anlamına gelir.
precision: 0 ile 15 arasında bir tam sayı, yanıttaki tüm tam sayı olmayan sayıları yuvarlar. Tam sayılara dokunmaz: bir tanımlayıcı bir ölçüm değildir.

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

Doğum haritasında bu parametre çifti 32 410 yerine 511 bayt verir, yani yanıt altmış kat küçülür.

Hiçbir şey bulamayan bir yol sessizce kaybolmaz. Yanıtın yanında _fields_unmatched alanında gelir: alanların bir kısmı gerçekten isteğe bağlıdır ve belirli bir yanıtta bulunmaz, bu yüzden bu bir hata değildir. Ama hiçbir yolun eşleşmediği bir liste bir yazım hatasıdır ve listeyle birlikte 400 FIELDS_UNKNOWN döndürür. Harita yerine boş bir nesne, kendinden emin ama yanlış bir yanıt olurdu.

İki parametre de başlıkta değil, query’de gider ve bu bilinçli bir tercihtir: yanıt önbelleğinin anahtarı metoda, yola, gövdeye, sıralanmış query’ye ve plana göre oluşturulur. Başlıktaki bir mod, Accept-Language’in anahtara dahil olmadığı ve Almanca bir yanıtın bir sonraki kullanıcıya Ukraynaca diye verildiği 2026-08-22 olayını tekrarlardı.

Şekillendirme yalnızca data’yı etkiler. Zarf, _footer ve _warning olduğu gibi kalır.

Aynısı MCP üzerinden de çalışır. mcp.astroway.info üzerindeki her araç, kendi parametrelerinin yanında fields ve precision kabul eder ve bunları aynı query ile API’ye iletir. MCP üzerinden doğum haritası 91 737 bayt tutuyordu, çünkü veriler iki kez geliyordu: girintili bir metin bloğu olarak ve yapılandırılmış bir alan olarak. Aynı üç yol ve precision: 2 ile bu 1 182 bayttır.

Doğum haritası çağrısı	Bayt
MCP, 21.09.2026 öncesindeki gibi	91 737
MCP, metin bloğunda girintisiz	72 484
MCP, `precision: 2`	61 356
MCP, `fields` içinde üç yol artı `precision: 2`	1 182
REST, `fields` içinde üç yol artı `precision=2`	559

Bilinmeyen doğum saati

Son kullanıcıların önemli bir kısmı tam doğum saatini bilmez. Varsayılan bir öğle saati koyup haritayı normal şekilde hesaplarsanız, yanıtta güvenilir görünen ama her iki saatlik hata için yaklaşık bir burç kadar yanılan bir yükselen ve ev başlangıçları ortaya çıkar.

Bu yüzden time yerine timeUnknown: true gönderilebilir:

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 bu modda ne döndürür:

Alan	Değer
`planets`	yerel öğle saatine göre hesaplanır
`aspects`	hesaplanır, ancak Ay ile yapılan açılar güvenilir değildir (aşağıya bakın)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	açıklama bloğu: tam olarak neyin atlandığı ve Ay’ın nerede olabileceği

timeUnknown.moon bloğu, Ay’ın günün başındaki ve sonundaki boylamını, gün boyunca kat ettiği yayı (11.8-15.4°), içinde bulunduğu burçların listesini ve changesSign bayrağını içerir. Ay bir gün içinde burç değiştirebilir, bu yüzden bu aralığı tek bir sayının arkasına saklamak yerine kullanıcıya göstermek gerekir.

Bayrağı /v1/chart ve /v1/synastry kabul eder (sinastride partnerlerin her biri için ayrı ayrı ayarlanabilir). Diğer endpoint’ler evlere veya açısal noktalara bağlıdır ve 400 TIME_UNKNOWN_UNSUPPORTED ile yanıt verir: sessizce yok sayılan bir bayrak ve yanıtta uydurulmuş bir yükselen yerine açık bir hata daha iyidir.

API sürümleme

Major sürüm URL’dedir (/v1/). Breaking change’ler yerinde değil, yalnızca /v2/ ile gelir. Ayrıntılar: Sürümleme.

GET /v1/version mevcut deploy’u döndürür:

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’lar “davranış neden birden farklı” sorusunu ayıklamak için bunu başlangıçta çağırabilir: build_commit alanı deploy’u tam olarak tanımlar.

En sık gördüğümüz hatalı çağrılar

90 günlük üretim loglarının analizinden, 5 tipik entegratör hatası:

/v1/<endpoint> yerine /api/<endpoint>: WordPress wp-json alışkanlığı. Artık ipucuyla birlikte JSON 404 döndürüyoruz.
/v1/v1/<endpoint>: SDK baseUrl = .../v1 ile yapılandırılmış ve üstüne /v1/X ekliyor. Artık 308 redirect.
/v1/openapi.json yerine /swagger.json: Postman/Insomnia otomatik yoklaması. Artık 301 redirect.
Authorization: Bearer <jwt> olmadan /v1/me, /v1/auth/keys/me → 401. Token’ın başlıkta gönderilip gönderilmediğini kontrol edin.
Embed token yerine API anahtarıyla /v1/embed/natal → 401. Embed endpoint’leri API anahtarını değil, panelden alınan herkese açık embed token’ı kabul eder.