API Versioning & Deprecation Policy

Who this is for: developers building against the EmbayLMS REST API who need to know what we may change, what we may not, and how much warning you get.

Versioning

The API is versioned in the path: every endpoint lives under /api/v1/.

https://{your-slug}.embaylms.com/api/v1/users

A new major version would appear as a new prefix (/api/v2/) served alongside v1, not as a change to v1. We do not use header-based or query-parameter versioning, and there are no dated sub-versions.

What we may change inside `v1` without a new version

These are additive and will not break a correctly-written client:

New endpoints.
New optional query parameters (existing defaults never change).
New fields in a response object. Your client must ignore unknown fields.
New enum values in a field already documented as an enum. Handle unknown values gracefully rather than throwing.
New optional request-body fields.

What counts as breaking, and will not happen inside `v1`

Removing or renaming an endpoint, a response field, or a query parameter.
Changing a field’s type, or its meaning.
Making an optional request field required.
Removing an enum value.
Changing the response envelope ({ data, meta, error }).
Tightening authentication or scope requirements on an existing endpoint.

If we need to do any of these, it goes in a new major version, and v1 is deprecated under the policy below.

Deprecation

The support window

Commitment	Value
Minimum notice before an endpoint is removed	12 months from the date the `Deprecation` header first appears
Minimum notice before a whole API version is removed	24 months
Notice for a security-forced removal	As much as is safely possible — this is the one case the windows above may be shortened, and we will contact affected integrators directly

A deprecated endpoint keeps working normally for the whole window. It is not rate-limited differently, does not return warnings in the body, and does not degrade. The only change is the headers below.

How you find out

1. Response headers (RFC 8594). Every response from a deprecated endpoint carries:

Header	Meaning
`Deprecation`	An HTTP-date: when the endpoint was deprecated
`Sunset`	An HTTP-date: the earliest date it may be removed. Absent if no removal date has been committed yet
`Link: <…>; rel="deprecation"`	This page
`Link: <…>; rel="successor-version"`	The replacement, when there is a direct one

HTTP/1.1 200 OK
Deprecation: Wed, 01 Oct 2026 00:00:00 GMT
Sunset: Fri, 01 Oct 2027 00:00:00 GMT
Link: <https://docs.embaylms.com/api-reference/versioning-and-deprecation>; rel="deprecation"; type="text/html"

Log these headers. They are the earliest and most reliable signal you will get. A monitor that alerts on the presence of a Deprecation header on any response is about ten lines of code and turns a future outage into a ticket.

2. The OpenAPI spec. A deprecated operation is flagged deprecated: true at /api/v1/docs, and its description opens with the deprecation date, the reason and the sunset date. Most API tooling renders this as a strikethrough.

3. These docs. The endpoint’s own reference page carries the same notice.

4. Directly. We count calls to deprecated endpoints per API key, so before a sunset date we can contact the specific integrations still using one. This is also why it is worth keeping the contact address on your API key current.

Currently deprecated

Nothing. No endpoint in v1 is deprecated today.

This policy is published ahead of need on purpose: an endpoint we might want to retire next year has to have been sending warnings since this year, so the mechanism has to exist before the first deprecation, not with it.

What we ask of your client

Following these means an additive change will never break you:

Ignore unknown fields in responses rather than failing validation.
Handle unknown enum values without throwing.
Do not depend on field order in JSON objects or on the exact wording of error.message — parse error.code (the HTTP status) instead.
Read the meta pagination block rather than assuming a page size.
Log Deprecation / Sunset headers, and alert on them.
Retry 429 using Retry-After, and use exponential backoff on 5xx.

Troubleshooting

I see a Deprecation header but no Sunset. Expected. The endpoint is deprecated but no removal date has been committed. You have at least 12 months from the Deprecation date, and a Sunset header will appear once a date is set.

An endpoint disappeared without warning. That should not happen inside the policy. Check that you were reading response headers — the warning is delivered there first and is easy to miss if you only watch status codes. If you were, contact support with the endpoint and the date you last saw it working; we treat this as an incident.

The spec says deprecated: true but I get no headers. Check that you are reading headers from the API response itself and not from a proxy or SDK that strips them. If the API genuinely sends none, that is a bug — please report it.

Will v1 be removed? Not without 24 months’ notice, a v2 running alongside it, and a migration guide.

Errors Plans (public pricing catalog)