Grafana

grafana-skill

Programmatically manage Grafana resources using TypeScript tools and HTTP API workflows.

Workflow Routing

Tools

DashboardCrud CLI

# Set environment variables
export GRAFANA_URL="https://grafana.example.com"
export GRAFANA_TOKEN="your-service-account-token"

# List dashboards
bun run Tools/DashboardCrud.ts list
bun run Tools/DashboardCrud.ts list --query production --tag monitoring

# Get dashboard by UID
bun run Tools/DashboardCrud.ts get abc123

# Export dashboard to JSON
bun run Tools/DashboardCrud.ts export abc123 --output dashboard.json

# Create dashboard from JSON file
bun run Tools/DashboardCrud.ts create --file dashboard.json --folder my-folder

# Update dashboard
bun run Tools/DashboardCrud.ts update abc123 --file updated.json --message "Updated panels"

# Clone dashboard
bun run Tools/DashboardCrud.ts clone abc123 --title "Production Copy" --folder prod-folder

# View version history
bun run Tools/DashboardCrud.ts versions abc123

# Restore to previous version
bun run Tools/DashboardCrud.ts restore abc123 --version 5

# Delete dashboard
bun run Tools/DashboardCrud.ts delete abc123

GrafanaClient TypeScript Library

import { GrafanaClient, createGrafanaClient } from './Tools/GrafanaClient';

// Initialize from environment variables
const client = createGrafanaClient();

// Or with explicit config
const client = new GrafanaClient({
  baseUrl: 'https://grafana.example.com',
  token: 'your-service-account-token',
  orgId: 1, // optional
});

// Dashboard operations
const dashboards = await client.searchDashboards({ query: 'production', tag: 'monitoring' });
const dashboard = await client.getDashboardByUid('abc123');
const saved = await client.saveDashboard({ dashboard: myDashboard, folderUid: 'folder-uid' });
await client.deleteDashboard('abc123');

// Version management
const versions = await client.getDashboardVersions('abc123');
await client.restoreDashboardVersion('abc123', 5);

// Folders, Data sources, Alerting, Annotations also available

Authentication

# Service Account Token (Recommended)
export GRAFANA_TOKEN="glsa_xxxxxxxxxxxxxxxxxxxx"

# Multi-Organization Header
curl -H "Authorization: Bearer $GRAFANA_TOKEN" \
     -H "X-Grafana-Org-Id: 2" \
     https://grafana.example.com/api/org

Quick API Reference

Reference Documentation

• [Dashboards](References/Dashboards.md): Complete dashboard CRUD, versions, permissions
• [DataSources](References/DataSources.md): Data source management, queries, health checks
• [Alerting](References/Alerting.md): Alert rules, contact points, notification policies
• [Folders](References/Folders.md): Folder management and permissions
• [Annotations](References/Annotations.md): Create, query, update annotations
• [UsersTeams](References/UsersTeams.md): User management, team operations
• [CommonPatterns](References/CommonPatterns.md): Error handling, pagination, utilities

Examples

Example 1: List and export dashboards

User: "List all production dashboards and export them"
→ bun run Tools/DashboardCrud.ts list --tag production
→ For each: bun run Tools/DashboardCrud.ts export <uid>
→ Returns list of exported JSON files

Example 2: Create dashboard from JSON

User: "Create a new dashboard from this JSON file"
→ bun run Tools/DashboardCrud.ts create --file dashboard.json --folder monitoring
→ Returns new dashboard UID and URL

Example 3: Clone dashboard to another folder

User: "Clone the CPU dashboard to the production folder"
→ bun run Tools/DashboardCrud.ts clone cpu-uid --title "CPU Prod" --folder prod-folder
→ Returns cloned dashboard details

Example 4: Restore dashboard version

User: "Restore dashboard abc123 to version 5"
→ bun run Tools/DashboardCrud.ts versions abc123
→ bun run Tools/DashboardCrud.ts restore abc123 --version 5
→ Dashboard restored, new version created

Example 5: Programmatic bulk update

User: "Write TypeScript to bulk update dashboard tags"
→ Uses GrafanaClient library:
   const client = createGrafanaClient();
   const dashboards = await client.searchDashboards({ tag: 'old-tag' });
   for (const dash of dashboards) {
     const full = await client.getDashboardByUid(dash.uid);
     full.dashboard.tags = full.dashboard.tags.filter(t => t !== 'old-tag');
     full.dashboard.tags.push('new-tag');
     await client.saveDashboard({ dashboard: full.dashboard, message: 'Updated tags' });
   }

Error Handling

Tips

1. Use UIDs over IDs: UIDs are portable across Grafana instances 2. Include version for updates: Prevents overwriting concurrent changes 3. Use `overwrite: true` carefully: Only when you want to force-update 4. Service accounts over API keys: API keys are deprecated in newer Grafana versions

---

Gotchas

• Datasource permission: viewers can see the panel but get "query forbidden" if the datasource has explicit per-team permissions — confusing for non-admin users.
• Variable interpolation: $__interval and $__name are interpreted differently in legacy vs newer query backends; same dashboard JSON behaves differently.
• Provisioning datasources via YAML under /etc/grafana/provisioning: edits via UI are silently reverted on file re-read; pick one source of truth.
• API tokens are per-org — multi-org Grafana setups need separate tokens; a global "admin" token doesn't span orgs.
• Annotation queries with missing time-field return zero annotations without error — debug by checking the raw query response, not the panel.
• Alert rule state lives in the Grafana DB, not in Prometheus — rolling Grafana back loses alert state history.

Alerting API Reference

Complete reference for Grafana Alerting HTTP API endpoints (Grafana 9.0+).

Table of Contents

• Alert Rules
• Rule Groups
• Contact Points
• Notification Policies
• Mute Timings
• Silences
• Active Alerts
• Templates

---

Alert Rules

List All Alert Rules

GET /api/v1/provisioning/alert-rules

Example Response:

[
  {
    "id": 1,
    "uid": "cIBgcSjkk",
    "orgID": 1,
    "folderUID": "l3KqBxCMz",
    "ruleGroup": "CPU Alerts",
    "title": "High CPU Alert",
    "condition": "B",
    "data": [...],
    "updated": "2024-06-20T14:22:00Z",
    "noDataState": "OK",
    "execErrState": "OK",
    "for": "5m",
    "annotations": {"summary": "CPU usage is high"},
    "labels": {"severity": "warning"},
    "provenance": ""
  }
]

Get Alert Rule by UID

GET /api/v1/provisioning/alert-rules/:uid

Create Alert Rule

POST /api/v1/provisioning/alert-rules

Complete Example:

{
  "title": "High Memory Usage",
  "ruleGroup": "Memory Alerts",
  "folderUID": "l3KqBxCMz",
  "noDataState": "NoData",
  "execErrState": "Error",
  "for": "5m",
  "orgId": 1,
  "condition": "C",
  "annotations": {
    "summary": "Memory usage above 90%",
    "description": "Host {{ $labels.instance }} memory usage is {{ $values.A }}%",
    "runbook_url": "https://wiki.example.com/runbooks/memory"
  },
  "labels": {
    "severity": "critical",
    "team": "platform"
  },
  "data": [
    {
      "refId": "A",
      "queryType": "",
      "relativeTimeRange": {"from": 600, "to": 0},
      "datasourceUid": "prometheus-uid",
      "model": {
        "expr": "(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100",
        "instant": false,
        "intervalMs": 1000,
        "maxDataPoints": 43200,
        "refId": "A"
      }
    },
    {
      "refId": "B",
      "queryType": "",
      "relativeTimeRange": {"from": 600, "to": 0},
      "datasourceUid": "-100",
      "model": {
        "type": "reduce",
        "expression": "A",
        "reducer": "last",
        "refId": "B"
      }
    },
    {
      "refId": "C",
      "queryType": "",
      "relativeTimeRange": {"from": 0, "to": 0},
      "datasourceUid": "-100",
      "model": {
        "type": "threshold",
        "expression": "B",
        "refId": "C",
        "conditions": [
          {
            "evaluator": {"type": "gt", "params": [90]},
            "operator": {"type": "and"},
            "query": {"params": ["C"]},
            "reducer": {"type": "last"}
          }
        ]
      }
    }
  ]
}

Update Alert Rule

PUT /api/v1/provisioning/alert-rules/:uid

Delete Alert Rule

DELETE /api/v1/provisioning/alert-rules/:uid

---

Rule Groups

Get Rule Group

GET /api/v1/provisioning/folder/:folderUid/rule-groups/:group

Update Rule Group

PUT /api/v1/provisioning/folder/:folderUid/rule-groups/:group

Request Body:

{
  "name": "CPU Alerts",
  "interval": "1m",
  "rules": [...]
}

---

Contact Points

List Contact Points

GET /api/v1/provisioning/contact-points

Query Parameters:

Example Response:

[
  {
    "uid": "email-receiver",
    "name": "email-receiver",
    "type": "email",
    "settings": {
      "addresses": "alerts@example.com",
      "singleEmail": false
    },
    "disableResolveMessage": false
  }
]

Create Contact Point

POST /api/v1/provisioning/contact-points

Email Example:

{
  "name": "ops-team-email",
  "type": "email",
  "settings": {
    "addresses": "ops@example.com;oncall@example.com",
    "singleEmail": true
  },
  "disableResolveMessage": false
}

Slack Example:

{
  "name": "slack-alerts",
  "type": "slack",
  "settings": {
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
    "recipient": "#alerts",
    "username": "Grafana",
    "icon_emoji": ":grafana:",
    "mentionUsers": "U12345678",
    "mentionGroups": "S12345678",
    "mentionChannel": "here"
  }
}

PagerDuty Example:

{
  "name": "pagerduty",
  "type": "pagerduty",
  "settings": {
    "integrationKey": "your-integration-key",
    "severity": "critical",
    "class": "ping failure",
    "component": "Grafana",
    "group": "Production"
  }
}

Webhook Example:

{
  "name": "custom-webhook",
  "type": "webhook",
  "settings": {
    "url": "https://your-endpoint.com/alerts",
    "httpMethod": "POST",
    "username": "grafana",
    "password": "secret",
    "maxAlerts": 10
  }
}

Update Contact Point

PUT /api/v1/provisioning/contact-points/:uid

Delete Contact Point

DELETE /api/v1/provisioning/contact-points/:uid

---

Notification Policies

Get Notification Policy Tree

GET /api/v1/provisioning/policies

Example Response:

{
  "receiver": "email-receiver",
  "group_by": ["grafana_folder", "alertname"],
  "routes": [
    {
      "receiver": "slack-alerts",
      "object_matchers": [["severity", "=", "critical"]],
      "continue": false,
      "group_wait": "30s",
      "group_interval": "5m",
      "repeat_interval": "4h"
    }
  ],
  "group_wait": "30s",
  "group_interval": "5m",
  "repeat_interval": "4h"
}

Update Notification Policy Tree

PUT /api/v1/provisioning/policies

Request Body:

{
  "receiver": "email-receiver",
  "group_by": ["grafana_folder", "alertname"],
  "routes": [
    {
      "receiver": "pagerduty",
      "object_matchers": [
        ["severity", "=", "critical"],
        ["team", "=", "platform"]
      ],
      "continue": false,
      "group_wait": "10s",
      "group_interval": "1m",
      "repeat_interval": "1h"
    },
    {
      "receiver": "slack-alerts",
      "object_matchers": [["severity", "=", "warning"]],
      "continue": true,
      "mute_time_intervals": ["weekends"]
    }
  ],
  "group_wait": "30s",
  "group_interval": "5m",
  "repeat_interval": "4h"
}

---

Mute Timings

List Mute Timings

GET /api/v1/provisioning/mute-timings

Create Mute Timing

POST /api/v1/provisioning/mute-timings

Weekend Mute Example:

{
  "name": "weekends",
  "time_intervals": [
    {
      "weekdays": ["saturday", "sunday"]
    }
  ]
}

Business Hours Only Example:

{
  "name": "outside-business-hours",
  "time_intervals": [
    {
      "weekdays": ["monday:friday"],
      "times": [
        {"start_time": "00:00", "end_time": "09:00"},
        {"start_time": "17:00", "end_time": "24:00"}
      ]
    },
    {
      "weekdays": ["saturday", "sunday"]
    }
  ]
}

Update Mute Timing

PUT /api/v1/provisioning/mute-timings/:name

Delete Mute Timing

DELETE /api/v1/provisioning/mute-timings/:name

---

Silences

List Silences

GET /api/alertmanager/grafana/api/v2/silences

Create Silence

POST /api/alertmanager/grafana/api/v2/silences

Request Body:

{
  "matchers": [
    {"name": "alertname", "value": "HighCPU", "isRegex": false, "isEqual": true},
    {"name": "instance", "value": "server-01", "isRegex": false, "isEqual": true}
  ],
  "startsAt": "2024-06-20T10:00:00Z",
  "endsAt": "2024-06-20T18:00:00Z",
  "createdBy": "admin",
  "comment": "Scheduled maintenance window"
}

Delete Silence

DELETE /api/alertmanager/grafana/api/v2/silence/:silenceId

---

Active Alerts

Get All Active Alerts

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

Query Parameters:

Get Alert Groups

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

---

Templates

List Templates

GET /api/v1/provisioning/templates

Create/Update Template

PUT /api/v1/provisioning/templates/:name

Request Body:

{
  "template": "{{ define \"custom_email.subject\" }}\n[{{ .Status | toUpper }}{{ if eq .Status \"firing\" }}:{{ .Alerts.Firing | len }}{{ end }}] {{ .GroupLabels.alertname }}\n{{ end }}"
}

Delete Template

DELETE /api/v1/provisioning/templates/:name

---

Expression Types

For alert rule data queries, use datasourceUid: "-100" for expression types:

Reduce Example:

{
  "refId": "B",
  "datasourceUid": "-100",
  "model": {
    "type": "reduce",
    "expression": "A",
    "reducer": "last",
    "refId": "B"
  }
}

Threshold Example:

{
  "refId": "C",
  "datasourceUid": "-100",
  "model": {
    "type": "threshold",
    "expression": "B",
    "conditions": [
      {"evaluator": {"type": "gt", "params": [80]}}
    ]
  }
}

Annotations API Reference

Complete reference for Grafana Annotations HTTP API endpoints.

Table of Contents

• Query Annotations
• Create Annotation
• Create Graphite Annotation
• Update Annotation
• Patch Annotation
• Delete Annotation
• Find Annotation by ID
• Annotation Tags

---

Query Annotations

GET /api/annotations

Query Parameters:

Example Request:

curl -H "Authorization: Bearer <TOKEN>" \
  "https://grafana.example.com/api/annotations?from=1506676478816&to=1507281278816&tags=deploy&tags=production&limit=100"

Example Response:

[
  {
    "id": 1124,
    "alertId": 0,
    "dashboardId": 163,
    "dashboardUID": "cIBgcSjkk",
    "panelId": 2,
    "userId": 1,
    "userName": "admin",
    "newState": "",
    "prevState": "",
    "time": 1507266395000,
    "timeEnd": 1507266395000,
    "text": "Deployment completed",
    "tags": ["deploy", "production"],
    "data": {}
  }
]

Annotation Types:

• Dashboard annotation: Associated with a specific dashboard/panel
• Organization annotation: Global annotation visible across all dashboards
• Alert annotation: Auto-created when alert state changes

---

Create Annotation

POST /api/annotations

Dashboard Annotation

{
  "dashboardUID": "cIBgcSjkk",
  "panelId": 2,
  "time": 1507037197339,
  "timeEnd": 1507180805056,
  "tags": ["deploy", "production"],
  "text": "Deployment v2.1.0 completed"
}

Organization Annotation (Global)

Omit dashboardUID and panelId to create a global annotation:

{
  "time": 1507037197339,
  "tags": ["maintenance", "infrastructure"],
  "text": "Scheduled maintenance window started"
}

Point Annotation (Single Moment)

{
  "dashboardUID": "cIBgcSjkk",
  "time": 1507037197339,
  "tags": ["incident"],
  "text": "Service outage detected"
}

Region Annotation (Time Range)

Include timeEnd to create a region:

{
  "dashboardUID": "cIBgcSjkk",
  "time": 1507037197339,
  "timeEnd": 1507040797339,
  "tags": ["maintenance"],
  "text": "Maintenance window"
}

Request Fields:

Example Response:

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

---

Create Graphite Annotation

POST /api/annotations/graphite

Compatible with Graphite event format:

{
  "what": "Event - deploy",
  "tags": ["deploy", "production"],
  "when": 1467844481,
  "data": "deploy of main branch happened at Wed Jul 6 22:34:41 UTC 2016"
}

Fields:

---

Update Annotation

PUT /api/annotations/:annotationId

Replaces all properties of the annotation:

{
  "time": 1507037197339,
  "timeEnd": 1507040797339,
  "text": "Updated annotation text",
  "tags": ["updated", "deploy"]
}

---

Patch Annotation

PATCH /api/annotations/:annotationId

Updates only specified properties:

{
  "text": "Partially updated text"
}

Example - Update only tags:

{
  "tags": ["new-tag", "updated"]
}

Example - Extend time range:

{
  "timeEnd": 1507050797339
}

---

Delete Annotation

DELETE /api/annotations/:annotationId

Example Request:

curl -X DELETE -H "Authorization: Bearer <TOKEN>" \
  "https://grafana.example.com/api/annotations/1124"

Example Response:

{
  "message": "Annotation deleted"
}

---

Find Annotation by ID

GET /api/annotations/:annotationId

Example Response:

{
  "id": 1124,
  "alertId": 0,
  "dashboardId": 163,
  "dashboardUID": "cIBgcSjkk",
  "panelId": 2,
  "userId": 1,
  "userName": "admin",
  "newState": "",
  "prevState": "",
  "time": 1507266395000,
  "timeEnd": 1507270000000,
  "text": "Deployment completed",
  "tags": ["deploy", "production"],
  "data": {}
}

---

Annotation Tags

Get Annotation Tags

GET /api/annotations/tags

Returns all unique tags used in annotations.

Query Parameters:

Example Response:

{
  "result": {
    "tags": [
      {"tag": "deploy", "count": 15},
      {"tag": "production", "count": 12},
      {"tag": "incident", "count": 5},
      {"tag": "maintenance", "count": 8}
    ]
  }
}

---

Common Patterns

Deploy Marker

import time
import requests

def create_deploy_annotation(grafana_url, token, dashboard_uid, version, env):
    response = requests.post(
        f"{grafana_url}/api/annotations",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        },
        json={
            "dashboardUID": dashboard_uid,
            "time": int(time.time() * 1000),
            "tags": ["deploy", env, f"v{version}"],
            "text": f"Deployed version {version} to {env}"
        }
    )
    return response.json()

Maintenance Window

def create_maintenance_window(grafana_url, token, start_ms, end_ms, description):
    response = requests.post(
        f"{grafana_url}/api/annotations",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        },
        json={
            "time": start_ms,
            "timeEnd": end_ms,
            "tags": ["maintenance", "scheduled"],
            "text": description
        }
    )
    return response.json()

Clean Up Old Annotations

def delete_old_annotations(grafana_url, token, older_than_ms, tags=None):
    params = {
        "from": 0,
        "to": older_than_ms,
        "limit": 1000
    }
    if tags:
        params["tags"] = tags

    response = requests.get(
        f"{grafana_url}/api/annotations",
        headers={"Authorization": f"Bearer {token}"},
        params=params
    )

    annotations = response.json()
    for ann in annotations:
        requests.delete(
            f"{grafana_url}/api/annotations/{ann['id']}",
            headers={"Authorization": f"Bearer {token}"}
        )

    return len(annotations)

Common Patterns Reference

Error handling, pagination, and reusable patterns for the Grafana HTTP API.

Table of Contents

• Error Handling
• Pagination
• Rate Limiting
• Common Errors
• Python Client Examples
• Bash Script Examples

---

Error Handling

HTTP Status Codes

Error Response Format

{
  "message": "Dashboard not found",
  "status": "not-found"
}

Or with more detail:

{
  "message": "Failed to save dashboard",
  "status": "validation-failed",
  "messageId": "dashboards.dashboardNotFound",
  "traceID": "abc123def456"
}

---

Pagination

List Endpoints

Most list endpoints support pagination via limit and page:

GET /api/search?limit=50&page=1
GET /api/users/search?perpage=100&page=2

Response Metadata

Some endpoints return pagination metadata:

{
  "totalCount": 250,
  "page": 1,
  "perPage": 100,
  "users": [...]
}

Iterating All Pages

def get_all_pages(grafana, endpoint, key='results', page_size=100):
    all_results = []
    page = 1

    while True:
        response = grafana.get(f"{endpoint}?perpage={page_size}&page={page}")
        results = response.get(key, response)

        if not results:
            break

        all_results.extend(results)

        total = response.get('totalCount', len(results))
        if len(all_results) >= total:
            break

        page += 1

    return all_results

---

Rate Limiting

Grafana doesn't have built-in API rate limiting by default, but:

1. Reverse proxies may impose limits 2. Grafana Cloud has rate limits per tier 3. Best practice: Add delays between bulk operations

import time

def bulk_create_with_rate_limit(items, create_func, delay=0.1):
    results = []
    for item in items:
        result = create_func(item)
        results.append(result)
        time.sleep(delay)
    return results

---

Common Errors

Dashboard Version Conflict (412)

Error:

{
  "message": "The dashboard has been changed by someone else",
  "status": "version-mismatch"
}

Solution: Fetch latest version and retry:

def update_dashboard_safely(grafana, uid, updates):
    dashboard_data = grafana.get_dashboard_by_uid(uid)
    dashboard = dashboard_data['dashboard']

    # Apply updates
    dashboard.update(updates)

    # Include version for optimistic locking
    return grafana.create_or_update_dashboard({
        'dashboard': dashboard,
        'folderUid': dashboard_data['meta'].get('folderUid'),
        'overwrite': False
    })

Permission Denied (403)

Error:

{
  "message": "Access denied"
}

Common causes:

• Token lacks required permissions
• User not in correct organization
• RBAC restrictions (Enterprise)

Debug: Check service account permissions in Grafana UI.

Resource Not Found (404)

Error:

{
  "message": "Dashboard not found",
  "status": "not-found"
}

Common causes:

• Wrong UID or ID
• Resource in different organization
• Resource was deleted

---

Python Client Examples

Base Client Class

import requests
from typing import Optional, Dict, Any, List
from urllib.parse import urljoin

class GrafanaAPIError(Exception):
    def __init__(self, message: str, status_code: int, response: Dict):
        self.message = message
        self.status_code = status_code
        self.response = response
        super().__init__(f"{status_code}: {message}")

class GrafanaClient:
    def __init__(self, base_url: str, token: str, org_id: Optional[int] = None):
        self.base_url = base_url.rstrip('/')
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        })
        if org_id:
            self.session.headers['X-Grafana-Org-Id'] = str(org_id)

    def _request(self, method: str, endpoint: str, **kwargs) -> Dict:
        url = urljoin(self.base_url, endpoint)
        response = self.session.request(method, url, **kwargs)

        try:
            data = response.json()
        except:
            data = {'message': response.text}

        if not response.ok:
            raise GrafanaAPIError(
                data.get('message', 'Unknown error'),
                response.status_code,
                data
            )

        return data

    def get(self, endpoint: str, params: Dict = None) -> Dict:
        return self._request('GET', endpoint, params=params)

    def post(self, endpoint: str, json: Dict = None) -> Dict:
        return self._request('POST', endpoint, json=json)

    def put(self, endpoint: str, json: Dict = None) -> Dict:
        return self._request('PUT', endpoint, json=json)

    def patch(self, endpoint: str, json: Dict = None) -> Dict:
        return self._request('PATCH', endpoint, json=json)

    def delete(self, endpoint: str) -> Dict:
        return self._request('DELETE', endpoint)

Dashboard Operations

class DashboardMixin:
    def search_dashboards(
        self,
        query: str = None,
        tag: str = None,
        folder_uid: str = None,
        limit: int = 100
    ) -> List[Dict]:
        params = {'type': 'dash-db', 'limit': limit}
        if query:
            params['query'] = query
        if tag:
            params['tag'] = tag
        if folder_uid:
            params['folderUIDs'] = folder_uid
        return self.get('/api/search', params=params)

    def get_dashboard_by_uid(self, uid: str) -> Dict:
        return self.get(f'/api/dashboards/uid/{uid}')

    def create_or_update_dashboard(
        self,
        dashboard: Dict,
        folder_uid: str = None,
        message: str = None,
        overwrite: bool = False
    ) -> Dict:
        payload = {
            'dashboard': dashboard,
            'overwrite': overwrite
        }
        if folder_uid:
            payload['folderUid'] = folder_uid
        if message:
            payload['message'] = message
        return self.post('/api/dashboards/db', json=payload)

    def delete_dashboard(self, uid: str) -> Dict:
        return self.delete(f'/api/dashboards/uid/{uid}')

Data Source Operations

class DataSourceMixin:
    def list_datasources(self) -> List[Dict]:
        return self.get('/api/datasources')

    def get_datasource_by_uid(self, uid: str) -> Dict:
        return self.get(f'/api/datasources/uid/{uid}')

    def create_datasource(self, datasource: Dict) -> Dict:
        return self.post('/api/datasources', json=datasource)

    def update_datasource(self, uid: str, datasource: Dict) -> Dict:
        return self.put(f'/api/datasources/uid/{uid}', json=datasource)

    def delete_datasource(self, uid: str) -> Dict:
        return self.delete(f'/api/datasources/uid/{uid}')

    def health_check_datasource(self, uid: str) -> Dict:
        return self.get(f'/api/datasources/uid/{uid}/health')

    def query_datasource(self, queries: List[Dict], from_time: str, to_time: str) -> Dict:
        return self.post('/api/ds/query', json={
            'queries': queries,
            'from': from_time,
            'to': to_time
        })

Complete Client

class GrafanaAPI(GrafanaClient, DashboardMixin, DataSourceMixin):
    """Complete Grafana API client with all mixins."""
    pass

# Usage
grafana = GrafanaAPI(
    base_url='https://grafana.example.com',
    token='your-service-account-token'
)

# Search dashboards
dashboards = grafana.search_dashboards(query='production', tag='monitoring')

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

# Create annotation
grafana.post('/api/annotations', json={
    'dashboardUID': 'abc123',
    'time': int(time.time() * 1000),
    'tags': ['deploy'],
    'text': 'Deployment completed'
})

---

Bash Script Examples

Health Check Script

#!/bin/bash
GRAFANA_URL="${GRAFANA_URL:-http://localhost:3000}"
GRAFANA_TOKEN="${GRAFANA_TOKEN}"

check_health() {
    response=$(curl -s -w "\n%{http_code}" \
        -H "Authorization: Bearer $GRAFANA_TOKEN" \
        "$GRAFANA_URL/api/health")

    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | head -n-1)

    if [ "$http_code" = "200" ]; then
        echo "✓ Grafana is healthy"
        return 0
    else
        echo "✗ Grafana health check failed: $body"
        return 1
    fi
}

check_health

Export All Dashboards

#!/bin/bash
GRAFANA_URL="${GRAFANA_URL}"
GRAFANA_TOKEN="${GRAFANA_TOKEN}"
OUTPUT_DIR="${OUTPUT_DIR:-./dashboards}"

mkdir -p "$OUTPUT_DIR"

# Get all dashboard UIDs
uids=$(curl -s \
    -H "Authorization: Bearer $GRAFANA_TOKEN" \
    "$GRAFANA_URL/api/search?type=dash-db" | \
    jq -r '.[].uid')

for uid in $uids; do
    echo "Exporting dashboard: $uid"
    curl -s \
        -H "Authorization: Bearer $GRAFANA_TOKEN" \
        "$GRAFANA_URL/api/dashboards/uid/$uid" | \
        jq '.dashboard' > "$OUTPUT_DIR/$uid.json"
done

echo "Exported $(echo "$uids" | wc -w) dashboards to $OUTPUT_DIR"

Import Dashboard

#!/bin/bash
GRAFANA_URL="${GRAFANA_URL}"
GRAFANA_TOKEN="${GRAFANA_TOKEN}"
DASHBOARD_FILE="${1}"
FOLDER_UID="${2:-}"

if [ -z "$DASHBOARD_FILE" ]; then
    echo "Usage: $0 <dashboard.json> [folder_uid]"
    exit 1
fi

# Read dashboard and wrap it
dashboard=$(cat "$DASHBOARD_FILE")

payload=$(jq -n \
    --argjson dashboard "$dashboard" \
    --arg folderUid "$FOLDER_UID" \
    '{
        dashboard: ($dashboard | .id = null | .uid = null),
        folderUid: $folderUid,
        overwrite: false
    }')

response=$(curl -s -X POST \
    -H "Authorization: Bearer $GRAFANA_TOKEN" \
    -H "Content-Type: application/json" \
    -d "$payload" \
    "$GRAFANA_URL/api/dashboards/db")

echo "$response" | jq .

Dashboards API Reference

Complete reference for Grafana Dashboard HTTP API endpoints.

Table of Contents

• Search Dashboards
• Get Dashboard by UID
• Create/Update Dashboard
• Delete Dashboard
• Get Dashboard Versions
• Restore Dashboard Version
• Dashboard Permissions
• Public/Shared Dashboards

---

Search Dashboards

GET /api/search

Query Parameters:

Example Request:

curl -H "Authorization: Bearer <TOKEN>" \
  "https://grafana.example.com/api/search?type=dash-db&query=production&tag=monitoring&limit=50"

Example Response:

[
  {
    "id": 163,
    "uid": "cIBgcSjkk",
    "title": "Production Overview",
    "uri": "db/production-overview",
    "url": "/d/cIBgcSjkk/production-overview",
    "slug": "",
    "type": "dash-db",
    "tags": ["monitoring", "production"],
    "isStarred": false,
    "folderId": 3,
    "folderUid": "l3KqBxCMz",
    "folderTitle": "Operations",
    "folderUrl": "/dashboards/f/l3KqBxCMz/operations",
    "sortMeta": 0
  }
]

---

Get Dashboard by UID

GET /api/dashboards/uid/:uid

Example Request:

curl -H "Authorization: Bearer <TOKEN>" \
  "https://grafana.example.com/api/dashboards/uid/cIBgcSjkk"

Example Response:

{
  "meta": {
    "type": "db",
    "canSave": true,
    "canEdit": true,
    "canAdmin": true,
    "canStar": true,
    "canDelete": true,
    "slug": "production-overview",
    "url": "/d/cIBgcSjkk/production-overview",
    "expires": "0001-01-01T00:00:00Z",
    "created": "2023-01-15T10:30:00Z",
    "updated": "2024-06-20T14:22:00Z",
    "updatedBy": "admin",
    "createdBy": "admin",
    "version": 15,
    "hasAcl": false,
    "isFolder": false,
    "folderId": 3,
    "folderUid": "l3KqBxCMz",
    "folderTitle": "Operations",
    "folderUrl": "/dashboards/f/l3KqBxCMz/operations",
    "provisioned": false,
    "provisionedExternalId": ""
  },
  "dashboard": {
    "id": 163,
    "uid": "cIBgcSjkk",
    "title": "Production Overview",
    "tags": ["monitoring", "production"],
    "timezone": "browser",
    "schemaVersion": 38,
    "version": 15,
    "refresh": "30s",
    "panels": [...]
  }
}

---

Create/Update Dashboard

POST /api/dashboards/db

Request Body:

{
  "dashboard": {
    "id": null,
    "uid": null,
    "title": "New Dashboard",
    "tags": ["tag1", "tag2"],
    "timezone": "browser",
    "schemaVersion": 38,
    "refresh": "30s",
    "panels": [
      {
        "id": 1,
        "type": "timeseries",
        "title": "CPU Usage",
        "gridPos": {"h": 8, "w": 12, "x": 0, "y": 0},
        "targets": [
          {
            "refId": "A",
            "datasource": {"type": "prometheus", "uid": "prometheus"},
            "expr": "100 - (avg(rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)"
          }
        ]
      }
    ]
  },
  "folderUid": "l3KqBxCMz",
  "message": "Initial commit",
  "overwrite": false
}

Fields:

Example Response (Success):

{
  "id": 163,
  "uid": "cIBgcSjkk",
  "url": "/d/cIBgcSjkk/new-dashboard",
  "status": "success",
  "version": 1,
  "slug": "new-dashboard"
}

---

Delete Dashboard

DELETE /api/dashboards/uid/:uid

Example Request:

curl -X DELETE -H "Authorization: Bearer <TOKEN>" \
  "https://grafana.example.com/api/dashboards/uid/cIBgcSjkk"

Example Response:

{
  "title": "Production Overview",
  "message": "Dashboard Production Overview deleted",
  "id": 163
}

---

Get Dashboard Versions

GET /api/dashboards/uid/:uid/versions

Query Parameters:

Example Response:

[
  {
    "id": 15,
    "dashboardId": 163,
    "parentVersion": 14,
    "restoredFrom": 0,
    "version": 15,
    "created": "2024-06-20T14:22:00Z",
    "createdBy": "admin",
    "message": "Updated thresholds"
  }
]

---

Restore Dashboard Version

POST /api/dashboards/uid/:uid/restore

Request Body:

{
  "version": 10
}

Example Response:

{
  "id": 163,
  "uid": "cIBgcSjkk",
  "url": "/d/cIBgcSjkk/production-overview",
  "status": "success",
  "version": 16,
  "slug": "production-overview"
}

---

Dashboard Permissions

Get Permissions

GET /api/dashboards/uid/:uid/permissions

Update Permissions

POST /api/dashboards/uid/:uid/permissions

Request Body:

{
  "items": [
    {"role": "Viewer", "permission": 1},
    {"role": "Editor", "permission": 2},
    {"teamId": 1, "permission": 1},
    {"userId": 11, "permission": 4}
  ]
}

Permission Levels:

• 1: View
• 2: Edit
• 4: Admin

---

Public/Shared Dashboards

Create Public Dashboard

POST /api/dashboards/uid/:uid/public-dashboards/

Request Body:

{
  "uid": "cd56d9fd-f3d4-486d-afba-a21760e2acbe",
  "accessToken": "5c948bf96e6a4b13bd91975f9a2028b7",
  "timeSelectionEnabled": false,
  "isEnabled": true,
  "annotationsEnabled": false,
  "share": "public"
}

Get Public Dashboard

GET /api/dashboards/uid/:uid/public-dashboards/

Update Public Dashboard

PATCH /api/dashboards/uid/:uid/public-dashboards/:publicDashboardUid

Delete Public Dashboard

DELETE /api/dashboards/uid/:uid/public-dashboards/:publicDashboardUid

Data Sources API Reference

Complete reference for Grafana Data Source HTTP API endpoints.

Table of Contents

• List Data Sources
• Get Data Source
• Create Data Source
• Update Data Source
• Delete Data Source
• Query Data Source
• Health Check
• Data Source Resources

---

List Data Sources

GET /api/datasources

Note: Default max returned is 5000. Pagination not currently supported.

Example Response:

[
  {
    "id": 1,
    "uid": "PE9C8AA5B1A6E7E89",
    "orgId": 1,
    "name": "Prometheus",
    "type": "prometheus",
    "typeName": "Prometheus",
    "typeLogoUrl": "public/app/plugins/datasource/prometheus/img/prometheus_logo.svg",
    "access": "proxy",
    "url": "http://prometheus:9090",
    "user": "",
    "database": "",
    "basicAuth": false,
    "isDefault": true,
    "jsonData": {
      "httpMethod": "POST",
      "manageAlerts": true,
      "prometheusType": "Prometheus"
    },
    "readOnly": false
  }
]

---

Get Data Source

By ID (Deprecated)

GET /api/datasources/:id

By UID (Recommended)

GET /api/datasources/uid/:uid

By Name

GET /api/datasources/name/:name

Example Response:

{
  "id": 1,
  "uid": "PE9C8AA5B1A6E7E89",
  "orgId": 1,
  "name": "Prometheus",
  "type": "prometheus",
  "access": "proxy",
  "url": "http://prometheus:9090",
  "basicAuth": false,
  "isDefault": true,
  "jsonData": {
    "httpMethod": "POST",
    "manageAlerts": true
  },
  "secureJsonFields": {},
  "version": 1,
  "readOnly": false
}

---

Create Data Source

POST /api/datasources

Prometheus Example

{
  "name": "Prometheus",
  "type": "prometheus",
  "url": "http://prometheus:9090",
  "access": "proxy",
  "basicAuth": false,
  "isDefault": true,
  "jsonData": {
    "httpMethod": "POST",
    "manageAlerts": true,
    "prometheusType": "Prometheus",
    "prometheusVersion": "2.47.0"
  }
}

InfluxDB Example

{
  "name": "InfluxDB",
  "type": "influxdb",
  "url": "http://influxdb:8086",
  "access": "proxy",
  "basicAuth": false,
  "database": "telegraf",
  "jsonData": {
    "httpMode": "POST",
    "version": "Flux"
  },
  "secureJsonData": {
    "token": "your-influxdb-token"
  }
}

PostgreSQL Example

{
  "name": "PostgreSQL",
  "type": "postgres",
  "url": "postgres:5432",
  "access": "proxy",
  "user": "grafana",
  "database": "grafana",
  "basicAuth": false,
  "jsonData": {
    "sslmode": "disable",
    "maxOpenConns": 100,
    "maxIdleConns": 100,
    "connMaxLifetime": 14400
  },
  "secureJsonData": {
    "password": "your-password"
  }
}

Loki Example

{
  "name": "Loki",
  "type": "loki",
  "url": "http://loki:3100",
  "access": "proxy",
  "basicAuth": false,
  "jsonData": {
    "maxLines": 1000,
    "derivedFields": [
      {
        "matcherRegex": "traceID=(\\w+)",
        "name": "TraceID",
        "url": "${__value.raw}",
        "datasourceUid": "tempo-uid"
      }
    ]
  }
}

CloudWatch Example

{
  "name": "CloudWatch",
  "type": "cloudwatch",
  "access": "proxy",
  "jsonData": {
    "authType": "default",
    "defaultRegion": "us-east-1"
  }
}

Azure Monitor Example

{
  "name": "Azure Monitor",
  "type": "grafana-azure-monitor-datasource",
  "access": "proxy",
  "jsonData": {
    "cloudName": "azuremonitor",
    "tenantId": "your-tenant-id",
    "clientId": "your-client-id",
    "subscriptionId": "your-subscription-id"
  },
  "secureJsonData": {
    "clientSecret": "your-client-secret"
  }
}

---

Update Data Source

By ID (Deprecated)

PUT /api/datasources/:id

By UID (Recommended)

PUT /api/datasources/uid/:uid

Request Body: Same as create, include all fields.

---

Delete Data Source

By ID (Deprecated)

DELETE /api/datasources/:id

By UID (Recommended)

DELETE /api/datasources/uid/:uid

By Name

DELETE /api/datasources/name/:name

---

Query Data Source

POST /api/ds/query

Execute queries against any data source with a backend implementation.

Prometheus Query Example

{
  "queries": [
    {
      "refId": "A",
      "datasource": {
        "type": "prometheus",
        "uid": "PE9C8AA5B1A6E7E89"
      },
      "expr": "up{job=\"prometheus\"}",
      "instant": false,
      "range": true,
      "intervalMs": 15000,
      "maxDataPoints": 1000
    }
  ],
  "from": "now-1h",
  "to": "now"
}

Loki Query Example

{
  "queries": [
    {
      "refId": "A",
      "datasource": {
        "type": "loki",
        "uid": "loki-uid"
      },
      "expr": "{job=\"nginx\"} |= \"error\"",
      "queryType": "range",
      "maxLines": 1000
    }
  ],
  "from": "now-1h",
  "to": "now"
}

SQL Query Example

{
  "queries": [
    {
      "refId": "A",
      "datasource": {
        "type": "postgres",
        "uid": "postgres-uid"
      },
      "rawSql": "SELECT time, value FROM metrics WHERE $__timeFilter(time)",
      "format": "time_series"
    }
  ],
  "from": "now-1h",
  "to": "now"
}

Response Structure:

{
  "results": {
    "A": {
      "frames": [
        {
          "schema": {
            "refId": "A",
            "fields": [
              {"name": "time", "type": "time"},
              {"name": "value", "type": "number"}
            ]
          },
          "data": {
            "values": [
              [1644488152084, 1644488212084],
              [0.95, 0.97]
            ]
          }
        }
      ]
    }
  }
}

---

Health Check

GET /api/datasources/uid/:uid/health

Example Response (Success):

{
  "status": "OK",
  "message": "Successfully connected to Prometheus"
}

Example Response (Error):

{
  "status": "ERROR",
  "message": "Post \"http://prometheus:9090/api/v1/query\": dial tcp: connection refused"
}

---

Data Source Resources

Access data source-specific resources (metrics, dimensions, etc.).

GET /api/datasources/uid/:uid/resources/:resource

CloudWatch Dimension Keys Example

GET /api/datasources/uid/cloudwatch-uid/resources/dimension-keys?region=us-east-1&namespace=AWS/EC2

Prometheus Label Values Example

GET /api/datasources/uid/prometheus-uid/resources/api/v1/label/__name__/values

---

Common Data Source Types

Folders API Reference

Complete reference for Grafana Folder HTTP API endpoints.

Table of Contents

• List Folders
• Get Folder
• Create Folder
• Update Folder
• Delete Folder
• Move Folder
• Folder Permissions

---

List Folders

GET /api/folders

Query Parameters:

Example Response:

[
  {
    "id": 1,
    "uid": "nErXDvCkzz",
    "title": "Operations",
    "url": "/dashboards/f/nErXDvCkzz/operations",
    "hasAcl": false,
    "canSave": true,
    "canEdit": true,
    "canAdmin": true,
    "canDelete": true,
    "createdBy": "admin",
    "created": "2023-01-15T10:30:00Z",
    "updatedBy": "admin",
    "updated": "2024-06-20T14:22:00Z",
    "version": 1
  }
]

---

Get Folder

By UID

GET /api/folders/:uid

By ID (Deprecated)

GET /api/folders/id/:id

Example Response:

{
  "id": 1,
  "uid": "nErXDvCkzz",
  "title": "Operations",
  "url": "/dashboards/f/nErXDvCkzz/operations",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "canDelete": true,
  "createdBy": "admin",
  "created": "2023-01-15T10:30:00Z",
  "updatedBy": "admin",
  "updated": "2024-06-20T14:22:00Z",
  "version": 3,
  "parentUid": ""
}

---

Create Folder

POST /api/folders

Request Body:

{
  "uid": "my-folder-uid",
  "title": "My New Folder",
  "parentUid": "parent-folder-uid"
}

Fields:

Example Response:

{
  "id": 5,
  "uid": "my-folder-uid",
  "title": "My New Folder",
  "url": "/dashboards/f/my-folder-uid/my-new-folder",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "canDelete": true,
  "createdBy": "admin",
  "created": "2024-06-20T14:22:00Z",
  "updatedBy": "admin",
  "updated": "2024-06-20T14:22:00Z",
  "version": 1,
  "parentUid": "parent-folder-uid"
}

---

Update Folder

PUT /api/folders/:uid

Request Body:

{
  "title": "Updated Folder Title",
  "version": 1,
  "overwrite": false
}

Fields:

Error Response (Version Mismatch):

{
  "message": "The folder has been changed by someone else",
  "status": "version-mismatch"
}

---

Delete Folder

DELETE /api/folders/:uid

Query Parameters:

Warning: Deleting a folder also deletes all dashboards inside it. This operation cannot be undone.

Example Request:

curl -X DELETE -H "Authorization: Bearer <TOKEN>" \
  "https://grafana.example.com/api/folders/nErXDvCkzz?forceDeleteRules=true"

Example Response:

{
  "title": "Operations",
  "message": "Folder Operations deleted",
  "id": 1
}

---

Move Folder

POST /api/folders/:uid/move

Note: Only available when nested folders are enabled.

Request Body:

{
  "parentUid": "new-parent-folder-uid"
}

Use empty string or omit parentUid to move to root level.

---

Folder Permissions

Get Folder Permissions

GET /api/folders/:uid/permissions

Example Response:

[
  {
    "id": 1,
    "folderId": 1,
    "created": "2023-01-15T10:30:00Z",
    "updated": "2024-06-20T14:22:00Z",
    "userId": 0,
    "userLogin": "",
    "userEmail": "",
    "teamId": 0,
    "team": "",
    "role": "Viewer",
    "permission": 1,
    "permissionName": "View",
    "uid": "nErXDvCkzz",
    "title": "Operations",
    "slug": "operations",
    "isFolder": true,
    "url": "/dashboards/f/nErXDvCkzz/operations",
    "inherited": false
  }
]

Update Folder Permissions

POST /api/folders/:uid/permissions

Request Body:

{
  "items": [
    {"role": "Viewer", "permission": 1},
    {"role": "Editor", "permission": 2},
    {"teamId": 1, "permission": 1},
    {"userId": 11, "permission": 4}
  ]
}

Permission Levels:

---

Search Folders and Dashboards

GET /api/search

Query Parameters for Folder Search:

Example:

curl -H "Authorization: Bearer <TOKEN>" \
  "https://grafana.example.com/api/search?type=dash-folder&query=prod"

---

New Folder API (v1beta1)

Grafana is transitioning to a new Kubernetes-style API structure.

List Folders (New API)

GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders

Get Folder (New API)

GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders/:uid

Create Folder (New API)

POST /apis/folder.grafana.app/v1beta1/namespaces/default/folders

Request Body:

{
  "metadata": {
    "name": "my-folder-uid",
    "annotations": {
      "grafana.app/folder": "parent-folder-uid"
    }
  },
  "spec": {
    "title": "My New Folder"
  }
}

Response:

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1beta1",
  "metadata": {
    "name": "my-folder-uid",
    "namespace": "default",
    "uid": "...",
    "resourceVersion": "...",
    "creationTimestamp": "2024-06-20T14:22:00Z",
    "annotations": {
      "grafana.app/folder": "parent-folder-uid",
      "grafana.app/createdBy": "admin",
      "grafana.app/updatedBy": "admin",
      "grafana.app/updatedTimestamp": "2024-06-20T14:22:00Z"
    }
  },
  "spec": {
    "title": "My New Folder"
  }
}

Users & Teams API Reference

Complete reference for Grafana User, Team, and Service Account HTTP API endpoints.

Table of Contents

• Current User
• Users (Admin)
• Teams
• Team Members
• Service Accounts
• Service Account Tokens
• Organizations
• Organization Users

---

Current User

Get Current User

GET /api/user

Example Response:

{
  "id": 1,
  "email": "admin@example.com",
  "name": "Admin User",
  "login": "admin",
  "theme": "dark",
  "orgId": 1,
  "isGrafanaAdmin": true,
  "isDisabled": false,
  "isExternal": false,
  "authLabels": [],
  "updatedAt": "2024-06-20T14:22:00Z",
  "createdAt": "2023-01-15T10:30:00Z",
  "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
}

Update Current User

PUT /api/user

{
  "name": "New Name",
  "email": "newemail@example.com",
  "login": "newlogin",
  "theme": "light"
}

Get Current User Organizations

GET /api/user/orgs

Get Current User Teams

GET /api/user/teams

Star/Unstar Dashboard

POST /api/user/stars/dashboard/uid/:dashboardUID
DELETE /api/user/stars/dashboard/uid/:dashboardUID

Change Active Organization

POST /api/user/using/:orgId

---

Users (Admin)

Requires Grafana Admin permission.

Search Users

GET /api/users/search

Query Parameters:

Example Response:

{
  "totalCount": 2,
  "users": [
    {
      "id": 1,
      "name": "Admin User",
      "login": "admin",
      "email": "admin@example.com",
      "isAdmin": true,
      "isDisabled": false,
      "lastSeenAt": "2024-06-20T14:22:00Z",
      "lastSeenAtAge": "2m",
      "authLabels": ["OAuth"]
    }
  ],
  "page": 1,
  "perPage": 10
}

Get User by ID

GET /api/users/:id

Create User

POST /api/admin/users

{
  "name": "New User",
  "email": "newuser@example.com",
  "login": "newuser",
  "password": "password123",
  "OrgId": 1
}

Update User

PUT /api/users/:id

{
  "name": "Updated Name",
  "email": "updated@example.com",
  "login": "updatedlogin",
  "theme": "dark"
}

Delete User

DELETE /api/admin/users/:id

Update User Permissions

PUT /api/admin/users/:id/permissions

{
  "isGrafanaAdmin": true
}

Disable/Enable User

POST /api/admin/users/:id/disable
POST /api/admin/users/:id/enable

---

Teams

Search Teams

GET /api/teams/search

Query Parameters:

Example Response:

{
  "totalCount": 1,
  "teams": [
    {
      "id": 1,
      "orgId": 1,
      "name": "Platform Team",
      "email": "platform@example.com",
      "avatarUrl": "/avatar/3f49c15916554246daa714b9bd0ee398",
      "memberCount": 5,
      "permission": 0
    }
  ],
  "page": 1,
  "perPage": 1000
}

Get Team by ID

GET /api/teams/:teamId

Create Team

POST /api/teams

{
  "name": "DevOps Team",
  "email": "devops@example.com"
}

Update Team

PUT /api/teams/:teamId

{
  "name": "Updated Team Name",
  "email": "newemail@example.com"
}

Delete Team

DELETE /api/teams/:teamId

---

Team Members

Get Team Members

GET /api/teams/:teamId/members

Example Response:

[
  {
    "orgId": 1,
    "teamId": 1,
    "userId": 2,
    "email": "user@example.com",
    "name": "User Name",
    "login": "username",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
    "labels": [],
    "permission": 0
  }
]

Add Team Member

POST /api/teams/:teamId/members

{
  "userId": 5
}

Remove Team Member

DELETE /api/teams/:teamId/members/:userId

Update Team Member Permission

PUT /api/teams/:teamId/members/:userId

{
  "permission": 4
}

Permission Values:

• 0: Member
• 4: Admin

---

Service Accounts

Search Service Accounts

GET /api/serviceaccounts/search

Query Parameters:

Example Response:

{
  "totalCount": 1,
  "serviceAccounts": [
    {
      "id": 1,
      "name": "automation-sa",
      "login": "sa-automation-sa",
      "orgId": 1,
      "isDisabled": false,
      "role": "Editor",
      "tokens": 2,
      "avatarUrl": "/avatar/85ec38023d90823d3e5b43ef35646af9"
    }
  ],
  "page": 1,
  "perPage": 10
}

Get Service Account by ID

GET /api/serviceaccounts/:id

Create Service Account

POST /api/serviceaccounts

{
  "name": "automation-sa",
  "role": "Editor",
  "isDisabled": false
}

Roles: Viewer, Editor, Admin

Update Service Account

PATCH /api/serviceaccounts/:id

{
  "name": "new-name",
  "role": "Admin",
  "isDisabled": false
}

Delete Service Account

DELETE /api/serviceaccounts/:id

---

Service Account Tokens

List Tokens

GET /api/serviceaccounts/:id/tokens

Example Response:

[
  {
    "id": 1,
    "name": "token-1",
    "created": "2024-06-20T14:22:00Z",
    "expiration": "2024-12-20T14:22:00Z",
    "secondsUntilExpiration": 15552000,
    "hasExpired": false,
    "lastUsedAt": "2024-06-20T14:22:00Z"
  }
]

Create Token

POST /api/serviceaccounts/:id/tokens

{
  "name": "automation-token",
  "secondsToLive": 86400
}

Use secondsToLive: 0 for non-expiring tokens.

Response:

{
  "id": 2,
  "name": "automation-token",
  "key": "glsa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Important: The key is only shown once. Store it securely.

Delete Token

DELETE /api/serviceaccounts/:id/tokens/:tokenId

---

Organizations

Get Current Organization

GET /api/org

Update Current Organization

PUT /api/org

{
  "name": "New Org Name"
}

List Organizations (Admin)

GET /api/orgs

Create Organization (Admin)

POST /api/orgs

{
  "name": "New Organization"
}

Get Organization by ID (Admin)

GET /api/orgs/:orgId

Update Organization (Admin)

PUT /api/orgs/:orgId

Delete Organization (Admin)

DELETE /api/orgs/:orgId

---

Organization Users

Get Current Org Users

GET /api/org/users

Example Response:

[
  {
    "orgId": 1,
    "userId": 1,
    "email": "admin@example.com",
    "name": "Admin",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
    "login": "admin",
    "role": "Admin",
    "lastSeenAt": "2024-06-20T14:22:00Z",
    "lastSeenAtAge": "2m"
  }
]

Add User to Current Org

POST /api/org/users

{
  "loginOrEmail": "user@example.com",
  "role": "Viewer"
}

Update User Role in Current Org

PATCH /api/org/users/:userId

{
  "role": "Editor"
}

Remove User from Current Org

DELETE /api/org/users/:userId

Get Org Users (Admin)

GET /api/orgs/:orgId/users

Add User to Org (Admin)

POST /api/orgs/:orgId/users

{
  "loginOrEmail": "user@example.com",
  "role": "Viewer"
}

Update User Role in Org (Admin)

PATCH /api/orgs/:orgId/users/:userId

Remove User from Org (Admin)

DELETE /api/orgs/:orgId/users/:userId