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 (без префікса /v1/)
❌ https://api.astroway.info/api/v1/chart     — 404 (наш внутрішній шлях, ззовні недоступний)
❌ https://api.astroway.info/v1/v1/chart      — 308 redirect на /v1/chart (фікс типового SDK-багу)

Якщо ви помилково використали /api/<endpoint>, ми повертаємо 404 з полем error.code = "WRONG_PREFIX" і підказкою — ваш SDK може це обробити та підказати правильний шлях.

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

AstroWay — це API астрологічних обчислень, не proxy для LLM. Якщо ви приходите з muscle memory OpenAI SDK і пробуєте просто змінити base_url на наш — це не спрацює:

❌ POST /v1/chat/completions            — не існує
❌ POST /v1/completions                 — не існує
❌ GET  /v1/models                      — не існує (умисно)
❌ POST /v1/embeddings                  — не існує

Ми не публікуємо список AI-провайдерів за двома причинами:

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

AI присутній лише як implementation detail в /v1/interpret/* (натальна, синастрія, транзити), /v1/horoscope/* (щоденний/тижневий гороскоп), /v1/dev-assistant (помічник по документації) та /v1/reports/* (PDF-наративи). Решта 400+ ендпоінтів — детермінований 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	Кредитів	Приклади
½	5	/v1/reference/*, статичні довідники
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
6	500	/v1/rectification
7	5000	PDF-репорти (/v1/reports/*)

Кеш-знижки: X-Cache: HIT (5-хв idempotency-cache) — 0 кредитів. AI-ендпоінти (/interpret/*) — 50% знижка на cache hit.

Заголовки відповіді містять X-Credits-Used, X-Credits-Remaining, X-Credits-Limit — SDK можуть автоматично трекати баланс.

Версіонування 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 типових інтегратор-помилок:

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

Пов’язане

• Швидкий старт — перший запит за 5 хвилин
• Автентифікація — JWT, API-ключі, embed-токени
• Вартість ендпоінтів — точна таблиця кредитів
• Помилки — список error codes
• OpenAPI 3.1 — повна специфікація