ecenticecentic
How it worksResourcesPricingBlog
Install now
ASCII-art illustration of a calendar

URL-path versioning · 180 days notice · Deprecation and Sunset headers

ecentic API versioning.

The version is in the path. An integration that pins a version keeps the contract it was written against, and never loses it without warning.

Back to the docs
01

How versions work

One number, in the path, changed only for a break.

GET https://ecentic.ai/api/v1/discovery
API-Version: 1

The current version is v1, served at `/api/v1`. Every response also echoes the version in an `API-Version` header, so a client that follows a redirect or a link can confirm what it is actually talking to.

Additive changes ship inside a version: new endpoints, new optional request fields, new fields on an existing response. Treat unknown response fields as forward compatibility, not as an error.

A change that removes a field, renames one, narrows a type, or changes the meaning of an existing value is a breaking change and ships as a new version path beside the old one — never in place.

02

Deprecation and sunset

Two standard headers, and a window long enough to act on them.

When a version is deprecated, every response from it carries a `Deprecation` header (RFC 9745). When a removal date is fixed, responses also carry a `Sunset` header (RFC 8594) naming the date the version stops answering, and a `Link` with `rel="successor-version"` pointing at the replacement.

The minimum notice between the deprecation announcement and the sunset date is 180 days. No version is removed without both headers having been served for that full window.

minimum notice: 180 days
Deprecation: @1780272000
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: <https://ecentic.ai/api/v2>; rel="successor-version"
03

What is not versioned

Discovery documents track their own protocol's version instead.

The `.well-known` discovery documents are versioned by the protocol they implement, not by the ecentic API version — the UCP profile carries a UCP version, the MCP server card carries a protocol version, and so on. Reading the version from inside the document is always correct; inferring it from the ecentic API version is not.

DocsErrors
Get picked by AI

Ready to be the product agents recommend?

Install free on Shopify or WooCommerce and see your AI score in minutes.

Install on ShopifyInstall on WooCommerce
ecentic

Win every AI shopping agent's cart.

Built for the agent economy
Product
  • Features
  • How it works
  • Pricing
  • Product Listings
Platforms
  • Shopify
  • WooCommerce
  • Enterprise
Resources
  • Developer docs
  • API reference
  • Resources
  • Blog
  • Compare
  • UCP Validator
  • UCP Playground
  • Book a demo
Company
  • Support
  • Privacy policy
  • Terms of service

© 2026 ecentic. All rights reserved.

Made for merchants who refuse to be invisible to AI.