# Versioning > How the API is versioned, what counts as a breaking change, and the changelog. The API is in **beta**. The shapes are stable and we will not break them without bumping the version and saying so in the changelog — but we are still adding to them, and we would like to hear what is missing. ## The version is in the path While the API is in beta, everything stays under `/api/v1`. A breaking change bumps the version date below and is marked **Breaking** in the changelog; once the API leaves beta, breaking changes will get a new path instead. Inside v1, `info.version` in the OpenAPI document (currently `2026-09-09`) is the date of the current resource shapes. It is the same string that rides along in every webhook envelope as `api_version`, so a receiver can tell which shapes a payload follows. ## The OpenAPI document ```text GET https://your-site.awrora.app/api/v1/openapi.json ``` No authentication is needed. It is generated from the same schemas the API validates against, so it is never out of date with the implementation — where a guide and the OpenAPI document disagree, the OpenAPI document is right. The [API reference](/api-reference) is generated from it. ## Additions are not breaking Your client must tolerate: * new fields on a resource, * new values in an enum, * new event types. Ignore what you do not recognise. Additive changes do not change the version and are listed in the changelog below. ## Deprecation policy This is what we commit to when something in the API has to change in a way your integration would notice. ### What counts as breaking A change is **breaking** if a client that follows these guides could stop working because of it: * removing an endpoint, a field, an enum value, a query parameter or an event type, * renaming any of them, or changing a field's type or format, * making an optional request field required, or rejecting input that used to be accepted, * changing the meaning of a field, a status or an error `code`, * requiring a scope that a key did not need before, * changing webhook headers, the envelope or the signature scheme. Not breaking — and shipped without notice beyond the changelog: * the additions listed under [Additions are not breaking](#additions-are-not-breaking), * new endpoints, new optional request fields and new error codes on paths that could already fail, * changes to the human-readable `error` messages (branch on `code` — see [Errors](/developers/errors)), * the order of fields in a response, and the length or format of opaque ids and cursors. ### How a deprecation is announced When we decide to remove or change something, we will: 1. mark it **Deprecated** in the changelog below and in the [news](/changelog), with the date it stops working and what to use instead, 2. mark it as deprecated in the OpenAPI document and the [API reference](/api-reference), 3. email the owner of every organisation that has an active API key or webhook endpoint. Today the changelog is the only one of these that happens on its own: there is no automatic email to key owners yet, and responses do not carry `Deprecation` or `Sunset` headers. Watch the changelog until that changes. ### Notice periods | While the API is | Minimum notice for a breaking change | | ---------------- | ------------------------------------------------------------------------------------------------------------------- | | In beta (now) | **30 days** — and we will keep the old behaviour alongside the new one for that period wherever we can | | Stable | **6 months** before the old path version stops working, and the old version keeps working unchanged in the meantime | During beta, breaking changes bump the version date and are marked **Breaking** in the changelog. A security fix may need to ship faster than the notice period; if it does, we will say so in the changelog the same day. ### Webhook events and fields * **Event types** are deprecated with the same notice as endpoints. Until the date in the changelog we keep delivering them to every endpoint subscribed to them; after it, they disappear from the list of types you can pick, and we stop sending them. * **Fields in a payload** follow the resource they belong to — a webhook carries the same object as the API, so a field deprecated on the booking is deprecated in `booking.*` events too. * Every envelope carries `api_version`. When a breaking change bumps it, the value changes on the same day, so a receiver can tell which shapes a payload follows without guessing. ### After the sunset date The endpoint, field or event type is removed. A removed endpoint answers `404`; a removed field is simply absent from responses and payloads; a removed request field is ignored, like any field the API does not know. Nothing is redirected to the replacement — move before the date. ## Changelog | Date | Version | Change | | ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 2026-09-01 | `2026-09-01` | Initial release — **beta**. Experiences, availability, bookings (read, create, cancel), customers, gift cards, events, webhooks, OpenAPI. | | 2026-09-09 | `2026-09-09` | **Breaking:** the webhook headers were renamed from `Aurora-*` to `Awrora-*` (`Awrora-Signature`, `Awrora-Event-Id`, `Awrora-Event-Type`, `Awrora-Delivery-Id`) and the user agent to `Awrora-Webhooks/1.0`. Receivers must read the new header names. | | 2026-09-15 | `2026-09-09` | Additive: `payment.source` on the booking object (`stripe` \| `on_site` \| `external`). Cancelling a booking never attempts a refund unless `payment.source` is `stripe`. | ## Known gaps Things we already intend to add: * `experience.published` and `booking.refunded` events * `POST /v1/bookings/{id}/reschedule` * `updated_since` on customers * a distinct status for cancelled departures in availability Something missing, wrong or surprising? Reach us through your usual Awrora support channel.