# Versioning and changelog

> How the API changes, what counts as breaking, and the list of changes.

Source: https://www.ordstage.com/docs/versioning/

The version is in the path: `https://api.ordstage.com/v1`. Within `v1`, Ordstage only makes **additive** changes:

- new endpoints, new optional parameters and new optional request fields;
- new fields in answers and webhook payloads;
- new error codes, new webhook event types and new values in fields documented as open lists (such as a
  booking's `source`).

Build your integration to tolerate these: ignore fields you don't know, handle unknown error codes by `type`,
and ignore webhook events you didn't subscribe to.

Anything that would break a working integration (removing or renaming a field, changing a type, making an
optional parameter required, changing the meaning of a value) ships as a new version, `/v2`, with `v1` kept
running alongside it and a migration guide. Deprecations are announced in this changelog first.

The machine-readable description of the API is always at
[`https://api.ordstage.com/v1/openapi.json`](https://api.ordstage.com/v1/openapi.json) (OpenAPI 3.1).

## Changelog

### 2026-10-30

- **New resources:** the business profile, members and invitations, webhooks and API keys (read only),
  assistants, conversations, contacts and leads, each with its scope. See the Resources guides.
- **New webhook events** for each of them (`contact.created`, `lead.status_changed`, `conversation.handed_over`,
  `assistant.published`, `member.removed` and more). A webhook with no events chosen gets them too.

### 2026-10-29

- **Public API foundation.** Keys v2 (`ord_live_` and `ord_test_`) with expiry, IP allowlists, rotation with
  overlap and per-key activity; one error envelope with `Request-Id`; per-key rate limits with `X-RateLimit-*`
  headers; `Idempotency-Key` support; cursor pagination; keys in URLs are refused and revoked.
- **Bookings** endpoints moved to these conventions. Their success answers are unchanged, and their errors keep
  the old `detail` field next to the new `error` envelope.
- These docs and the interactive API reference.