# Versioning

AstroWay API uses **URL versioning**: the version is in the request path. Simpler than header-based and caches well through proxies.

```
https://api.astroway.info/v1/chart
```

## SemVer for API

We follow [semver.org](https://semver.org/):

- **MAJOR** (`v1` → `v2`) — breaking changes. Old version keeps working for at least 12 months after the new one launches.
- **MINOR** — new endpoints, new optional fields. Always backwards-compatible.
- **PATCH** — bug fixes, precision refinements. Visible via `X-Api-Version: 1.12.3` response header.

## What is **not** a breaking change

- Adding a new endpoint
- Adding a new optional field to request body
- Adding a new field in the response
- Refining error message text (error `code` values stay stable)
- Precision refinements within declared ±1" (planets) / ±1' (houses)
- Increasing rate limit or credit budget on your plan

This means your code **must not** break when a new field appears in the response. Parse only what you need, ignore the rest.

## What **is** a breaking change (major release only)

- Removing or renaming an endpoint
- Removing or renaming a response field
- Changing a field's type (e.g. `number` → `string`)
- Changing field semantics (what the same name means)
- Changing `code` in error responses
- Tightening validation that could break previously valid requests

## Changelog

All changes — in [Changelog](/en/changelog/). Minor releases every 2–4 weeks, patches as ready.

Subscribe to updates:
- RSS: `https://api.astroway.info/changelog/rss.xml`
- Email: `Settings → Notifications → Product updates` in [dashboard](https://api.astroway.info/dashboard/settings)

## Deprecation policy

When a field or endpoint is deprecated:
1. Announced in changelog + email notice
2. Response includes `Deprecation: Sun, 01 Nov 2026 00:00:00 GMT` header ([RFC 8594](https://datatracker.ietf.org/doc/html/rfc8594))
3. Deprecated API keeps working for **at least 12 months**
4. Removal only in the next major release