Grafana

---
name: grafana
description: "Grafana API integration with managed authentication. Manage dashboards, data sources, folders, annotations, alerts, and teams.\n Use this skill when users want to interact with Grafana for monitoring, visualization, and observability.\n For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway)."
---

# Grafana

Access Grafana dashboards, data sources, folders, annotations, and alerts via managed API authentication.

## Quick Start

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/grafana/api/search?type=dash-db')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

## Base URL

```
https://gateway.maton.ai/grafana/{native-api-path}
```

The gateway proxies requests to your Grafana instance and automatically injects authentication.

## Authentication

All requests require the Maton API key:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Grafana connections at `https://ctrl.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=grafana&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'grafana'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

Open the returned `url` in a browser to complete authentication. You'll need to provide your Grafana service account token.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

---

## API Reference

### Organization & User

#### Get Current Organization

```bash
GET /grafana/api/org
```

**Response:**
```json
{
  "id": 1,
  "name": "Main Org.",
  "address": {
    "address1": "",
    "address2": "",
    "city": "",
    "zipCode": "",
    "state": "",
    "country": ""
  }
}
```

#### Get Current User

```bash
GET /grafana/api/user
```

**Response:**
```json
{
  "id": 1,
  "uid": "abc123",
  "email": "user@example.com",
  "name": "User Name",
  "login": "user",
  "orgId": 1,
  "isGrafanaAdmin": false
}
```

---

### Dashboards

#### Search Dashboards

```bash
GET /grafana/api/search?type=dash-db
```

**Query Parameters:**
- `type` - `dash-db` for dashboards, `dash-folder` for folders
- `query` - Search query string
- `tag` - Filter by tag
- `folderIds` - Filter by folder IDs
- `limit` - Max results (default 1000)

**Response:**
```json
[
  {
    "id": 1,
    "uid": "abc123",
    "title": "My Dashboard",
    "uri": "db/my-dashboard",
    "url": "/d/abc123/my-dashboard",
    "type": "dash-db",
    "tags": ["production"],
    "isStarred": false
  }
]
```

#### Get Dashboard by UID

```bash
GET /grafana/api/dashboards/uid/{uid}
```

**Response:**
```json
{
  "meta": {
    "type": "db",
    "canSave": true,
    "canEdit": true,
    "canAdmin": true,
    "canStar": true,
    "slug": "my-dashboard",
    "url": "/d/abc123/my-dashboard",
    "expires": "0001-01-01T00:00:00Z",
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-02T00:00:00Z",
    "version": 1
  },
  "dashboard": {
    "id": 1,
    "uid": "abc123",
    "title": "My Dashboard",
    "tags": ["production"],
    "panels": [...],
    "schemaVersion": 30,
    "version": 1
  }
}
```

#### Create/Update Dashboard

```bash
POST /grafana/api/dashboards/db
Content-Type: application/json

{
  "dashboard": {
    "title": "New Dashboard",
    "panels": [],
    "schemaVersion": 30,
    "version": 0
  },
  "folderUid": "optional-folder-uid",
  "overwrite": false
}
```

**Response:**
```json
{
  "id": 1,
  "uid": "abc123",
  "url": "/d/abc123/new-dashboard",
  "status": "success",
  "version": 1,
  "slug": "new-dashboard"
}
```

#### Delete Dashboard

```bash
DELETE /grafana/api/dashboards/uid/{uid}
```

**Response:**
```json
{
  "title": "My Dashboard",
  "message": "Dashboard My Dashboard deleted",
  "id": 1
}
```

#### Get Home Dashboard

```bash
GET /grafana/api/dashboards/home
```

---

### Folders

#### List Folders

```bash
GET /grafana/api/folders
```

**Response:**
```json
[
  {
    "id": 1,
    "uid": "folder123",
    "title": "My Folder",
    "url": "/dashboards/f/folder123/my-folder",
    "hasAcl": false,
    "canSave": true,
    "canEdit": true,
    "canAdmin": true
  }
]
```

#### Get Folder by UID

```bash
GET /grafana/api/folders/{uid}
```

#### Create Folder

```bash
POST /grafana/api/folders
Content-Type: application/json

{
  "title": "New Folder"
}
```

**Response:**
```json
{
  "id": 1,
  "uid": "folder123",
  "title": "New Folder",
  "url": "/dashboards/f/folder123/new-folder",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "version": 1
}
```

#### Update Folder

```bash
PUT /grafana/api/folders/{uid}
Content-Type: application/json

{
  "title": "Updated Folder Name",
  "version": 1
}
```

#### Delete Folder

```bash
DELETE /grafana/api/folders/{uid}
```

---

### Data Sources

#### List Data Sources

```bash
GET /grafana/api/datasources
```

**Response:**
```json
[
  {
    "id": 1,
    "uid": "ds123",
    "orgId": 1,
    "name": "Prometheus",
    "type": "prometheus",
    "access": "proxy",
    "url": "http://prometheus:9090",
    "isDefault": true,
    "readOnly": false
  }
]
```

#### Get Data Source by ID

```bash
GET /grafana/api/datasources/{id}
```

#### Get Data Source by UID

```bash
GET /grafana/api/datasources/uid/{uid}
```

#### Get Data Source by Name

```bash
GET /grafana/api/datasources/name/{name}
```

#### Create Data Source

```bash
POST /grafana/api/datasources
Content-Type: application/json

{
  "name": "New Prometheus",
  "type": "prometheus",
  "url": "http://prometheus:9090",
  "access": "proxy",
  "isDefault": false
}
```

#### Update Data Source

```bash
PUT /grafana/api/datasources/{id}
Content-Type: application/json

{
  "name": "Updated Prometheus",
  "type": "prometheus",
  "url": "http://prometheus:9090",
  "access": "proxy"
}
```

#### Delete Data Source

```bash
DELETE /grafana/api/datasources/{id}
```

---

### Annotations

#### List Annotations

```bash
GET /grafana/api/annotations
```

**Query Parameters:**
- `from` - Epoch timestamp (ms)
- `to` - Epoch timestamp (ms)
- `dashboardId` - Filter by dashboard ID
- `dashboardUID` - Filter by dashboard UID
- `panelId` - Filter by panel ID
- `tags` - Filter by tags (comma-separated)
- `limit` - Max results

#### Create Annotation

```bash
POST /grafana/api/annotations
Content-Type: application/json

{
  "dashboardUID": "abc123",
  "time": 1609459200000,
  "text": "Deployment completed",
  "tags": ["deployment", "production"]
}
```

**Response:**
```json
{
  "message": "Annotation added",
  "id": 1
}
```

#### Update Annotation

```bash
PUT /grafana/api/annotations/{id}
Content-Type: application/json

{
  "text": "Updated annotation text",
  "tags": ["updated"]
}
```

#### Delete Annotation

```bash
DELETE /grafana/api/annotations/{id}
```

---

### Teams

#### Search Teams

```bash
GET /grafana/api/teams/search
```

**Query Parameters:**
- `query` - Search query
- `page` - Page number
- `perpage` - Results per page

**Response:**
```json
{
  "totalCount": 1,
  "teams": [
    {
      "id": 1,
      "orgId": 1,
      "name": "Engineering",
      "email": "engineering@example.com",
      "memberCount": 5
    }
  ],
  "page": 1,
  "perPage": 1000
}
```

#### Get Team by ID

```bash
GET /grafana/api/teams/{id}
```

#### Create Team

```bash
POST /grafana/api/teams
Content-Type: application/json

{
  "name": "New Team",
  "email": "team@example.com"
}
```

#### Update Team

```bash
PUT /grafana/api/teams/{id}
Content-Type: application/json

{
  "name": "Updated Team Name"
}
```

#### Delete Team

```bash
DELETE /grafana/api/teams/{id}
```

---

### Alert Rules (Provisioning API)

#### List Alert Rules

```bash
GET /grafana/api/v1/provisioning/alert-rules
```

#### Get Alert Rule

```bash
GET /grafana/api/v1/provisioning/alert-rules/{uid}
```

#### List Alert Rules by Folder

```bash
GET /grafana/api/ruler/grafana/api/v1/rules
```

---

### Service Accounts

#### Search Service Accounts

```bash
GET /grafana/api/serviceaccounts/search
```

**Response:**
```json
{
  "totalCount": 1,
  "serviceAccounts": [
    {
      "id": 1,
      "name": "api-service",
      "login": "sa-api-service",
      "orgId": 1,
      "isDisabled": false,
      "role": "Editor"
    }
  ],
  "page": 1,
  "perPage": 1000
}
```

---

### Plugins

#### List Plugins

```bash
GET /grafana/api/plugins
```

**Response:**
```json
[
  {
    "name": "Prometheus",
    "type": "datasource",
    "id": "prometheus",
    "enabled": true,
    "pinned": false
  }
]
```

---

## Code Examples

### JavaScript

```javascript
const response = await fetch('https://gateway.maton.ai/grafana/api/search?type=dash-db', {
  headers: {
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`
  }
});
const dashboards = await response.json();
console.log(dashboards);
```

### Python

```python
import os
import requests

response = requests.get(
    'https://gateway.maton.ai/grafana/api/search?type=dash-db',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'
    }
)
print(response.json())
```

---

## Notes

- Dashboard UIDs are unique identifiers used in most operations
- Use `/api/search?type=dash-db` to find dashboard UIDs
- Folder operations require folder UIDs
- Some admin operations (list all users, orgs) require elevated permissions
- Alert rules use the provisioning API (`/api/v1/provisioning/...`)
- Annotations require epoch timestamps in milliseconds

## Error Handling

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 400 | Invalid request |
| 401 | Invalid or missing authentication |
| 403 | Permission denied |
| 404 | Resource not found |
| 409 | Conflict (e.g., duplicate name) |
| 412 | Precondition failed (version mismatch) |
| 422 | Unprocessable entity |

## Resources

- [Grafana HTTP API Documentation](https://grafana.com/docs/grafana/latest/developers/http_api/)
- [Dashboard API](https://grafana.com/docs/grafana/latest/developers/http_api/dashboard/)
- [Folder API](https://grafana.com/docs/grafana/latest/developers/http_api/folder/)
- [Data Source API](https://grafana.com/docs/grafana/latest/developers/http_api/data_source/)
- [Maton Community](https://discord.com/invite/dBfFAcefs2)
- [Maton Support](mailto:support@maton.ai)