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-провайдерів за двома причинами:

Не actionable для інтегратора. Ви викликаєте /v1/interpret/natal або /v1/horoscope/daily - наш сервер сам обирає LLM з ротованої fallback-чейни (Gemini → Groq → Cerebras → SambaNova → Mistral → …). Зміна провайдера не міняє shape відповіді, тільки latency та occasional rewording.
Операційна свобода. Чейн змінюється без попередження (виключення 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	Кредитів	Приклади
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": "Зростаюча опукла", "moonSign": "Козеріг", "sunSign": "Лев" }
}

Порівнюйте англійські значення, показуйте localized. Ці назви беруться з явної таблиці термінів у коді, а не з машинного перекладу: термінологію не можна перекладати послівно, інакше фаза Місяця перетворюється на фінансове слово.

У Human Design центри в localized.centers мають ключами ті самі ідентифікатори, що й centers[].name, тому зіставлення йде за ключем, а не за перекладеним рядком. У Таро те саме робить localized.cards, ключ - slug карти.

Поля з відкритих множин поки що англійські й документовані як такі: themes[] у планети дня, ключові слова та значення карт Таро, назви каналів і воріт Human Design. Назви Молодших Арканів збираються із заморожених форм рангу й масті, тож локалізована вся колода з 78 карт і nameLocalized для неї true; поле лишається false лише там, де таблиця не може дати назву. Відкриті множини перекладайте на своєму боці або чекайте на окремі словники.

Невідомий час народження

Значна частина кінцевих користувачів не знає точного часу народження. Якщо підставити умовний полудень і порахувати карту як звичайну, у відповіді з’явиться асцендент і куспіди домів, які виглядають достовірно, але помиляються приблизно на знак за кожні дві години похибки.

Тому замість 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-ключ.

Пов’язане

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

도움이 되었나요?

Запропонувати правку

마지막 업데이트: 2026. 8. 24.