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>, ми повертаємо 404 з полем error.code = "WRONG_PREFIX" і підказкою - ваш SDK може це обробити та підказати правильний шлях.

Це не LLM-проксі

AstroWay - це API астрологічних обчислень, не proxy для LLM. Якщо ви приходите з muscle memory 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-провайдерів за двома причинами:

Не actionable для інтегратора. Ви викликаєте /v1/interpret/natal або /v1/horoscope/daily - наш сервер сам обирає LLM з кількох провайдерів із автоматичним fallback. Зміна провайдера не міняє shape відповіді, тільки latency та occasional rewording.
Операційна свобода. Чейн змінюється без попередження (виключення HuggingFace 2026-05-18, додавання NIM/ZAI). Якби ми оголошували конкретний models[] - це ставало б де-факто контрактом.

AI присутній лише як implementation detail в /v1/interpret/* (натальна, синастрія, транзити), /v1/horoscope/* (щоденний/тижневий гороскоп), /v1/dev-assistant (помічник по документації) та /v1/reports/* (PDF-наративи). Решта 750+ ендпоінтів - детермінований Swiss Ephemeris без AI.

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`	Per-DB reachability check (для 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-словники - для віджетів

Безкоштовні 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/*) - 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`

Агент платить за кожен токен, який читає. POST /v1/chart віддає близько 32 КБ, а моделі зазвичай потрібні дві колонки з них, і кожна довгота приходить із чотирнадцятьма знаками після коми там, де ніхто не будує точніше за кутову мінуту.

Два параметри запиту вирішують це на останньому кроці, тому працюють на всіх ендпоінтах:

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 байтів замість 32 410, тобто відповідь менша у шістдесят разів.

Шлях, який нічого не знайшов, не зникає мовчки. Він приходить у полі _fields_unmatched поруч із відповіддю: частина полів справді необов’язкова й відсутня в конкретній відповіді, тому це не помилка. А от список, де не збіглося жодного шляху, це друкарська помилка, і він повертає 400 FIELDS_UNKNOWN з переліком. Порожній об’єкт замість карти був би впевненою неправильною відповіддю.

Обидва параметри йдуть у query, а не в заголовку, і це навмисно: кеш відповідей ключується за методом, шляхом, тілом, відсортованим query і планом. Режим у заголовку повторив би інцидент 2026-08-22, коли Accept-Language не входив у ключ і німецьку відповідь віддали наступному як українську.

Шейпінг стосується тільки data. Конверт, _footer і _warning лишаються цілими.

Те саме працює через MCP. Кожен інструмент на mcp.astroway.info приймає fields і precision поруч зі своїми параметрами й віддає їх API тим самим query. Натальна карта через 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 типових інтегратор-помилок:

/api/<endpoint> замість /v1/<endpoint>: звичка з WordPress wp-json. Тепер повертаємо JSON 404 з hint.
/v1/v1/<endpoint>: SDK сконфігурований з baseUrl = .../v1 і додає /v1/X зверху. Тепер 308 redirect.
/swagger.json замість /v1/openapi.json: Postman/Insomnia auto-probe. Тепер 301 redirect.
/v1/me, /v1/auth/keys/me без Authorization: Bearer <jwt> → 401. Перевірте чи токен передається в заголовку.
/v1/embed/natal з API-ключем замість embed-токена → 401. Embed-ендпоінти приймають публічний embed-token з dashboard, не API-ключ.