API versioning

The inbound sync API is versioned by URL prefix — /api/v1/*. The registry in config/api.php declares each version's lifecycle and the api.version middleware (alias for App\Http\Middleware\EnforceApiVersion) enforces it on the route group.

Lifecycle states

A version also auto-retires once its sunset_at date passes — no flag flip needed.

Adding a version

1. Create the controllers under App\Http\Controllers\Api\V2.
2. Add a Route::prefix('v2')->middleware(['api.version:v2', ...]) group in routes/api.php.
3. Register 'v2' in config/api.php and flip v1 to deprecated with deprecated_at/sunset_at dates.

Unversioned routes — stable contract

/api/embed/*, /{company}/direct-booking, /{eventType}/event-type-booking and /webhooks/* are not versioned: external sites embed them and cannot migrate on our schedule. Breaking changes there need a parallel route, never an edit.