Versioning

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#

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 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,
• 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),
• 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, with the date it stops working and what to use instead,
2. mark it as deprecated in the OpenAPI document and the 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#

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#

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.