Migration & Breaking Changes

This guide documents the AskVerdict API versioning policy, how breaking changes are communicated, and how to upgrade safely between versions. The current stable release is API v1.

Current API Version

All versioned endpoints are prefixed with /v1/. Internal API endpoints (auth, billing, admin) are under /api/ and follow the same version policy.

Versioning Policy

AskVerdict follows semantic versioning for the API:

• Patch releases (v1.x.x): bug fixes, performance improvements, new optional fields — always backward compatible
• Minor releases (v1.x.0): new endpoints, new optional request parameters, new response fields — always backward compatible
• Major releases (v2.0.0): breaking changes — require a migration guide and a transition period

What is a Breaking Change

A breaking change is any modification that could cause an existing integration to fail or produce incorrect results without modification. Examples:

• Removing a field from a response payload
• Changing a field's type (e.g., string → number)
• Renaming an endpoint path
• Making a previously optional parameter required
• Changing the meaning or behavior of an existing parameter
• Removing a supported enum value
• Changing an HTTP status code for an existing scenario

What is Not a Breaking Change

• Adding new optional fields to a response (your parser should ignore unknown fields)
• Adding new optional request parameters
• Adding new endpoints
• Adding new enum values to a field (parse defensively — handle unknown values gracefully)
• Improvements to error messages (the error code remains stable, the message may change)
• Performance improvements that do not change behavior

Deprecation Policy

Before a breaking change reaches a major release, affected fields, parameters, or endpoints go through a deprecation period:

1. Announcement: Deprecation is announced in the Changelog and via email to developers with active API keys
2. Deprecation notice in responses: Deprecated endpoints return a Deprecation HTTP header:

   plaintextCopy

   Deprecation: true
   Sunset: Sat, 01 Jan 2027 00:00:00 GMT
   Link: <https://askverdict.ai/docs/guides/migration>; rel="deprecation"

3. Minimum deprecation window: At least 90 days between announcement and removal for production endpoints; 30 days for beta features
4. Removal: The deprecated behavior is removed in the next major version after the Sunset date

Upgrade Checklist Template

When a new major version is released, use this checklist to audit your integration.

Pre-Upgrade Audit

• Read the full migration guide for the target version
• Identify all endpoints you call — check each against the breaking changes list
• Identify all response fields you read — check for renamed or removed fields
• Identify all enum values you reference — check for removed values
• Check if any previously optional parameters are now required
• Review webhook payload changes if you use webhooks

Code Changes

• Update the base URL if the version prefix changed
• Update SDK to the new major version: npm install @askverdict/sdk@next
• Update CLI to the new major version: npm install -g @askverdict/cli@next
• Apply all required request payload changes
• Update response field references (renamed fields, restructured payloads)
• Add handling for new required error codes
• Test streaming behavior if SSE event types changed

Testing

• Run your full test suite against the v2 staging environment (https://api-staging.askverdict.ai/v2/)
• Test authentication flows end-to-end
• Test streaming debates with each mode (fast, balanced, thorough)
• Test error handling: invalid input, rate limits, provider errors
• Test webhook delivery and signature verification if applicable

Rollout

• Deploy to staging first; run smoke tests
• Update SDK and CLI in lock-step — do not mix versions
• Monitor error rates for 24 hours after cutover
• Remove any v1-specific compatibility shims after verifying stability

SDK Version Compatibility

Each major API version corresponds to a major SDK version:

The SDK major version tracks the API major version. Minor and patch SDK releases are backward compatible within the same major version.

If you are using the SDK, upgrading the SDK package is the primary migration step — the SDK handles the underlying HTTP changes for you.

CLI Version Compatibility

The CLI follows the same version alignment as the SDK:

Run askverdict --version to check your installed version.

Error Code Stability

Error code values in API responses are stable across minor and patch versions. The human-readable message may change to improve clarity.

Current stable error codes:

Future: v2 Breaking Changes (Template)

This section will be populated when v2 is planned. It is included here as a template for the format.

Overview

This section will describe the scope and motivation of v2 changes.

Breaking Changes

[Example] Renamed field: verdict.winningPosition → verdict.dominantPosition

Affected endpoints: POST /v2/verdicts, GET /v2/debates/:id

Before (v1):

{
  "verdict": {
    "winningPosition": "against"
  }
}

After (v2):

{
  "verdict": {
    "dominantPosition": "against"
  }
}

Migration: Update all code that reads verdict.winningPosition to verdict.dominantPosition.

v2 Migration Timeline (Template)

Staying Informed

To be notified of upcoming breaking changes and deprecations:

1. Watch the changelog — /docs/changelog/index is updated with every release
2. Check your API key dashboard — deprecation notices appear in the Developer Portal for keys that call deprecated endpoints
3. Monitor response headers — watch for Deprecation: true in API responses from your integration
4. Subscribe to the developer newsletter — opt in at Settings → Notifications