Versioning

The Convotic API uses URL-based versioning to provide a stable and predictable integration experience.

Current Version

The current API version is v1. All endpoints are available under:

https://api.convotic.com/v1/

How Versioning Works

The API version is embedded in the URL path. Each major version operates as an independent, self-contained API surface:

Version	Base URL	Status
v1	https://api.convotic.com/v1/	Current

When a new major version is released (e.g., v2), it will be available at a separate path:

https://api.convotic.com/v2/

Your existing integrations using /v1/ will continue to work without modification.

Backward Compatibility Promise

Within a given API version, Convotic guarantees the following:

• Existing fields will not be removed from response objects.
• Existing field types will not change (e.g., a string field will not become a number).
• Existing endpoints will not be removed.
• Required parameters will not be added to existing endpoints.

The following changes are considered backward-compatible and may occur without a version bump:

• Adding new optional query parameters to existing endpoints.
• Adding new fields to response objects.
• Adding new endpoints.
• Adding new values to enumerations (e.g., a new platform value).

Deprecation Policy

When a new API version is released:

1. Announcement. Deprecation of the previous version will be announced at least 6 months in advance via email and the Convotic dashboard.
2. Deprecation period. The deprecated version will remain fully functional for the entire 6-month deprecation period.
3. Sunset. After the deprecation period ends, the deprecated version will return 410 Gone responses. Migrate to the latest version before this date.

Deprecation Headers

When a version is deprecated but still functional, responses will include a deprecation header:

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

Migration Guide

When a new version is released, a migration guide will be published with:

• A summary of all breaking changes.
• Before and after examples for each affected endpoint.
• Recommended migration steps.

Check the API Overview for the latest version information.