Skip to content

API Versioning Policy

Our commitment to stability and backward compatibility for partner integrations.

Versioning Strategy

The Contio Partner API uses URL-based versioning with semantic version principles:

  • Current Version: v1
  • Base URL: https://api.contio.ai/v1/partner/

Stability Guarantees

What We Won't Break

Within a major version (e.g., v1), we guarantee:

  • ✅ Existing endpoints remain available
  • ✅ Required parameters stay required
  • ✅ Response field types don't change
  • ✅ Error codes remain consistent
  • ✅ Authentication methods continue working

What May Change

We may make additive, backward-compatible changes:

  • ➕ New optional request parameters
  • ➕ New response fields
  • ➕ New endpoints
  • ➕ New event types
  • ➕ New scopes (optional to use)

Deprecation Policy

When deprecating features:

  1. 6-month notice via email and documentation
  2. Migration guide provided
  3. Sunset date clearly communicated
  4. Support available during transition

SDK Versioning

The Partner SDK follows semantic versioning:

Version Change Meaning
1.0.0 → 1.0.1 Bug fixes only
1.0.0 → 1.1.0 New features, backward compatible
1.0.0 → 2.0.0 Breaking changes

Lock to minor version in your dependencies:

{
  "dependencies": {
    "@contio/partner-sdk": "^1.0.0"
  }
}

API Version Headers

All Partner API responses include a version header:

X-API-Version: 1.7

Use this header to:

  • Verify compatibility - Ensure your integration matches the expected API version
  • Debug issues - Include the version when reporting problems to support
  • Detect upgrades - Monitor for API version changes in production

The version follows major.minor format (e.g., 1.1). Patch-level changes don't increment the API version since they're backward compatible.

Release Notes

For the complete release history including new features, bug fixes, and migration guides, see the Release Notes.

Support

Questions about versioning or migration?