What this policy promises
APIs change over time. This policy explains how much notice you’ll receive before a breaking change affects your integration.In summary, stable endpoints receive at least 180 days’ notice before a breaking change or a removal. After the deprecation period ends, the endpoint returns
410 Gone and points you at its replacement. It never returns incorrect or partial data.What this policy covers
This policy applies to every endpoint documented on docs.semgrep.dev, according to its maturity level. Each endpoint’s maturity is shown as a badge in the API reference and as a badge extension in the OpenAPI spec.
Undocumented endpoints are not covered. If an endpoint does not appear in the published API reference, it is not part of the supported API, regardless of what you see in your browser’s network tab. This includes internal endpoints used by Semgrep AppSec Platform and the Semgrep CLI. These endpoints may change or be removed without notice and are not supported for customer integrations.
What counts as a breaking change
Semgrep considers the following to be breaking changes:- Remove or rename the endpoint, or change its URL path or HTTP method.
- Remove or rename a field in a response, whether or not that field is optional.
- Change the type of an existing field, or narrow the set of values it accepts.
- Add a new required request parameter, or make an existing optional one required.
- Change the meaning of an existing field without changing its name.
- Add a new endpoint, or a new optional request parameter.
- Add a new field to a response. Parse responses so that unrecognized fields are ignored rather than treated as an error.
- Add a new value to an existing enum, unless that enum is documented as closed.
- Change the order of items in a response where no order is documented.
- Change human-readable text, such as an
errormessage, that is not documented as stable.
Exception: unavoidable urgent changes
If Semgrep assesses that continuing to support an endpoint, field, or other aspect of API behavior would expose customer data, create a security risk, or have other serious impacts, Semgrep may make changes with less notice than described above, or in rare cases without notice. Semgrep will not invoke this exception lightly. When invoked, Semgrep will communicate what changed and why as soon as possible.Identify deprecated endpoints
- Subscribe to the API changelog: Every deprecation is announced in the changelog on the day it ships, marked Deprecated, and filed under Potentially breaking so that it still appears when you filter the changelog for changes that can affect your integration. Each API version has its own RSS feed. Subscribe to the v1 or v2 feed to receive deprecation notices automatically.
- Check the API reference: The API reference marks deprecated endpoints and includes their sunset dates.
- Monitor deprecation headers: Deprecated endpoints include
DeprecationandSunsetresponse headers. Monitoring these headers in your application logs helps identify any deprecated endpoints that your integration still depends on. - Contact Semgrep if you’re unsure: If you’re unsure whether an endpoint or feature is covered by this policy, contact support@semgrep.com and Semgrep will confirm in writing.
What happens at sunset
Once an endpoint’s sunset date arrives, it stops serving data and returns410 Gone. The removal is recorded in the changelog on the day it happens, so the end of an endpoint’s life is announced the same way its deprecation was. Semgrep does not silently leave a sunset endpoint running, and it never responds with partial or stale data in place of the data you asked for.
A sunset response looks like this:
When an endpoint is removed with no replacement, the
Link header is omitted and the error string says that no replacement exists. The Deprecation and Sunset headers are also sent on successful responses throughout the notice period, not only at sunset.