Deprecation notice for the legacy Annotations API
Deprecation notice for the legacy Annotations API
The legacy Annotations API (/api/annotations) is deprecated in favor of a new Annotations API at /apis/annotation.grafana.app/v0alpha1. The new API uses the same structure as Grafana’s newest APIs, with each annotation as its own resource that you can create, read, update, patch, and delete, plus dedicated search and tags endpoints.
The legacy API still works. Grafana isn’t disabling legacy /api endpoints yet. They remain available, but won’t be updated. Removal of legacy APIs is planned for a future major release, and any breaking changes will be announced well in advance to avoid disruptions.
Availability
- Grafana Cloud: The new API is rolling out gradually, so it might not be available on your stack yet.
- Self-managed Grafana: The new API is available but disabled by default. To enable it, set
enabled = truein the[annotations.app_platform]section of the Grafana configuration.
The API is an alpha version (v0alpha1), so it might change.
What to know before you migrate
The new API doesn’t map one-to-one to the legacy API. In particular:
- Annotations are identified by
metadata.nameinstead of a numericid. - You find annotations with
GET .../search, which filters by dashboard, panel, time range, tags, and creator, and pages through results with acontinuetoken. dashboardIdisn’t supported. UsedashboardUID.- Alert annotations aren’t available. Keep using the legacy API for them.
- The legacy
datafield and the mass-delete endpoint aren’t available in the new API. - After you create an annotation, you can’t change its
time,timeEnd,dashboardUID, orpanelID. Instead, you need to delete and recreate the annotation with the updated values.
Refer to the migration section of the documentation for all the details.
What you need to do
Nothing today. Your existing integrations keep working. For new integrations, use the new API once it’s available on your stack.
