# 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/](/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) |

## Платні розрахункові ендпоінти

Усі **астрологічні розрахунки** списують кредити з вашого тарифного плану. Точна вартість кожного — на сторінці [Вартість ендпоінтів](/credits/). Стисло:

| 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. Деталі — [Версіонування](/versioning/).

`GET /v1/version` повертає поточний deploy:

```bash
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](https://api.astroway.info/dashboard/embeds), не API-ключ.

## Пов'язане

- [Швидкий старт](/getting-started/) — перший запит за 5 хвилин
- [Автентифікація](/authentication/) — JWT, API-ключі, embed-токени
- [Вартість ендпоінтів](/credits/) — точна таблиця кредитів
- [Помилки](/errors/) — список error codes
- [OpenAPI 3.1](/v1/openapi.json) — повна специфікація