Annotations

Oodle supports creating, updating, listing, and deleting annotations via HTTP API. Use annotations to mark deployment events, releases, configuration changes, or any significant event on your dashboards as vertical markers on time-series panels.

Authentication

All requests require an API key passed in the X-API-KEY header. You can find your API key on the Settings > Integrations page in the Oodle UI.

Create an annotation

curl -X POST \
  https://<API_DOMAIN>/v1/api/instance/<INSTANCE_ID>/grafana/annotations \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <API_KEY>" \
  -d "{
    \"text\": \"Deployed v1.2.3 to production\",
    \"tags\": [\"deployment\", \"production\"],
    \"time\": $(date +%s)000
  }"

Request body

Field	Type	Required	Description
text	string	Yes	Description of the event
tags	string[]	No	Tags for filtering annotations
time	int64	No	Start time in epoch milliseconds (defaults to now)
timeEnd	int64	No	End time in epoch ms (for range annotations)
dashboardId	int64	No	Scope to a specific dashboard
panelId	int64	No	Scope to a specific panel

Response

{
  "id": 42,
  "message": "Annotation added"
}

List annotations

curl \
  "https://<API_DOMAIN>/v1/api/instance/<INSTANCE_ID>/grafana/annotations?tags=deployment&limit=10" \
  -H "X-API-KEY: <API_KEY>"

Query parameters

Parameter	Type	Description
from	int64	Start of time range (epoch ms)
to	int64	End of time range (epoch ms)
tags	string	Filter by tag (repeat for multiple)
dashboardId	int64	Filter by dashboard ID
panelId	int64	Filter by panel ID
limit	int32	Max annotations to return

Response

[
  {
    "id": 42,
    "dashboardId": 1,
    "dashboardUID": "abc123",
    "panelId": 0,
    "time": 1718000000000,
    "timeEnd": 0,
    "text": "Deployed v1.2.3 to production",
    "tags": ["deployment", "production"],
    "created": 1718000000000,
    "updated": 1718000000000
  }
]

Update an annotation

curl -X PUT \
  "https://<API_DOMAIN>/v1/api/instance/<INSTANCE_ID>/grafana/annotations/<ANNOTATION_ID>" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <API_KEY>" \
  -d '{
    "text": "Deployed v1.2.4 (hotfix)",
    "tags": ["deployment", "hotfix"]
  }'

Request body

Field	Type	Required	Description
text	string	Yes	Updated description
tags	string[]	No	Updated tags
time	int64	No	Updated start time (epoch ms)
timeEnd	int64	No	Updated end time (epoch ms)

Response

{
  "message": "Annotation updated"
}

Delete an annotation

curl -X DELETE \
  "https://<API_DOMAIN>/v1/api/instance/<INSTANCE_ID>/grafana/annotations/<ANNOTATION_ID>" \
  -H "X-API-KEY: <API_KEY>"

Response

{
  "message": "Annotation deleted"
}

CI/CD integration

Add annotation creation to your CI/CD pipeline to automatically mark deployments on dashboards:

GitHub Actions

- name: Create deployment annotation
  run: |
    curl -X POST \
      "https://${{ secrets.OODLE_API_DOMAIN }}/v1/api/instance/${{ secrets.OODLE_INSTANCE }}/grafana/annotations" \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: ${{ secrets.OODLE_API_KEY }}" \
      -d "{
        \"text\": \"Deployed ${{ github.sha }} to production\",
        \"tags\": [\"deployment\", \"${{ github.ref_name }}\"],
        \"time\": $(date +%s)000
      }"

Integration setup

You can find the API domain, instance ID, and API key on the Annotations tile in the Integrations page of the Oodle UI.