Versioning

The Basker Partners API uses date-based path versioning. Every endpoint URL includes the version as a path segment, immediately after /partners/:

https://api.basker.app/partners/{version}/{tenant}/...

For example, 2026-02 is the version segment in:

https://api.basker.app/partners/2026-02/royal-opera-house/events

Why date-based versions

A new version is published roughly every quarter, named after the month it shipped (2025-07, 2025-10, 2026-02). Old versions stay live for at least 12 months after the next version is released, giving integrations a clear window to migrate.

This keeps integrations stable: pinning to a known version means new fields, removed fields, or behavioural changes in newer versions don't silently affect your integration. Upgrade when you're ready.

What changes between versions

Versions are usually small, additive, and well-documented. Common shapes of change:

• New endpoints — pure addition; safe to ignore until you need them.
• New fields on existing responses — additive; existing field consumers keep working.
• Renamed or removed fields — breaking; the changelog flags them.
• Behavioural changes to filtering, pagination, or sorting — flagged in the changelog.

Versions never silently change behaviour. If a version makes a breaking change, the previous version stays available so integrations can migrate at their own pace.

How to pick a version

• New integrations: use the most recent stable version. The default value in the OpenAPI spec is also the most recent.
• Existing integrations: stay on your current version until you have time to test against the new one. Migration is rarely urgent.

Migration workflow

1. Read the changelog for the new version. Focus on breaking changes (renamed fields, removed endpoints, behavioural changes).
2. Spin up a parallel test against the new version with one or two key endpoints.
3. Identify the diff — log shape changes, missing fields, new required parameters.
4. Update your integration to consume the new shape.
5. Switch the path version on production once you've verified the new build.
6. Decommission the old version's path once your traffic has fully migrated.

Engineering can supply migration notes for any specific version on request.

Related

• Authentication — auth headers don't change between versions.
• Multi-tenancy — the tenant slug appears after the version in every path.
• Errors — error envelope is consistent across versions.