URL conventions and free endpoints

If you’re seeing 404s on what should be a routine request — it’s almost always a wrong prefix or you’re looking for Swagger UI at a non-standard path. This page documents every canonical URL and alias.

Path prefix

All endpoints live under /v1/. No other prefix is accepted.

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

If you accidentally hit /api/<endpoint>, we return 404 with error.code = "WRONG_PREFIX" and a hint — your SDK can intercept this and surface the correct path.

Not an LLM proxy

AstroWay is an astrology calculations API, not an LLM proxy. If you arrive with OpenAI SDK muscle memory and try to just swap base_url to ours — it won’t work:

❌ 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

We don’t publish the AI provider list for two reasons:

Not actionable for integrators. You call /v1/interpret/natal or /v1/horoscope/daily — our server picks an LLM from a rotated fallback chain (Gemini → Groq → Cerebras → SambaNova → Mistral → …) on its own. Swapping providers doesn’t change the response shape, only latency and occasional rewording.
Operational freedom. The chain changes without warning (we removed HuggingFace 2026-05-18, added NIM/ZAI). If we declared a fixed models[] it would become a de-facto contract.

AI is present purely as an implementation detail in /v1/interpret/* (natal, synastry, transits), /v1/horoscope/* (daily/weekly forecasts), /v1/dev-assistant (docs helper) and /v1/reports/* (PDF narratives). The remaining 400+ endpoints are deterministic Swiss Ephemeris, no AI involved.

OpenAPI 3.1 spec

The canonical URL is /v1/openapi.json. For integration convenience we accept these aliases:

Alias	Where	Why
`/v1/swagger.json`	301 → `/v1/openapi.json`	Swagger 2.0 / openapi-generator default
`/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 host

Interactive Swagger UI lives at /v1/docs (also mirrored in the browseable docs at /docs/api/).

Free system endpoints

These paths require no API key and don’t burn credits — call them from any frontend, monitor, or health-check.

Path	Returns
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` — fast liveness probe
`GET /v1/health/deep`	Per-DB reachability check (for UptimeRobot / Pingdom), 503 if any DB is down
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` — SDK self-check
`GET /v1/openapi.json`	Full OpenAPI 3.1 spec with examples + `x-codeSamples`
`GET /v1/docs`	Interactive Swagger UI
`GET /v1/reference/*`	Canonical reference data (signs, planets, houses, aspects) — IP-rate-limited, no key
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Language list + UI dictionaries — for widgets

Free endpoints that require an account

Account endpoints accept a JWT (issued at login) but don’t deduct credits from your plan balance.

Prefix	What
`/v1/auth/*`	Register, login, refresh, password reset
`/v1/me`, `/v1/me/*`	Profile, usage stats, recent calls
`/v1/keys`, `/v1/keys/*`	API key management
`/v1/admin/*`	Admin panel (requires `api_role = admin`)
`/v1/messages`	Feedback widget submissions (anonymous, rate-limited)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	AI docs assistant (anonymous, separate quota)
`/v1/widget-config`	Runtime feature-flags for the widget
`/v1/embed/*`	Embeddable iframe widgets (IP-rate-limited)
`/v1/oauth/*`	Google / GitHub login
`/v1/books/*`	Birth Book — separate scoped JWT (issued by WordPress mu-plugin)

Paid calculation endpoints

All astrology calculations deduct credits from your plan. Exact per-endpoint cost is on Per-endpoint Cost. Summary:

Tier	Credits	Examples
½	5	`/v1/reference/*`, static lookups
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 reports (`/v1/reports/*`)

Cache discounts: X-Cache: HIT (5-min idempotency cache) — 0 credits. AI endpoints (/interpret/*) — 50% off on cache hit.

Response headers include X-Credits-Used, X-Credits-Remaining, X-Credits-Limit — your SDK can track balance automatically.

API versioning

Major version in the URL (/v1/). Breaking changes only ship as /v2/, never in-place. Details — Versioning.

GET /v1/version returns the current 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/"
# }

SDKs can call this on boot for debugging “why is the behaviour suddenly different” — the build_commit field uniquely identifies the deploy.

Most-common integrator mistakes

From 90 days of prod logs, the top 5 integration mistakes we see:

/api/<endpoint> instead of /v1/<endpoint> — WordPress wp-json muscle memory. We now return JSON 404 with a hint.
/v1/v1/<endpoint> — SDK configured with baseUrl = .../v1 and the call adds /v1/X on top. Now 308 redirected.
/swagger.json instead of /v1/openapi.json — Postman/Insomnia auto-probe. Now 301 redirected.
/v1/me, /v1/auth/keys/me without Authorization: Bearer <jwt> → 401. Check that the token reaches the header.
/v1/embed/natal with an API key instead of an embed token → 401. Embed endpoints accept the public embed token from the dashboard, not your API key.