API Versioning

Versioning Strategy

VideoConduit uses URL path versioning. All endpoints are prefixed with a version identifier: /api/v1/download, /api/v1/info, etc.

When we introduce breaking changes, we'll release a new version (e.g. /api/v2/) alongside the existing one. Both versions run simultaneously during a migration window.

Current Version

The current and only version is v1 (1.0.0). All endpoints are served under /api/v1/.

Every API response includes an X-API-Version header with the current version number:

X-API-Version: 1.0.0

Version Discovery

Use the /api/version endpoint (no auth required) to programmatically discover available versions and their status:

curl https://videoconduit.com/api/version

{
  "current_version": "1.0.0",
  "versions": {
    "v1": {
      "status": "active",
      "deprecated": false,
      "sunset": null,
      "released": "2025-01-01"
    }
  },
  "docs_url": "https://videoconduit.com/docs/api-versioning/"
}

The /api/changelog endpoint (also no auth) returns a structured list of changes per version.

Deprecation Process

When a new API version launches, the previous version enters a deprecation period. We guarantee a minimum of 12 months between deprecation announcement and sunset (removal).

During deprecation, the old version continues to work normally but responses will include additional headers:

Detecting Deprecation Programmatically

Check the Deprecation header on any API response. If present, log a warning and begin planning your migration:

import requests

response = requests.post(
    "https://videoconduit.com/api/v1/download",
    headers={"Authorization": "Bearer vc_your_api_key"},
    json={"url": "https://example.com/video"},
)

if response.headers.get("Deprecation") == "true":
    sunset = response.headers.get("Sunset", "unknown")
    successor = response.headers.get("Link", "")
    print(f"WARNING: API v1 is deprecated. Sunset date: {sunset}")
    print(f"Migrate to: {successor}")

Breaking vs Non-Breaking Changes

Breaking Changes (require a new version)

• Removing an endpoint
• Removing or renaming a response field
• Changing the type of a response field
• Making a previously optional request field required
• Changing error codes or response status codes
• Changing authentication mechanisms

Non-Breaking Changes (happen within a version)

• Adding new endpoints
• Adding optional request fields
• Adding new response fields
• Adding new error codes (without removing existing ones)
• Bug fixes and performance improvements
• Adding new webhook event types

Migration Timeline

When a new version launches, the typical timeline is:

1. Day 0: New version launches. Old version continues to work without deprecation headers.
2. Day 30: Old version is marked deprecated. Deprecation and Sunset headers appear on responses.
3. Months 1–12: Both versions run side by side. Old version continues to work normally. Migration guides available.
4. Month 12+: Old version reaches sunset date and may be removed. Requests return 410 Gone.

Backwards Compatibility Promise

We will never break an active API version without providing a successor version first. If you stay on a supported version, your integration will continue to work. We communicate all changes through:

• HTTP response headers (Deprecation, Sunset, Link)
• The /api/version endpoint
• The /api/changelog endpoint
• Email notifications to account owners
• This documentation page