Skip to main content
VertaaUXVertaaUX
← Developer Docs

API Versioning & Deprecation Policy

Our commitment to API stability and predictable evolution. This policy outlines how we version the API, communicate breaking changes, and provide migration pathways when deprecating features.

API DocumentationAPI Changelog•Error Codes

Key Principles

Stability First

Once released, API behavior remains consistent. Breaking changes require a new version and extended deprecation period.

12-Month Notice

Breaking changes announced 12 months in advance with migration guides, code examples, and dashboard warnings.

Additive Evolution

New fields, endpoints, and optional parameters added without version bump. Clients ignore unknown fields.

Clear Communication

Deprecations communicated via email, docs, changelog, dashboard banners, and API headers.

API Version Lifecycle

General Availability (GA)

  • Full support for all features
  • SLA applies
  • Bug fixes and security patches
  • Non-breaking enhancements
  • Duration: Until next major version + 6 months

Maintenance Mode

  • Critical bug fixes and security patches only
  • No new features
  • SLA still applies
  • Deprecation warnings in API responses
  • Duration: 6 months minimum

End of Life (EOL)

  • API version removed
  • Returns 410 Gone for all requests
  • No support available
  • Must migrate to current version
  • Notice: Announced 12 months prior

Example Timeline

Jan 2025:v1.0 released (General Availability)
Jul 2025:v2.0 announced, v1.0 enters Maintenance Mode (6-month notice)
Jan 2026:v1.0 EOL announced (12-month notice), v2.0 GA
Jan 2027:v1.0 removed (returns 410 Gone)

Breaking vs. Non-Breaking Changes

❌ Breaking Changes

Require a new major version and 12-month deprecation period:

  • Removing endpoints or fields
  • Changing field types (string → number)
  • Renaming fields or parameters
  • Making optional fields required
  • Changing error codes or status codes
  • Modifying authentication requirements
  • Altering rate limit behavior

✅ Non-Breaking Changes

Can be deployed without version change:

  • Adding new endpoints
  • Adding new optional fields
  • Adding new optional parameters
  • Adding new enum values
  • Adding new error codes (additive)
  • Making required fields optional
  • Bug fixes that restore documented behavior

Client Resilience: Design your API clients to ignore unknown fields and handle new enum values gracefully. This allows us to add features without breaking your integration.

Deprecation Process

When we deprecate a feature, endpoint, or API version, we follow a structured process to minimize disruption:

1

Announcement (T-12 months)

  • Email notification to all affected customers
  • Deprecation notice added to API docs and changelog
  • Dashboard banner for affected API keys
  • Migration guide published with code examples
2

Warning Period (T-6 to T-12 months)

  • Deprecation warning headers added to API responses
  • Weekly reminder emails to accounts still using deprecated feature
  • Dashboard analytics show deprecation usage
  • Support team proactively reaches out to high-usage accounts
3

Final Warning (T-3 months)

  • Daily email notifications to accounts with active usage
  • API responses include Sunset header with exact EOL date
  • Dashboard blocks creation of new API keys for deprecated version
  • Personal outreach from customer success team
4

End of Life (T-0)

  • Deprecated feature/version removed from production
  • API returns 410 Gone status
  • Final migration guide sent to remaining users
  • Extended support available for Enterprise customers (if needed)

Deprecation Headers

When you use a deprecated feature, the API includes special headers in the response:

Deprecation: true

Indicates this endpoint or version is deprecated

Sunset: Sat, 15 Jan 2027 00:00:00 GMT

RFC 8594 compliant date when feature will be removed

Link: <https://vertaaux.ai/developer-docs/migration>; rel="deprecation"

URL to migration guide with detailed instructions

Example Deprecated Response

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Sat, 15 Jan 2027 00:00:00 GMT
Link: <https://vertaaux.ai/developer-docs/migration>; rel="deprecation"
Warning: 299 - "This API version will be removed on 2027-01-15"

{
  "job_id": "clu123...",
  "status": "completed",
  ...
}

Migration Support

We're committed to making migrations as smooth as possible:

Detailed Guides

Step-by-step migration instructions with before/after code examples for every breaking change.

Parallel Running

Test new version alongside old version using different API keys during transition period.

Codemods & Scripts

Automated migration scripts provided for common frameworks and languages when applicable.

Dedicated Support

Pro and Enterprise customers get priority support during migration with engineering office hours.

Current API Versions

API v1 (2025-01-10)

Alpha

Current public version during alpha. SLA and uptime targets apply only via an executed Enterprise agreement; published telemetry will appear on the Status page as monitoring rolls out.

Base URL: VertaaUX API v1 base URL

Check changelog for the latest API updates and status page for operational status.

Questions About Versioning?

If you have questions about our versioning policy or need help with a migration, we're here to help.

Contact SupportView API Docs