API deprecation policy

Last updated 2026-11-02

A breaking change goes into a new version, and whatever it replaces keeps working for at least 90 days after we announce it. The rest of this page says what that covers and when it doesn't apply.

The API isn't open to every workspace yet. It's switched on one workspace at a time, and there's no public sign-up. Where it's on, the workspace's owner and admins see Developers under Settings.

What this covers

The REST endpoints under /api/v1, the OAuth endpoints /api/v1/oauth/token and /api/v1/oauth/revoke, and the install webhooks (app.installed, app.authorization_updated, app.uninstalled).

It doesn't cover /api/integrations/v1, the separate API behind Settings → API & webhooks, or the HyperDM app's own screens.

How versions work

The version is in the URL, and every endpoint's response, errors included, names it in the HyperDM-API-Version header (the OpenAPI document and a path that matches no endpoint don't). There is one version today: v1. While the API is switched on, its machine-readable description is at /api/v1/openapi.json.

Changes that aren't breaking

These can land in v1 at any time, and we list them on the changelog:

new endpoints, new permissions and new webhook events;
new optional parameters and new fields in a response;
new error codes for new situations;
fixes that make an endpoint do what its documentation says.

So build your client to ignore fields and events it doesn't recognize, and to fall back on the HTTP status when it meets an error code it doesn't know.

Changes that are breaking

removing or renaming an endpoint, a field or a permission;
changing what a field means, or its type;
adding a required parameter;
requiring a permission an endpoint didn't need before;
lowering the published rate limits.

What we do before a breaking change

We post it on the changelog with the date the old behavior stops, at least 90 days ahead. Until that date it keeps working as documented.

The changelog is the only notice today. We don't send deprecation emails or a Sunset header yet, so check it before you ship against the API.

When you get less notice

We'll give less notice, or none, in these cases, and we'll say why on the changelog as soon as we can:

a security problem;
a legal requirement;
a platform HyperDM depends on, such as Meta or TikTok, changes or removes what the endpoint relies on;
an incident. We can switch the API off for one workspace or for all of them. Requests then answer 403 platform_disabled.

What isn't a deprecation

Access can also end for reasons that have nothing to do with this policy, and each takes effect on the next request:

a key is revoked, rotated or expires, or a workspace uninstalls an app (credential_revoked);
HyperDM suspends an app (app_suspended);
the person who granted access stops being the workspace's owner (grant_inactive);
a refresh token is used twice, which revokes its whole chain.

A start can also be refused because the contact opted out or is outside the messaging window. That's the same check every message goes through, not a change to the API.