Part 10 of 12 – Conversation Intelligence Platform series Back to Part 1
“We’re retiring this endpoint” is a statement that has earned its bad reputation. In practice it usually means: we decided internally to stop supporting something, gave you as little notice as legally necessary, and your integration broke on a date you may or may not have noticed in an email you may or may not have rea
We’ve been on the receiving end of that. It’s rubbish. So when it came to migrating 200 endpoints out of a monolithic API into independent services, we had to decide what “done well” actually looks like – and then commit to it publicly, which is what this post is.
The policy is straightforward. When a v3 capability is re-expressed as an independent service, the corresponding v3 endpoints are deprecated. From the day the successor service is published, there is a minimum 12-month window before those v3 endpoints are retired. During that window, every response from a deprecated endpoint carries two headers:
Sunset: 2027-06-04
Deprecation: true
Link: <https://api.simwood.com/voice/v1>; rel="successor-version"The Sunset header gives the exact date the endpoint stops working. Deprecation: true makes it machine-detectable – your monitoring can alert on it if you want. The Link header points directly to the successor. Your HTTP client library probably already supports parsing these; many logging and observability tools do too.
The 12-month window is a minimum, not a target. If migration turns out to be complex for a significant portion of customers, we extend it. The point is not to get to the end of the window as fast as possible; it’s to give customers enough runway to migrate without it becoming a crisis.
The v3 decomposition covers twelve target services. In priority order: Conversational AI, WhatsApp, and Messaging first (already thin proxies in front of independent backends, so re-fronting them is lowest risk). Voice, Numbers, and Billing next (higher-change, higher-visibility, larger contracts). Then Porting, Lookup, Account, and the Platform Connect carrier services – BYOC, Operator Connect – as capacity allows.
Conversation Intelligence (/intelligence/v1) is already live as the reference implementation – the first service that went through this whole process, which is why it’s the right model for everything that follows.
I want to say something about the principle here, not just the mechanics.
To be straight about the context: the API deprecation framework described here is relevant to the industry with APIs. Much of the telco industry doesn’t have APIs at all – some carriers we deal with have barely moved beyond fax. We’re not talking about them. We’re talking about what good looks like when you’ve committed to building something developers can rely on, and deprecation policy is one of the clearest tests of that commitment.
The way we think about deprecation is that it’s a statement of care, not abandonment. “We’ve built something better and we’re telling you about it with enough lead time to move” is a fundamentally different message from “we’ve decided to stop doing this, good luck.” The 12-month window, the machine-readable headers, the direct link to the successor – these are details that add up to a developer experience that treats customers as if their time matters.
Practically: the API documentation shows the current status of every service and endpoint. Deprecated endpoints show the Sunset date and the successor link. New integrations should use the independent service APIs rather than v3 for anything where a service equivalent exists.
If you’re currently using v3 endpoints that are in the deprecation queue, you’ll hear from us directly well ahead of the Sunset date. We’re monitoring gateway logs for usage of deprecated endpoints and will reach out proactively to any customer who hasn’t migrated as the window approaches.
The goal is that nobody’s integration breaks unexpectedly. That is a solvable problem if you take it seriously enough to commit to the process. We’re committing.
Previous: Part 9 – Authentication done right
