Versioning & Deprecation

API Versioning

The xQR API is versioned via the URL path:

https://xqr.co/api/v1/links
               ^^^^

Current Version

v1 is the current and only stable version. All new features are added in a backwards-compatible manner.

What Counts as a Breaking Change

These changes are breaking and will only happen in a new API version:

• Removing an endpoint
• Removing or renaming a response field
• Changing the type of a response field
• Removing a supported query parameter or request body field
• Changing the authentication mechanism
• Changing the error response structure

What Is NOT a Breaking Change

These changes may happen within v1 without a version bump:

• Adding new endpoints
• Adding new optional request parameters
• Adding new response fields
• Adding new error codes
• Adding new webhook event types
• Adding new scopes
• Changing error messages (the message string, not the code)
• Increasing rate limits

Tip

To be safe, your integration should ignore unknown fields in API responses rather than failing on them. This ensures forward compatibility.

Deprecation Policy

When a feature or endpoint is deprecated:

1. Announcement — We announce the deprecation in the changelog and via email to all workspace owners at least 90 days before removal
2. Deprecation header — Deprecated endpoints return a Sunset header with the removal date:

   Sunset: Sat, 01 Nov 2026 00:00:00 GMT
   Deprecation: true

3. Documentation — Deprecated features are marked with a warning badge in these docs and include a migration guide
4. Removal — After the sunset date, the deprecated endpoint returns 410 Gone

Deprecation Timeline

Phase	Duration	What Happens
Active	—	Feature works normally
Deprecated	90+ days	Works but returns Sunset header; migration guide available
Sunset	—	Returns 410 Gone

Version Lifecycle

Version	Status	Support End
v1	Active	No planned end date

When a v2 is released:

• v1 will be supported for at least 12 months after v2 GA
• All v1 users will be notified via email and dashboard banners
• A detailed migration guide will be published

Stability Guarantee

We commit to:

• No surprise breakage — Breaking changes only in new versions with advance notice
• Long support windows — At least 12 months of overlap between major versions
• Clear communication — Changelogs, email notifications, and in-dashboard alerts
• Migration support — Detailed guides for every breaking change

OpenAPI Specification

A machine-readable API specification is available at:

https://docs.xqr.co/openapi.json

This spec follows the OpenAPI 3.1 format and is updated alongside the API. Use it to:

• Auto-generate client libraries
• Import into Postman, Insomnia, or Hoppscotch
• Validate requests in CI/CD pipelines
• Feed to AI tools for API understanding