grafana-api

grafana-api is a reusable Node.js SDK for integrating Grafana into internal tools, deployment automation, platform services, and developer workflows.

It is designed for teams that want something more structured than a one-off HTTP wrapper:

• modular src/ layout
• validated configuration
• reusable resource helpers
• consistent request and error handling
• simple extension points for unsupported endpoints

What this package gives developers

• A clean client for dashboards, folders, datasources, alerts, and annotations
• A generic request layer for any Grafana endpoint
• axios transport with configurable timeout and headers
• zod validation for safer client construction
• Operational error objects with status code, response body, and request metadata

Installation

npm install grafana-api

Package structure

grafana-api/
├── index.js
├── src/
│   ├── client.js
│   ├── config.js
│   ├── errors.js
│   ├── http-client.js
│   └── resources/
│       ├── alerts.js
│       ├── annotations.js
│       ├── dashboards.js
│       ├── datasources.js
│       ├── folders.js
│       └── users.js
└── test.js

This layout makes it straightforward to extend the client with more resource modules if your team needs additional Grafana APIs.

Quick start

const GrafanaClient = require('grafana-api');

async function main() {
  const grafana = new GrafanaClient({
    baseUrl: 'https://grafana.internal',
    apiKey: process.env.GRAFANA_API_KEY,
    organizationId: 2,
    timeout: 15000,
    headers: {
      'X-Request-Source': 'deploy-bot',
    },
  });

  const health = await grafana.getHealth();
  console.log(health);

  const dashboards = await grafana.getDashboards({
    query: 'payments',
    type: 'dash-db',
    limit: 10,
  });

  console.log(`Found ${dashboards.length} dashboards`);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Environment-based setup

const GrafanaClient = require('grafana-api');

const grafana = GrafanaClient.fromEnv();

Supported environment variables:

• GRAFANA_URL
• GRAFANA_HOST
• GRAFANA_PROTOCOL
• GRAFANA_PORT
• GRAFANA_API_KEY
• GRAFANA_TIMEOUT
• GRAFANA_ORG_ID

Common workflows

Dashboard automation

await grafana.createDashboard(
  {
    id: null,
    uid: 'service-latency',
    title: 'Service Latency',
    panels: [],
    timezone: 'browser',
    schemaVersion: 39,
    version: 0,
  },
  3,
  true,
  'Create dashboard from CI'
);

Folder and datasource bootstrap

await grafana.createFolder({ title: 'Payments' });

await grafana.createDatasource({
  name: 'Payments Prometheus',
  type: 'prometheus',
  url: 'http://prometheus.monitoring:9090',
  access: 'proxy',
  isDefault: false,
});

Alerts and deployment annotations

const alerts = await grafana.getAlerts({ state: 'alerting' });

await grafana.pauseAlert(42, true);

await grafana.createAnnotation({
  text: 'Production deploy',
  tags: ['deploy', 'payments'],
  time: Date.now(),
});

Custom endpoint access

const teams = await grafana.get('teams/search', {
  params: { query: 'platform' },
});

const apiKey = await grafana.post('auth/keys', {
  name: 'ci-key',
  role: 'Editor',
});

API reference

new GrafanaClient(options)

| Option | Required | Default | Description | | --- | --- | --- | --- | | apiKey | Yes | — | Grafana service account token | | baseUrl | No | — | Full Grafana URL such as https://grafana.internal | | host | No | — | Hostname when baseUrl is not supplied | | protocol | No | 'http' | Used with host | | port | No | 3000 | Used with host | | organizationId | No | null | Sent as X-Grafana-Org-Id | | timeout | No | 10000 | Request timeout in milliseconds | | headers | No | {} | Default headers merged into each request | | userAgent | No | grafana-api/1.1.0 | Custom user agent |

Generic methods

• request(method, path, options?)
• get(path, options?)
• post(path, data, options?)
• put(path, data, options?)
• patch(path, data, options?)
• delete(path, options?)

options supports:

• params
• data
• headers
• timeout

Resource methods

• getHealth()
• getCurrentUser()
• searchDashboards(params?)
• getDashboards(params?)
• getDashboard(uid)
• createDashboard(dashboard, folderId?, overwrite?, message?)
• updateDashboard(dashboard, folderId?, overwrite?, message?)
• deleteDashboard(uid)
• getFolders(params?)
• getFolder(id)
• createFolder(folder)
• deleteFolder(id)
• getDatasources()
• getDatasource(id)
• createDatasource(config)
• updateDatasource(id, config)
• deleteDatasource(id)
• getAlerts(params?)
• pauseAlert(id, paused?)
• getAnnotations(params?)
• createAnnotation(annotation)
• deleteAnnotation(id)

Error handling

Failed requests throw GrafanaApiError.

const { GrafanaApiError } = require('grafana-api');

try {
  await grafana.getDashboard('missing-dashboard');
} catch (error) {
  if (error instanceof GrafanaApiError) {
    console.error(error.statusCode);
    console.error(error.body);
    console.error(error.request);
  }
}

License

This package is licensed under the MIT License. See LICENSE.