A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Grafana API is how an app or AI agent works with a Grafana instance: reading and saving dashboards, organizing folders, managing data sources and alert rules, and adding annotations to charts. Access is granted through a service account token, and what each call can do is set by the organization role that token holds, Viewer, Editor, or Admin, plus any fine-grained permissions on top. There is no dated version of the API: it ships with each Grafana release, and alerting is how Grafana pushes a notification out when a rule fires.
How an app or AI agent connects to Grafana determines what it can reach. There are a few routes, each governed by the service account token behind it, the organization role that token carries, and any fine-grained permissions on top.
The HTTP API is served by the Grafana instance itself, so its base URL is the instance address, such as https://play.grafana.org. It is JSON over HTTPS and authenticates with a service account token in an Authorization header.
Grafana publishes a first-party MCP server, grafana/mcp-grafana, that lets an agent call Grafana through the Model Context Protocol. It exposes tools for dashboards, data sources and querying, alerting, annotations, incidents, and more, and authenticates with a Grafana service account token. The source is at github.com/grafana/mcp-grafana under the Apache 2.0 license, and it needs Grafana 9.0 or later.
Grafana has no generic change webhook. Its push route is alerting: an alert rule fires, a notification policy routes it, and a contact point delivers to a receiver such as a webhook URL, email, Slack, or PagerDuty. Provisioned through the alerting API under /api/v1/provisioning.
A service account is created inside one organization and given an organization role, then issued one or more long-lived tokens. Each request sends the token as 'Authorization: Bearer
A Grafana username and password can authenticate API requests directly. The server-administrator endpoints, such as the global Users API and creating organizations, require basic auth as a server admin and cannot be reached by a service account token.
The Grafana API is split into areas an agent can act on, such as dashboards, folders, data sources, alerting, and the people and organizations behind them. Each area has its own methods and its own permission actions, and some grant access to far more than others.
Save and read dashboards by their stable uid, get the home dashboard, and delete a dashboard. A dashboard is one JSON model saved through a single create-or-update endpoint.
List folders, read one by uid, and create, update, or delete a folder. Deleting a folder also removes the dashboards and alerts inside it.
List data sources, read one by uid, and create, update, or delete a data source connection.
Read and provision alert rules, and read and manage contact points and the notification policy tree that routes a firing alert to them.
Find, create, update, and delete annotations, the time-stamped event markers shown on dashboard panels.
Search dashboards and folders by text, tag, and type, returning only those the token can see.
Search and read service accounts, create and update them, delete them, and issue or revoke their long-lived tokens.
Read the current user, search the global user directory, and read a single user by id. The global directory requires a server administrator.
Search and read teams, create, update, and delete a team, and list or change its members.
Read and update the current organization and its members, and, for a server administrator, manage organizations across the instance.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
DashboardsSave and read dashboards by their stable uid, get the home dashboard, and delete a dashboard. A dashboard is one JSON model saved through a single create-or-update endpoint.4 | ||||||
| POST | /api/dashboards/db | Create a new dashboard or overwrite an existing one from a JSON model. | write | dashboards:write | Current | |
One endpoint both creates and updates: omit a uid to create, send a known uid and version to update. A stale version returns 412 unless overwrite is true. Scope narrows to dashboards:uid: Acts ondashboard Permission (capability) dashboards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/dashboards/uid/{uid} | Get a dashboard and its access metadata by uid. | read | dashboards:read | Current | |
Scope can narrow to a single dashboard as dashboards:uid: Acts ondashboard Permission (capability) dashboards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/dashboards/uid/{uid} | Delete the dashboard with the given uid. | write | dashboards:delete | Current | |
Scope can narrow to dashboards:uid: Acts ondashboard Permission (capability) dashboards:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/dashboards/home | Get the home dashboard for the current organization or user. | read | dashboards:read | Current | |
Returns the configured home dashboard, falling back to the built-in default. Acts ondashboard Permission (capability) dashboards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FoldersList folders, read one by uid, and create, update, or delete a folder. Deleting a folder also removes the dashboards and alerts inside it.5 | ||||||
| GET | /api/folders | List the folders the token can view. | read | folders:read | Current | |
Scope folders:* covers all folders; it can narrow to folders:uid: Acts onfolder Permission (capability) folders:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/folders/{uid} | Get a single folder by uid. | read | folders:read | Current | |
Scope can narrow to folders:uid: Acts onfolder Permission (capability) folders:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/folders | Create a new folder. | write | folders:create | Current | |
Creating a folder uses folders:create; later writes to it use folders:write. Acts onfolder Permission (capability) folders:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/folders/{uid} | Update an existing folder identified by uid. | write | folders:write | Current | |
Scope can narrow to folders:uid: Acts onfolder Permission (capability) folders:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/folders/{uid} | Delete a folder along with all dashboards and alerts stored inside it. | write | folders:delete | Current | |
This cascades: deleting the folder removes its dashboards and alert rules too. Scope can narrow to folders:uid: Acts onfolder Permission (capability) folders:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Data sourcesList data sources, read one by uid, and create, update, or delete a data source connection.5 | ||||||
| GET | /api/datasources | List all data sources in the current organization. | read | datasources:read | Current | |
Returns up to 5000 by default. Scope can narrow to datasources:uid: Acts ondata source Permission (capability) datasources:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/datasources/uid/{uid} | Get a single data source by uid. | read | datasources:read | Current | |
Secret fields such as passwords are not returned. Scope can narrow to datasources:uid: Acts ondata source Permission (capability) datasources:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/datasources | Create a new data source connection. | write | datasources:create | Current | |
The request can include credentials for the backend database in secureJsonData. Acts ondata source Permission (capability) datasources:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/datasources/uid/{uid} | Update an existing data source by uid. | write | datasources:write | Current | |
Scope can narrow to datasources:uid: Acts ondata source Permission (capability) datasources:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/datasources/uid/{uid} | Delete a data source by uid. | write | datasources:delete | Current | |
Scope can narrow to datasources:uid: Acts ondata source Permission (capability) datasources:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AlertingRead and provision alert rules, and read and manage contact points and the notification policy tree that routes a firing alert to them.8 | ||||||
| GET | /api/v1/provisioning/alert-rules | Get all provisioned alert rules. | read | alert.provisioning:read | Current | |
Covers the Grafana-managed alerting rules under provisioning. Acts onalert rule Permission (capability) alert.provisioning:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/provisioning/alert-rules/{uid} | Get a single alert rule by uid. | read | alert.provisioning:read | Current | |
Acts onalert rule Permission (capability) alert.provisioning:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/provisioning/alert-rules | Create a new alert rule. | write | alert.provisioning:write | Current | |
A provisioned rule defines the query, condition, and the folder it lives in. Acts onalert rule Permission (capability) alert.provisioning:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/provisioning/alert-rules/{uid} | Update an existing alert rule by uid. | write | alert.provisioning:write | Current | |
Acts onalert rule Permission (capability) alert.provisioning:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/provisioning/alert-rules/{uid} | Delete an alert rule by uid. | write | alert.provisioning:write | Current | |
Acts onalert rule Permission (capability) alert.provisioning:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/provisioning/contact-points | Get all contact points, the receivers a firing alert is sent to. | read | alert.provisioning:read | Current | |
A contact point is the push target, such as a webhook URL, email, Slack, or PagerDuty. Acts oncontact point Permission (capability) alert.provisioning:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/provisioning/contact-points | Create a contact point. | write | alert.provisioning:write | Current | |
This is how an integration registers where a firing alert is delivered. Acts oncontact point Permission (capability) alert.provisioning:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/provisioning/policies | Get the notification policy tree that routes firing alerts to contact points. | read | alert.provisioning:read | Current | |
The policy tree decides which contact point each alert reaches by its labels. Acts onnotification policy Permission (capability) alert.provisioning:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AnnotationsFind, create, update, and delete annotations, the time-stamped event markers shown on dashboard panels.4 | ||||||
| GET | /api/annotations | Find annotations filtered by time range, tags, dashboard, panel, or type. | read | annotations:read | Current | |
Acts onannotation Permission (capability) annotations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/annotations | Create an annotation, optionally scoped to a dashboard and panel. | write | annotations:create | Current | |
An organization annotation uses a different RBAC scope from a dashboard-scoped one. Acts onannotation Permission (capability) annotations:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/annotations/{id} | Update all properties of an annotation by id. | write | annotations:write | Current | |
A PATCH on the same path updates only the fields supplied. Acts onannotation Permission (capability) annotations:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/annotations/{id} | Delete the annotation with the given id. | write | annotations:delete | Current | |
Acts onannotation Permission (capability) annotations:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchSearch dashboards and folders by text, tag, and type, returning only those the token can see.1 | ||||||
| GET | /api/search | Search dashboards and folders by text, tag, and type. | read | dashboards:read | Current | |
Returns only items the token can see. Defaults to 1000 results, caps at 5000, paged by the page parameter. Acts onsearch result Permission (capability) dashboards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Service accountsSearch and read service accounts, create and update them, delete them, and issue or revoke their long-lived tokens.4 | ||||||
| GET | /api/serviceaccounts/search | Search service accounts with paging. | read | serviceaccounts:read | Current | |
Acts onservice account Permission (capability) serviceaccounts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/serviceaccounts | Create a new service account. | write | serviceaccounts:create | Current | |
A service account is the identity behind machine and agent access. Acts onservice account Permission (capability) serviceaccounts:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/serviceaccounts/{id}/tokens | Generate a new long-lived token for a service account. | write | serviceaccounts:write | Current | |
The token is returned once in the key field and cannot be retrieved again. This mints a credential that can call the API. Acts onservice account Permission (capability) serviceaccounts:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/serviceaccounts/{id} | Delete a service account. | write | serviceaccounts:delete | Current | |
Deleting the account revokes every token issued for it. Acts onservice account Permission (capability) serviceaccounts:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the current user, search the global user directory, and read a single user by id. The global directory requires a server administrator.3 | ||||||
| GET | /api/user | Get the currently authenticated user. | read | — | Current | |
Returns the signed-in user behind the credential and needs no special action. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/users | Search the global directory of all users on the instance. | read | users:read | Current | |
This global directory requires a Grafana server administrator and cannot be reached by a service account, which is scoped to one organization. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/users/{id} | Get a single user by id from the global directory. | read | users:read | Current | |
Requires a server administrator, as with the global user search. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsSearch and read teams, create, update, and delete a team, and list or change its members.3 | ||||||
| GET | /api/teams/search | Search teams with paging and filtering. | read | teams:read | Current | |
Acts onteam Permission (capability) teams:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/teams | Create a new team. | write | teams:create | Current | |
Acts onteam Permission (capability) teams:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/teams/{teamId}/members | Add a user to a team. | write | teams.permissions:write | Current | |
Managing membership uses the teams.permissions actions, distinct from teams:write on the team itself. Acts onteam Permission (capability) teams.permissions:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsRead and update the current organization and its members, and, for a server administrator, manage organizations across the instance.4 | ||||||
| GET | /api/org | Get the current organization the token belongs to. | read | orgs:read | Current | |
Acts onorganization Permission (capability) orgs:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/org | Update the current organization's details. | write | orgs:write | Current | |
Acts onorganization Permission (capability) orgs:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/org/users | List the users in the current organization. | read | org.users:read | Current | |
Org membership uses the org.users actions, separate from the global users actions. Acts onorganization Permission (capability) org.users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/org/users | Add an existing global user to the current organization. | write | org.users:add | Current | |
Acts onorganization Permission (capability) org.users:addVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Grafana does not push events to a generic webhook for API changes. Its push mechanism is alerting: a contact point sends a notification to a receiver, such as a webhook URL, email, Slack, or PagerDuty, when an alert rule fires.
| Event | What it signals | Triggered by |
|---|
Grafana itself sets no fixed request quota on the HTTP API. How fast and how much an app or AI agent can call depends on the deployment, since a self-hosted instance, a reverse proxy, or Grafana Cloud each apply their own limits.
Grafana does not document a fixed request-per-minute quota on its HTTP API. How fast an app or AI agent can call is set by the deployment rather than the API: a self-hosted instance is bounded by its own capacity, an operator may put a reverse proxy or gateway in front that enforces limits and returns 429 Too Many Requests when exceeded, and Grafana Cloud applies its own platform limits. Treat throughput as deployment-dependent, back off on a 429, and avoid tight polling loops against a shared instance.
List endpoints that can return many rows use page-based pagination through a page parameter that starts at 1 and a perpage or limit parameter for page size. The dashboard and folder search at /api/search defaults to 1000 results per page and caps at 5000, and the data source list returns up to 5000 by default. Smaller, fixed collections are returned in full without paging.
Requests and responses are JSON. A dashboard uid is at most 40 characters. There is no single documented maximum body size across the API; a very large dashboard JSON model is the main case to watch, and an operator's reverse proxy may impose its own request-size ceiling.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request body or parameters are malformed or fail validation, such as a dashboard JSON model that is invalid or a missing required field. | Correct the request body or parameters against the endpoint's documented shape and resend. |
| 401 | Unauthorized | Authentication is missing or invalid: no token, an expired or revoked service account token, or wrong basic-auth credentials. | Send a valid service account token in the Authorization header, or correct the username and password. |
| 403 | Forbidden | The caller is authenticated but its role or permissions do not allow the action, for example an Editor token trying to manage organization users, or a service account reaching a server-administrator endpoint. | Grant the service account the required role or RBAC action, or use a server-administrator credential where the endpoint demands one. |
| 404 | Not Found | The resource does not exist, such as a dashboard, folder, data source, or alert rule uid that is unknown in this organization. | Confirm the uid or id and that it belongs to the organization the token is scoped to. |
| 409 | Conflict | The request conflicts with the current state, such as creating a resource whose name or uid already exists. | Use a different name or uid, or update the existing resource instead of creating a new one. |
| 412 | Precondition Failed | A dashboard save lost a version race: the stored version is newer than the one being saved, or another dashboard already has the same title in the folder. | Re-read the current dashboard, reapply the change on the latest version, and save again, or set overwrite to true to force the save. |
| 429 | Too Many Requests | A rate limit was hit. Grafana itself sets no fixed quota, so a 429 comes from the deployment, such as a reverse proxy in front of the instance or a Grafana Cloud platform limit. | Back off and retry after a delay, and reduce polling against a shared instance. |
The Grafana HTTP API has no dated version string. It ships with each Grafana release, so the API an instance exposes tracks the Grafana version it runs, and changes arrive through the Grafana release notes.
The Grafana HTTP API has no dated version string. It is part of Grafana and changes with each release, so the methods an instance exposes track the Grafana version it runs. Authentication is by service account token. The entries below are notable dated changes from the Grafana release notes, newest first.
Grafana 10 made service accounts the recommended way to authenticate to the API, with API keys marked for removal. A service account holds an organization role and issues long-lived tokens, and existing API keys can be migrated to service account tokens. Released 22 May 2023.
An integration pins to a Grafana version by the instance it points at, and moves up when that instance is upgraded.
Grafana changelog ↗Bollard AI sits between a team's AI agents and Grafana. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.