Agent skill

grafana-http-api

Comprehensive skill for interacting with Grafana's HTTP API to manage dashboards, data sources, folders, alerting, annotations, users, teams, and organizations. Use when Claude needs to (1) Create, read, update, or delete Grafana dashboards, (2) Manage data sources and connections, (3) Configure alerting rules, contact points, and notification policies, (4) Work with folders and permissions, (5) Manage users, teams, and service accounts, (6) Create or query annotations, (7) Execute queries against data sources, or any other Grafana automation task via API.

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/grafana-http-api

SKILL.md

Grafana HTTP API Skill

Programmatically manage Grafana resources including dashboards, data sources, alerting, folders, annotations, users, teams, and organizations.

Authentication

Service Account Token (Recommended)

bash

curl -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
     -H "Content-Type: application/json" \
     https://your-grafana.com/api/dashboards/home

Basic Auth

bash

curl -u admin:admin https://your-grafana.com/api/org

Multi-Organization Header

Use X-Grafana-Org-Id header to specify target organization:

bash

curl -H "Authorization: Bearer <TOKEN>" \
     -H "X-Grafana-Org-Id: 2" \
     https://your-grafana.com/api/org

Quick Reference

Dashboards

Search dashboards:

bash

GET /api/search?type=dash-db&query=<search_term>&tag=<tag>&folderIds=<folder_id>

Get dashboard by UID:

bash

GET /api/dashboards/uid/<dashboard_uid>

Create/Update dashboard:

bash

POST /api/dashboards/db
{
  "dashboard": {
    "id": null,
    "uid": null,
    "title": "Production Overview",
    "tags": ["templated"],
    "timezone": "browser",
    "schemaVersion": 16,
    "refresh": "25s"
  },
  "folderUid": "l3KqBxCMz",
  "message": "Made changes to xyz",
  "overwrite": false
}

Delete dashboard:

bash

DELETE /api/dashboards/uid/<dashboard_uid>

Data Sources

List all data sources:

bash

GET /api/datasources

Get data source by UID:

bash

GET /api/datasources/uid/<datasource_uid>

Create data source:

bash

POST /api/datasources
{
  "name": "Prometheus",
  "type": "prometheus",
  "url": "http://prometheus:9090",
  "access": "proxy",
  "basicAuth": false,
  "isDefault": true
}

Query data source:

bash

POST /api/ds/query
{
  "queries": [
    {
      "refId": "A",
      "datasource": { "uid": "<datasource_uid>" },
      "expr": "up",
      "intervalMs": 1000,
      "maxDataPoints": 43200
    }
  ],
  "from": "now-1h",
  "to": "now"
}

Health check:

bash

GET /api/datasources/uid/<datasource_uid>/health

Folders

List folders:

bash

GET /api/folders

Create folder:

bash

POST /api/folders
{
  "title": "My Folder",
  "uid": "my-folder-uid"
}

Get folder:

bash

GET /api/folders/<folder_uid>

Update folder:

bash

PUT /api/folders/<folder_uid>
{
  "title": "Updated Folder Title",
  "version": 1
}

Delete folder:

bash

DELETE /api/folders/<folder_uid>?forceDeleteRules=true

Alerting

List all alert rules:

bash

GET /api/v1/provisioning/alert-rules

Get alert rule:

bash

GET /api/v1/provisioning/alert-rules/<rule_uid>

Create alert rule:

bash

POST /api/v1/provisioning/alert-rules
{
  "title": "High CPU Alert",
  "ruleGroup": "CPU Alerts",
  "folderUID": "<folder_uid>",
  "noDataState": "OK",
  "execErrState": "OK",
  "for": "5m",
  "condition": "B",
  "annotations": { "summary": "CPU usage is high" },
  "labels": { "severity": "warning" },
  "data": [
    {
      "refId": "A",
      "relativeTimeRange": { "from": 600, "to": 0 },
      "datasourceUid": "<datasource_uid>",
      "model": {
        "expr": "100 - (avg(rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)",
        "refId": "A"
      }
    },
    {
      "refId": "B",
      "relativeTimeRange": { "from": 0, "to": 0 },
      "datasourceUid": "-100",
      "model": {
        "type": "classic_conditions",
        "refId": "B",
        "conditions": [{
          "evaluator": { "type": "gt", "params": [80] },
          "operator": { "type": "and" },
          "query": { "params": ["A"] },
          "reducer": { "type": "avg" }
        }]
      }
    }
  ]
}

List contact points:

bash

GET /api/v1/provisioning/contact-points

List notification policies:

bash

GET /api/v1/provisioning/policies

Get active alerts:

bash

GET /api/alertmanager/grafana/api/v2/alerts

Annotations

Query annotations:

bash

GET /api/annotations?from=<epoch_ms>&to=<epoch_ms>&tags=tag1&tags=tag2&limit=100

Create annotation:

bash

POST /api/annotations
{
  "dashboardUID": "jcIIG-07z",
  "panelId": 2,
  "time": 1507037197339,
  "timeEnd": 1507180805056,
  "tags": ["tag1", "tag2"],
  "text": "Annotation Description"
}

Update annotation:

bash

PUT /api/annotations/<annotation_id>
{
  "time": 1507037197339,
  "timeEnd": 1507180805056,
  "text": "Updated annotation",
  "tags": ["updated-tag"]
}

Delete annotation:

bash

DELETE /api/annotations/<annotation_id>

Users & Teams

Search users (admin):

bash

GET /api/users/search?perpage=10&page=1&query=<search_term>

Get current user:

bash

GET /api/user

List teams:

bash

GET /api/teams/search?perpage=50&page=1&name=<team_name>

Create team:

bash

POST /api/teams
{
  "name": "MyTeam",
  "email": "team@example.com"
}

Add user to team:

bash

POST /api/teams/<team_id>/members
{
  "userId": <user_id>
}

Organizations

Get current organization:

bash

GET /api/org

List all organizations (admin):

bash

GET /api/orgs

Create organization (admin):

bash

POST /api/orgs
{
  "name": "New Org"
}

Service Accounts

List service accounts:

bash

GET /api/serviceaccounts/search?perpage=10&page=1

Create service account:

bash

POST /api/serviceaccounts
{
  "name": "automation-sa",
  "role": "Editor"
}

Create service account token:

bash

POST /api/serviceaccounts/<service_account_id>/tokens
{
  "name": "token-name",
  "secondsToLive": 86400
}

Reference Documentation

For detailed API documentation by domain:

Dashboards API: Complete dashboard CRUD, versions, permissions
Data Sources API: Data source management, queries, health checks
Alerting API: Alert rules, contact points, notification policies, silences
Folders API: Folder management and permissions
Annotations API: Create, query, update annotations
Users & Teams API: User management, team operations
Common Patterns: Error handling, pagination, Python utilities

Python Helper Library

Use scripts/grafana_api.py for a reusable Python client:

python

from grafana_api import GrafanaAPI

# Initialize client
grafana = GrafanaAPI(
    base_url="https://your-grafana.com",
    token="your-service-account-token"
)

# List dashboards
dashboards = grafana.search_dashboards(query="production")

# Get dashboard details
dashboard = grafana.get_dashboard_by_uid("abc123")

# Create annotation
grafana.create_annotation(
    dashboard_uid="abc123",
    text="Deployment completed",
    tags=["deploy", "production"]
)

# Query data source
result = grafana.query_datasource(
    datasource_uid="prometheus-uid",
    expr="up",
    start="now-1h",
    end="now"
)

Common Operations

Export Dashboard as JSON

bash

curl -H "Authorization: Bearer <TOKEN>" \
     https://your-grafana.com/api/dashboards/uid/<uid> | jq '.dashboard'

Import Dashboard

bash

curl -X POST -H "Authorization: Bearer <TOKEN>" \
     -H "Content-Type: application/json" \
     -d @dashboard.json \
     https://your-grafana.com/api/dashboards/db

Bulk Delete Dashboards by Tag

python

dashboards = grafana.search_dashboards(tag="deprecated")
for dash in dashboards:
    grafana.delete_dashboard(dash['uid'])

Clone Dashboard to Another Folder

python

source = grafana.get_dashboard_by_uid("source-uid")
source['dashboard']['id'] = None
source['dashboard']['uid'] = None
source['dashboard']['title'] = f"{source['dashboard']['title']} (Copy)"
source['folderUid'] = "target-folder-uid"
grafana.create_or_update_dashboard(source)

Error Handling

Common HTTP status codes:

200: Success
400: Bad request (invalid JSON, missing required fields)
401: Unauthorized (invalid/missing token)
403: Forbidden (insufficient permissions)
404: Not found
409: Conflict (resource already exists)
412: Precondition failed (version mismatch)
422: Unprocessable entity (validation error)

Tips

Use UIDs over IDs: UIDs are portable across Grafana instances
Include version for updates: Prevents overwriting concurrent changes
Use overwrite: true carefully: Only when you want to force-update
Paginate large results: Use limit and page parameters
Test in dev first: Always test API calls on non-production instances
Service accounts over API keys: API keys are deprecated in newer Grafana versions

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/data/grafana-http-api
License: MIT License

Featured Tools

Join Our Newsletter

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Grafana HTTP API Skill

Authentication

Service Account Token (Recommended)

Basic Auth

Multi-Organization Header

Quick Reference

Dashboards

Data Sources

Folders

Alerting

Annotations

Users & Teams

Organizations

Service Accounts

Reference Documentation

Python Helper Library

Common Operations

Export Dashboard as JSON

Import Dashboard

Bulk Delete Dashboards by Tag

Clone Dashboard to Another Folder

Error Handling

Tips

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state