Skip to content

Annotations API

Annotations are org-scoped event markers — a deploy, a release, an incident — that overlay your time-series charts so a spike lines up with the change that caused it. The most common use is a CI/CD pipeline posting a marker the moment it ships. The API key surface gives you full CRUD at /api/v1/annotations.

For the concept, the name-prefix filtering model, and how markers render on charts, see Annotations.

Endpoints

Method Path Purpose
GET /api/v1/annotations List annotations, filtered by time range and name prefix
POST /api/v1/annotations Create an annotation
PUT /api/v1/annotations/:id Update an existing annotation
DELETE /api/v1/annotations/:id Delete an annotation

All four authenticate with X-API-Key.

Creating a deploy marker

A POST with a name and title is enough — it creates a point-in-time marker at the moment of the request.

curl -X POST https://server/api/v1/annotations \
  -H "X-API-Key: $HEXCOVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"deploy/myapp","title":"v2.3.1 to production"}'
Field Required Meaning
name yes A free-form, slash-namespaced label used for filtering (e.g. deploy/myapp, app/release-v2.3, incident/outage-db). Charts filter by prefix — deploy/ shows every deploy marker.
title yes The human-readable text shown on the marker.
start_time no ISO-8601 timestamp for the event. Defaults to now.
end_time no ISO-8601 timestamp. Set it alongside start_time to make the annotation a duration (a shaded band) instead of a point.

The name is the lever for organizing markers: pick a stable prefix per source (deploy/, migration/, incident/) so dashboards and widgets can pull exactly the band they care about. Annotations are stored in the control plane and retained 90 days.

Listing

GET /api/v1/annotations returns the annotations in scope, narrowable by time range and name prefix so a dashboard only pulls the markers relevant to its window:

curl https://server/api/v1/annotations \
  -H "X-API-Key: $HEXCOVERY_API_KEY"

Updating and deleting

Use the annotation's id (returned at create and list time) to amend or remove a marker — for example to set an end_time once an incident resolves:

# Update
curl -X PUT https://server/api/v1/annotations/123 \
  -H "X-API-Key: $HEXCOVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"v2.3.1 — rolled back"}'

# Delete
curl -X DELETE https://server/api/v1/annotations/123 \
  -H "X-API-Key: $HEXCOVERY_API_KEY"
  • Annotations — the concept, prefix filtering, and chart overlay behavior.