HTTP API on Grafana Labs

API Tutorial: Create API tokens and dashboards for an organization

Sat, 04 Apr 2026 12:26:57 +0000

Create API tokens and dashboards for an organization

Use the Grafana API to set up new Grafana organizations or to add dynamically generated dashboards to an existing organization.

Authentication

There are two authentication methods to access the API:

Basic authentication: A Grafana Admin user can access some parts of the Grafana API through basic authentication.
API Tokens: All organization actions are accessed through an API Token. An API Token is associated with an organization. It can be used to create dashboards and other components specific for that organization.

How to create a new organization and an API Token

The task is to create a new organization and then add a Token that can be used by other users. In the examples below which use basic auth, the user is admin and the password is admin.

Create the org. Here is an example using curl:
Bash
```
curl -X POST -H "Content-Type: application/json" -d '{"name":"apiorg"}' http://admin:admin@localhost:3000/api/orgs
```
This should return a response: {"message":"Organization created","orgId":6}. Use the orgId for the next steps.

Optional step. If the org was created previously and/or step 3 fails then first add your Admin user to the org:

curl -X POST -H "Content-Type: application/json" -d '{"loginOrEmail":"admin", "role": "Admin"}' http://admin:admin@localhost:3000/api/orgs/<org id of new org>/users

Switch the org context for the Admin user to the new org:

curl -X POST http://admin:admin@localhost:3000/api/user/using/<id of new org>

Create the API token:
Bash
```
curl -X POST -H "Content-Type: application/json" -d '{"name":"apikeycurl", "role": "Admin"}' http://admin:admin@localhost:3000/api/auth/keys
```
This should return a response: {"name":"apikeycurl","key":"eyJrIjoiR0ZXZmt1UFc0OEpIOGN5RWdUalBJTllUTk83VlhtVGwiLCJuIjoiYXBpa2V5Y3VybCIsImlkIjo2fQ=="}.

Save the key returned here in your password manager as it is not possible to fetch again it in the future.

How to add a dashboard

Using the Token that was created in the previous step, you can create a dashboard or carry out other actions without having to switch organizations.

Add a dashboard using the key (or bearer token as it is also called):

curl -X POST --insecure -H "Authorization: Bearer eyJrIjoiR0ZXZmt1UFc0OEpIOGN5RWdUalBJTllUTk83VlhtVGwiLCJuIjoiYXBpa2V5Y3VybCIsImlkIjo2fQ==" -H "Content-Type: application/json" -d '{
  "dashboard": {
    "id": null,
    "title": "Production Overview",
    "tags": [ "templated" ],
    "timezone": "browser",
    "rows": [
      {
      }
    ],
    "schemaVersion": 6,
    "version": 0
  },
  "overwrite": false
}' http://localhost:3000/api/dashboards/db

Note: If you export a dashboard for sharing externally using the Share > Export menu in the Grafana UI, you cannot import that dashboard. Instead, click View JSON and save it to a file or fetch the JSON output through the API.

Admin HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Admin API

The Admin HTTP API does not currently work with an API Token. API Tokens are currently only linked to an organization and an organization role. They cannot be given the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user must have the Grafana Admin permission. (The default admin user is called admin and has permission to use this API.)

If you are running Grafana Enterprise and have Fine-grained access control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required.

Fetch settings

GET /api/admin/settings

Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope
settings:read	settings:* settings:auth.saml: settings:auth.saml:enabled (property level)

Example Request:

GET /api/admin/settings
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "DEFAULT": {
    "app_mode":"production"
  },
  "analytics": {
    "google_analytics_ua_id":"",
    "reporting_enabled":"false"
  },
  "auth.anonymous":{
    "enabled":"true",
    "org_name":"Main Org.",
    "org_role":"Viewer"
  },
  "auth.basic":{
    "enabled":"false"
  },
  "auth.github":{
    "allow_sign_up":"false",
    "allowed_domains":"",
    "allowed_organizations":"",
    "api_url":"https://api.github.com/user",
    "auth_url":"https://github.com/login/oauth/authorize",
    "client_id":"some_id",
    "client_secret":"************",
    "enabled":"false",
    "scopes":"user:email,read:org",
    "team_ids":"",
    "token_url":"https://github.com/login/oauth/access_token"
  },
  "auth.google":{
    "allow_sign_up":"false","allowed_domains":"",
    "api_url":"https://www.googleapis.com/oauth2/v1/userinfo",
    "auth_url":"https://accounts.google.com/o/oauth2/auth",
    "client_id":"some_client_id",
    "client_secret":"************",
    "enabled":"false",
    "scopes":"https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
    "token_url":"https://accounts.google.com/o/oauth2/token"
  },
  "auth.ldap":{
    "config_file":"/etc/grafana/ldap.toml",
    "enabled":"false"
  },
  "auth.proxy":{
    "auto_sign_up":"true",
    "enabled":"false",
    "header_name":"X-WEBAUTH-USER",
    "header_property":"username"
  },
  "dashboards.json":{
    "enabled":"false",
    "path":"/var/lib/grafana/dashboards"
  },
  "database":{
    "host":"127.0.0.1:0000",
    "name":"grafana",
    "password":"************",
    "path":"grafana.db",
    "ssl_mode":"disable",
    "type":"sqlite3",
    "user":"root"
  },
  "emails":{
    "templates_pattern":"emails/*.html, emails/*.txt",
    "welcome_email_on_sign_up":"false",
    "content_types":"text/html"
  },
  "log":{
    "buffer_len":"10000",
    "level":"Info",
    "mode":"file"
  },
  "log.console":{
    "level":""
  },
  "log.file":{
    "daily_rotate":"true",
    "file_name":"",
    "level":"",
    "log_rotate":"true",
    "max_days":"7",
    "max_lines":"1000000",
    "max_lines_shift":"28",
    "max_size_shift":""
  },
  "paths":{
    "data":"/tsdb/grafana",
    "logs":"/logs/apps/grafana"},
    "security":{
    "admin_password":"************",
    "admin_user":"admin",
    "cookie_remember_name":"grafana_remember",
    "cookie_username":"grafana_user",
    "disable_gravatar":"false",
    "login_remember_days":"7",
    "secret_key":"************"
  },
  "server":{
    "cert_file":"",
    "cert_key":"",
    "domain":"mygraf.com",
    "enable_gzip":"false",
    "enforce_domain":"false",
    "http_addr":"127.0.0.1",
    "http_port":"0000",
    "protocol":"http",
    "root_url":"%(protocol)s://%(domain)s:%(http_port)s/",
    "router_logging":"true",
    "data_proxy_logging":"true",
    "static_root_path":"public"
  },
  "session":{
    "cookie_name":"grafana_sess",
    "cookie_secure":"false",
    "gc_interval_time":"",
    "provider":"file",
    "provider_config":"sessions",
    "session_life_time":"86400"
  },
  "smtp":{
    "cert_file":"",
    "enabled":"false",
    "from_address":"admin@grafana.localhost",
    "from_name":"Grafana",
    "ehlo_identity":"dashboard.example.com",
    "host":"localhost:25",
    "key_file":"",
    "password":"************",
    "skip_verify":"false",
    "user":""
  },
  "users":{
    "allow_org_create":"true",
    "allow_sign_up":"false",
    "auto_assign_org":"true",
    "auto_assign_org_role":"Viewer"
  }
}

Update settings

PUT /api/admin/settings

Note: Available in Grafana Enterprise v8.0+.

Updates / removes and reloads database settings. You must provide either updates, removals or both.

This endpoint only supports changes to auth.saml configuration.

Required permissions

See note in the introduction for an explanation.

Action	Scope
settings:write	settings:* settings:auth.saml: settings:auth.saml:enabled (property level)

Example request:

PUT /api/admin/settings
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "updates": {
    "auth.saml": {
      "enabled": "true"
    }
  },
  "removals": {
    "auth.saml": ["single_logout"]
  },
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 32

{
  "message":"Settings updated"
}

Status codes:

200 - OK
400 - Bad Request
401 - Unauthorized
403 - Forbidden
500 - Internal Server Error

Grafana Stats

GET /api/admin/stats

Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope
server.stats:read	n/a

Example Request:

GET /api/admin/stats
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "users":2,
  "orgs":1,
  "dashboards":4,
  "snapshots":2,
  "tags":6,
  "datasources":1,
  "playlists":1,
  "stars":2,
  "alerts":2,
  "activeUsers":1
}

Grafana Usage Report preview

GET /api/admin/usage-report-preview

Preview usage report to be sent to vendor.

Only works with Basic Authentication (username and password). See introduction for an explanation.

Example Request:

GET /api/admin/usage-report-preview
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
	"version": "8_4_0",
	"metrics": {
		"stats.active_admins.count": 1,
		"stats.active_editors.count": 1,
		"stats.active_sessions.count": 0,
		"stats.active_users.count": 2,
		"stats.active_viewers.count": 0,
		"stats.admins.count": 1,
		"stats.alert_rules.count": 0,
		"stats.alerting.ds.other.count": 0,
		"stats.alerts.count": 5,
		"stats.annotations.count": 6,
		"stats.api_keys.count": 1
  }
}

Global Users

POST /api/admin/users

Create new user. Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope
users:create	n/a

Example Request:

POST /api/admin/users HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "name":"User",
  "email":"user@graf.com",
  "login":"user",
  "password":"userpassword",
  "OrgId": 1
}

Note that OrgId is an optional parameter that can be used to assign a new user to a different organization when auto_assign_org is set to true.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"id":5,"message":"User created"}

Password for User

PUT /api/admin/users/:id/password

Only works with Basic Authentication (username and password). See introduction for an explanation. Change password for a specific user.

Required permissions

See note in the introduction for an explanation.

Action	Scope
users.password:update	global:users:*

Example Request:

PUT /api/admin/users/2/password HTTP/1.1
Accept: application/json
Content-Type: application/json

{"password":"userpassword"}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message": "User password updated"}

Permissions

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

Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope
users.permissions:update	global:users:*

Example Request:

PUT /api/admin/users/2/permissions HTTP/1.1
Accept: application/json
Content-Type: application/json

{"isGrafanaAdmin": true}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message": "User permissions updated"}

Delete global User

DELETE /api/admin/users/:id

Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope
users:delete	global:users:*

Example Request:

DELETE /api/admin/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message": "User deleted"}

Pause all alerts

POST /api/admin/pause-all-alerts

Only works with Basic Authentication (username and password). See introduction for an explanation.

Example Request:

POST /api/admin/pause-all-alerts HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "paused": true
}

JSON Body schema:

paused – If true then all alerts are to be paused, false unpauses all alerts.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "state":   "Paused",
  "message": "alert paused",
  "alertsAffected": 1
}

Auth tokens for User

GET /api/admin/users/:id/auth-tokens

Return a list of all auth tokens (devices) that the user currently have logged in from.

Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope
users.authtoken:list	global:users:*

Example Request:

GET /api/admin/users/1/auth-tokens HTTP/1.1
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 361,
    "isActive": false,
    "clientIp": "127.0.0.1",
    "browser": "Chrome",
    "browserVersion": "72.0",
    "os": "Linux",
    "osVersion": "",
    "device": "Other",
    "createdAt": "2019-03-05T21:22:54+01:00",
    "seenAt": "2019-03-06T19:41:06+01:00"
  },
  {
    "id": 364,
    "isActive": false,
    "clientIp": "127.0.0.1",
    "browser": "Mobile Safari",
    "browserVersion": "11.0",
    "os": "iOS",
    "osVersion": "11.0",
    "device": "iPhone",
    "createdAt": "2019-03-06T19:41:19+01:00",
    "seenAt": "2019-03-06T19:41:21+01:00"
  }
]

Revoke auth token for User

POST /api/admin/users/:id/revoke-auth-token

Revokes the given auth token (device) for the user. User of issued auth token (device) will no longer be logged in and will be required to authenticate again upon next activity.

Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope
users.authtoken:update	global:users:*

Example Request:

POST /api/admin/users/1/revoke-auth-token HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "authTokenId": 364
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "User auth token revoked"
}

Logout User

POST /api/admin/users/:id/logout

Logout user revokes all auth tokens (devices) for the user. User of issued auth tokens (devices) will no longer be logged in and will be required to authenticate again upon next activity.

Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope
users.logout	global:users:*

Example Request:

POST /api/admin/users/1/logout HTTP/1.1
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "User auth token revoked"
}

Reload provisioning configurations

POST /api/admin/provisioning/dashboards/reload

POST /api/admin/provisioning/datasources/reload

POST /api/admin/provisioning/plugins/reload

POST /api/admin/provisioning/notifications/reload

POST /api/admin/provisioning/access-control/reload

Reloads the provisioning config files for specified type and provision entities again. It won’t return until the new provisioned entities are already stored in the database. In case of dashboards, it will stop polling for changes in dashboard files and then restart it with new configurations after returning.

Only works with Basic Authentication (username and password). See introduction for an explanation.

Required permissions

See note in the introduction for an explanation.

Action	Scope	Provision entity
provisioning:reload	provisioners:accesscontrol	accesscontrol
provisioning:reload	provisioners:dashboards	dashboards
provisioning:reload	provisioners:datasources	datasources
provisioning:reload	provisioners:plugins	plugins
provisioning:reload	provisioners:notifications	notifications

Example Request:

POST /api/admin/provisioning/dashboards/reload HTTP/1.1
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "Dashboards config reloaded"
}

Reload LDAP configuration

POST /api/admin/ldap/reload

Reloads the LDAP configuration.

Only works with Basic Authentication (username and password). See introduction for an explanation.

Example Request:

POST /api/admin/ldap/reload HTTP/1.1
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "LDAP config reloaded"
}

Alerting HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Alerting API

Note: This topic is relevant for the legacy dashboard alerts only.

You can find Grafana 8 alerts API specification details here. Also, refer to Grafana 8 alerts documentation for details on how to create and manage new alerts.

You can use the Alerting API to get information about legacy dashboard alerts and their states but this API cannot be used to modify the alert. To create new alerts or modify them you need to update the dashboard JSON that contains the alerts.

Get alerts

GET /api/alerts/

Example Request:

GET /api/alerts HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Querystring Parameters:

These parameters are used as querystring parameters. For example:

/api/alerts?dashboardId=1

dashboardId – Limit response to alerts in specified dashboard(s). You can specify multiple dashboards, e.g. dashboardId=23&dashboardId=35.
panelId – Limit response to alert for a specified panel on a dashboard.
query - Limit response to alerts having a name like this value.
state - Return alerts with one or more of the following alert states: ALL,no_data, paused, alerting, ok, pending. To specify multiple states use the following format: ?state=paused&state=alerting
limit - Limit response to X number of alerts.
folderId – Limit response to alerts of dashboards in specified folder(s). You can specify multiple folders, e.g. folderId=23&folderId=35.
dashboardQuery - Limit response to alerts having a dashboard name like this value.
dashboardTag - Limit response to alerts of dashboards with specified tags. To do an “AND” filtering with multiple tags, specify the tags parameter multiple times e.g. dashboardTag=tag1&dashboardTag=tag2.

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 1,
    "dashboardId": 1,
    "dashboardUId": "ABcdEFghij"
    "dashboardSlug": "sensors",
    "panelId": 1,
    "name": "fire place sensor",
    "state": "alerting",
    "newStateDate": "2018-05-14T05:55:20+02:00",
    "evalDate": "0001-01-01T00:00:00Z",
    "evalData": null,
    "executionError": "",
    "url": "https://grafana.com/dashboard/db/sensors"
  }
]

Get alert by id

GET /api/alerts/:id

Example Request:

GET /api/alerts/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "dashboardId": 1,
  "dashboardUId": "ABcdEFghij"
  "dashboardSlug": "sensors",
  "panelId": 1,
  "name": "fire place sensor",
  "state": "alerting",
  "message": "Someone is trying to break in through the fire place",
  "newStateDate": "2018-05-14T05:55:20+02:00",
  "evalDate": "0001-01-01T00:00:00Z",
  "evalData": "evalMatches": [
    {
      "metric": "movement",
      "tags": {
        "name": "fireplace_chimney"
      },
      "value": 98.765
    }
  ],
  "executionError": "",
  "url": "https://grafana.com/dashboard/db/sensors"
}

Important Note: “evalMatches” data is cached in the db when and only when the state of the alert changes (e.g. transitioning from “ok” to “alerting” state).

If data from one server triggers the alert first and, before that server is seen leaving alerting state, a second server also enters a state that would trigger the alert, the second server will not be visible in “evalMatches” data.

Pause alert by id

POST /api/alerts/:id/pause

Example Request:

POST /api/alerts/1/pause HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "paused": true
}

The :id query parameter is the id of the alert to be paused or unpaused.

JSON Body Schema:

paused – Can be true or false. True to pause an alert. False to unpause an alert.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "alertId": 1,
  "state":   "Paused",
  "message": "alert paused"
}

Pause all alerts

See Admin API.

Alerting Notification Channels HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Alerting Notification Channels API

This page documents the Alerting Notification Channels API.

Identifier (id) vs unique identifier (uid)

The identifier (id) of a notification channel is an auto-incrementing numeric value and is only unique per Grafana install.

The unique identifier (uid) of a notification channel can be used for uniquely identify a notification channel between multiple Grafana installs. It’s automatically generated if not provided when creating a notification channel. The uid allows having consistent URLs for accessing notification channels and when syncing notification channels between multiple Grafana installations, refer to alert notification channel provisioning.

The uid can have a maximum length of 40 characters.

Get all notification channels

Returns all notification channels that the authenticated user has permission to view.

GET /api/alert-notifications

Example request:

GET /api/alert-notifications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 1,
    "uid": "team-a-email-notifier",
    "name": "Team A",
    "type": "email",
    "isDefault": false,
    "sendReminder": false,
    "disableResolveMessage": false,
    "settings": {
      "addresses": "dev@grafana.com"
    },
    "created": "2018-04-23T14:44:09+02:00",
    "updated": "2018-08-20T15:47:49+02:00"
  }
]

Get all notification channels (lookup)

Returns all notification channels, but with less detailed information. Accessible by any authenticated user and is mainly used by providing alert notification channels in Grafana UI when configuring alert rule.

GET /api/alert-notifications/lookup

Example request:

GET /api/alert-notifications/lookup HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 1,
    "uid": "000000001",
    "name": "Test",
    "type": "email",
    "isDefault": false
  },
  {
    "id": 2,
    "uid": "000000002",
    "name": "Slack",
    "type": "slack",
    "isDefault": false
  }
]

Get notification channel by uid

GET /api/alert-notifications/uid/:uid

Returns the notification channel given the notification channel uid.

Example request:

GET /api/alert-notifications/uid/team-a-email-notifier HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "team-a-email-notifier",
  "name": "Team A",
  "type": "email",
  "isDefault": false,
  "sendReminder": false,
  "disableResolveMessage": false,
  "settings": {
    "addresses": "dev@grafana.com"
  },
  "created": "2018-04-23T14:44:09+02:00",
  "updated": "2018-08-20T15:47:49+02:00"
}

Get notification channel by id

GET /api/alert-notifications/:id

Returns the notification channel given the notification channel id.

Example request:

GET /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "team-a-email-notifier",
  "name": "Team A",
  "type": "email",
  "isDefault": false,
  "sendReminder": false,
  "disableResolveMessage": false,
  "settings": {
    "addresses": "dev@grafana.com"
  },
  "created": "2018-04-23T14:44:09+02:00",
  "updated": "2018-08-20T15:47:49+02:00"
}

Create notification channel

You can find the full list of supported notifiers on the alert notifiers page.

POST /api/alert-notifications

Example request:

POST /api/alert-notifications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "uid": "new-alert-notification", // optional
  "name": "new alert notification",  //Required
  "type":  "email", //Required
  "isDefault": false,
  "sendReminder": false,
  "settings": {
    "addresses": "dev@grafana.com"
  }
}

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "new-alert-notification",
  "name": "new alert notification",
  "type": "email",
  "isDefault": false,
  "sendReminder": false,
  "settings": {
    "addresses": "dev@grafana.com"
  },
  "created": "2018-04-23T14:44:09+02:00",
  "updated": "2018-08-20T15:47:49+02:00"
}

Update notification channel by uid

PUT /api/alert-notifications/uid/:uid

Updates an existing notification channel identified by uid.

Example request:

PUT /api/alert-notifications/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "uid": "new-alert-notification", // optional
  "name": "new alert notification",  //Required
  "type":  "email", //Required
  "isDefault": false,
  "sendReminder": true,
  "frequency": "15m",
  "settings": {
    "addresses": "dev@grafana.com"
  }
}

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "new-alert-notification",
  "name": "new alert notification",
  "type": "email",
  "isDefault": false,
  "sendReminder": true,
  "frequency": "15m",
  "settings": {
    "addresses": "dev@grafana.com"
  },
  "created": "2017-01-01 12:34",
  "updated": "2017-01-01 12:34"
}

Update notification channel by id

PUT /api/alert-notifications/:id

Updates an existing notification channel identified by id.

Example request:

PUT /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "id": 1,
  "uid": "new-alert-notification", // optional
  "name": "new alert notification",  //Required
  "type":  "email", //Required
  "isDefault": false,
  "sendReminder": true,
  "frequency": "15m",
  "settings": {
    "addresses": "dev@grafana.com"
  }
}

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "new-alert-notification",
  "name": "new alert notification",
  "type": "email",
  "isDefault": false,
  "sendReminder": true,
  "frequency": "15m",
  "settings": {
    "addresses": "dev@grafana.com"
  },
  "created": "2017-01-01 12:34",
  "updated": "2017-01-01 12:34"
}

Delete alert notification by uid

DELETE /api/alert-notifications/uid/:uid

Deletes an existing notification channel identified by uid.

Example request:

DELETE /api/alert-notifications/uid/team-a-email-notifier HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "Notification deleted"
}

Delete alert notification by id

DELETE /api/alert-notifications/:id

Deletes an existing notification channel identified by id.

Example request:

DELETE /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "Notification deleted"
}

Test notification channel

Sends a test notification message for the given notification channel type and settings. You can find the full list of supported notifiers at the alert notifiers page.

POST /api/alert-notifications/test

Example request:

POST /api/alert-notifications/test HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "type":  "email",
  "settings": {
    "addresses": "dev@grafana.com"
  }
}

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "Test notification sent"
}

Annotations HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Annotations resources / actions

This is the API documentation for the new Grafana Annotations feature released in Grafana 4.6. Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be global annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel.

Find Annotations

GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100

Example Request:

GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Query Parameters:

from: epoch datetime in milliseconds. Optional.
to: epoch datetime in milliseconds. Optional.
limit: number. Optional - default is 100. Max limit for results returned.
alertId: number. Optional. Find annotations for a specified alert.
dashboardId: number. Optional. Find annotations that are scoped to a specific dashboard
panelId: number. Optional. Find annotations that are scoped to a specific panel
userId: number. Optional. Find annotations created by a specific user
type: string. Optional. alert|annotation Return alerts or user created annotations
tags: string. Optional. Use this to filter global annotations. Global annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel. To do an “AND” filtering with multiple tags, specify the tags parameter multiple times e.g. tags=tag1&tags=tag2.

Example Response:

HTTP/1.1 200
Content-Type: application/json
[
    {
        "id": 1124,
        "alertId": 0,
        "dashboardId": 468,
        "panelId": 2,
        "userId": 1,
        "userName": "",
        "newState": "",
        "prevState": "",
        "time": 1507266395000,
        "timeEnd": 1507266395000,
        "text": "test",
        "metric": "",
        "tags": [
            "tag1",
            "tag2"
        ],
        "data": {}
    },
    {
        "id": 1123,
        "alertId": 0,
        "dashboardId": 468,
        "panelId": 2,
        "userId": 1,
        "userName": "",
        "newState": "",
        "prevState": "",
        "time": 1507265111000,
        "text": "test",
        "metric": "",
        "tags": [
            "tag1",
            "tag2"
        ],
        "data": {}
    }
]

Starting in Grafana v6.4 regions annotations are now returned in one entity that now includes the timeEnd property.

Create Annotation

Creates an annotation in the Grafana database. The dashboardId and panelId fields are optional. If they are not specified then a global annotation is created and can be queried in any dashboard that adds the Grafana annotations data source. When creating a region annotation include the timeEnd property.

The format for time and timeEnd should be epoch numbers in millisecond resolution.

POST /api/annotations

Example Request:

POST /api/annotations HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "dashboardId":468,
  "panelId":1,
  "time":1507037197339,
  "timeEnd":1507180805056,
  "tags":["tag1","tag2"],
  "text":"Annotation Description"
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

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

The response for this HTTP request is slightly different in versions prior to v6.4. In prior versions you would also get an endId if you where creating a region. But in 6.4 regions are represented using a single event with time and timeEnd properties.

Create Annotation in Graphite format

Creates an annotation by using Graphite-compatible event format. The when and data fields are optional. If when is not specified then the current time will be used as annotation’s timestamp. The tags field can also be in prior to Graphite 0.10.0 format (string with multiple tags being separated by a space).

POST /api/annotations/graphite

Example Request:

POST /api/annotations/graphite HTTP/1.1
Accept: application/json
Content-Type: application/json

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

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Graphite annotation added",
    "id": 1
}

Update Annotation

PUT /api/annotations/:id

Updates all properties of an annotation that matches the specified id. To only update certain property, consider using the Patch Annotation operation.

Example Request:

PUT /api/annotations/1141 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Content-Type: application/json

{
  "time":1507037197339,
  "timeEnd":1507180805056,
  "text":"Annotation Description",
  "tags":["tag3","tag4","tag5"]
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation updated"
}

Patch Annotation

This is available in Grafana 6.0.0-beta2 and above.

PATCH /api/annotations/:id

Updates one or more properties of an annotation that matches the specified id.

This operation currently supports updating of the text, tags, time and timeEnd properties.

Example Request:

PATCH /api/annotations/1145 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Content-Type: application/json

{
  "text":"New Annotation Description",
  "tags":["tag6","tag7","tag8"]
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation patched"
}

Delete Annotation By Id

DELETE /api/annotations/:id

Deletes the annotation that matches the specified id.

Example Request:

DELETE /api/annotations/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "message":"Annotation deleted"
}

Find Annotations Tags

GET /api/annotations/tags

Find all the event tags created in the annotations.

Example Request:

GET /api/annotations/tags?tag=out HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Query Parameters:

tag: Optional. A string that you can use to filter tags.
limit: Optional. A number, where the default is 100. Max limit for results returned.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "tags": [
            {
                "tag": "outage",
                "count": 1
            }
        ]
    }
}

Authentication HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Authentication API

Tokens

Currently you can authenticate via an API Token or via a Session cookie (acquired using regular login or OAuth).

X-Grafana-Org-Id Header

X-Grafana-Org-Id is an optional property that specifies the organization to which the action is applied. If it is not set, the created key belongs to the current context org. Use this header in all requests except those regarding admin.

Example Request:

POST /api/auth/keys HTTP/1.1
Accept: application/json
Content-Type: application/json
X-Grafana-Org-Id: 2
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name": "mykey",
  "role": "Admin",
  "secondsToLive": 86400
}

Basic Auth

If basic auth is enabled (it is enabled by default), then you can authenticate your HTTP request via standard basic auth. Basic auth will also authenticate LDAP users.

curl example:

curl http://admin:admin@localhost:3000/api/org
{"id":1,"name":"Main Org."}

Create API Token

Open the sidemenu and click the organization dropdown and select the API Keys option.

You use the token in all requests in the Authorization header, like this:

Example:

GET http://your.grafana.com/api/dashboards/db/mydash HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

The Authorization header value should be Bearer <your api key>.

The API Token can also be passed as a Basic authorization password with the special username api_key:

curl example:

curl http://api_key:eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk@localhost:3000/api/org
{"id":1,"name":"Main Org."}

Auth HTTP resources / actions

Api Keys

GET /api/auth/keys

Example Request:

GET /api/auth/keys HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Query Parameters:

includeExpired: boolean. enable listing of expired keys. Optional.

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 3,
    "name": "API",
    "role": "Admin"
  },
  {
    "id": 1,
    "name": "TestAdmin",
    "role": "Admin",
    "expiration": "2019-06-26T10:52:03+03:00"
  }
]

Create API Key

POST /api/auth/keys

Example Request:

POST /api/auth/keys HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name": "mykey",
  "role": "Admin",
  "secondsToLive": 86400
}

JSON Body schema:

name – The key name
role – Sets the access level/Grafana Role for the key. Can be one of the following values: Viewer, Editor or Admin.
secondsToLive – Sets the key expiration in seconds. It is optional. If it is a positive number an expiration date for the key is set. If it is null, zero or is omitted completely (unless api_key_max_seconds_to_live configuration option is set) the key will never expire.

Error statuses:

400 – api_key_max_seconds_to_live is set but no secondsToLive is specified or secondsToLive is greater than this value.
500 – The key was unable to be stored in the database.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"name":"mykey","key":"eyJrIjoiWHZiSWd3NzdCYUZnNUtibE9obUpESmE3bzJYNDRIc0UiLCJuIjoibXlrZXkiLCJpZCI6MX1=","id":1}

Delete API Key

DELETE /api/auth/keys/:id

Example Request:

DELETE /api/auth/keys/3 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"API key deleted"}

cURL examples

Sat, 04 Apr 2026 12:26:57 +0000

cURL examples

This page provides examples of calls to the Grafana API using cURL.

The most basic example for a dashboard for which there is no authentication. You can test the following on your local machine, assuming a default installation and anonymous access enabled, required:

curl http://localhost:3000/api/search

Here’s a cURL command that works for getting the home dashboard when you are running Grafana locally with basic authentication enabled using the default admin credentials:

curl http://admin:admin@localhost:3000/api/search

Dashboard HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Dashboard API

Identifier (id) vs unique identifier (uid)

The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.

The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs. It’s automatically generated if not provided when creating a dashboard. The uid allows having consistent URLs for accessing dashboards and when syncing dashboards between multiple Grafana installs, see dashboard provisioning for more information. This means that changing the title of a dashboard will not break any bookmarked links to that dashboard.

The uid can have a maximum length of 40 characters.

Create / Update dashboard

POST /api/dashboards/db

Creates a new dashboard or updates an existing dashboard. When updating existing dashboards, if you do not define the folderId or the folderUid property, then the dashboard(s) are moved to the General folder. (You need to define only one property, not both).

Example Request for new dashboard:

POST /api/dashboards/db HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

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

JSON Body schema:

dashboard – The complete dashboard model, id = null to create a new dashboard.
dashboard.id – id = null to create a new dashboard.
dashboard.uid – Optional unique identifier when creating a dashboard. uid = null will generate a new uid.
folderId – The id of the folder to save the dashboard in.
folderUid – The UID of the folder to save the dashboard in. Overrides the folderId.
overwrite – Set to true if you want to overwrite existing dashboard with newer version, same dashboard title in folder or same dashboard uid.
message - Set a commit message for the version history.
refresh - Set the dashboard refresh interval. If this is lower than the minimum refresh interval, then Grafana will ignore it and will enforce the minimum refresh interval.

For adding or updating an alert rule for a dashboard panel the user should declare a dashboard.panels.alert block.

Example Request for updating dashboard alert rule:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 78

{
 "dashboard":  {
        "id": 104,
        "panels": [
            {
                "alert": {
                    "alertRuleTags": {},
                    "conditions": [
                        {
                            "evaluator": {
                                "params": [
                                    25
                                ],
                                "type": "gt"
                            },
                            "operator": {
                                "type": "and"
                            },
                            "query": {
                                "params": [
                                    "A",
                                    "5m",
                                    "now"
                                ]
                            },
                            "reducer": {
                                "params": [],
                                "type": "avg"
                            },
                            "type": "query"
                        }
                    ],
                    "executionErrorState": "alerting",
                    "for": "5m",
                    "frequency": "1m",
                    "handler": 1,
                    "name": "Panel Title alert",
                    "noDataState": "no_data",
                    "notifications": []
                },
                "aliasColors": {},
                "bars": false,
                "dashLength": 10,
                "dashes": false,
                "datasource": null,
                "fieldConfig": {
                    "defaults": {
                        "custom": {}
                    },
                    "overrides": []
                },
                "fill": 1,
                "fillGradient": 0,
                "gridPos": {
                    "h": 9,
                    "w": 12,
                    "x": 0,
                    "y": 0
                },
                "hiddenSeries": false,
                "id": 2,
                "legend": {
                    "avg": false,
                    "current": false,
                    "max": false,
                    "min": false,
                    "show": true,
                    "total": false,
                    "values": false
                },
                "lines": true,
                "linewidth": 1,
                "nullPointMode": "null",
                "options": {
                    "dataLinks": []
                },
                "percentage": false,
                "pointradius": 2,
                "points": false,
                "renderer": "flot",
                "seriesOverrides": [],
                "spaceLength": 10,
                "stack": false,
                "steppedLine": false,
                "targets": [
                    {
                        "refId": "A",
                        "scenarioId": "random_walk"
                    }
                ],
                "thresholds": [
                    {
                        "colorMode": "critical",
                        "fill": true,
                        "line": true,
                        "op": "gt",
                        "value": 50
                    }
                ],
                "timeFrom": null,
                "timeRegions": [],
                "timeShift": null,
                "title": "Panel Title",
                "tooltip": {
                    "shared": true,
                    "sort": 0,
                    "value_type": "individual"
                },
                "type": "graph",
                "xaxis": {
                    "buckets": null,
                    "mode": "time",
                    "name": null,
                    "show": true,
                    "values": []
                },
                "yaxes": [
                    {
                        "format": "short",
                        "label": null,
                        "logBase": 1,
                        "max": null,
                        "min": null,
                        "show": true
                    },
                    {
                        "format": "short",
                        "label": null,
                        "logBase": 1,
                        "max": null,
                        "min": null,
                        "show": true
                    }
                ],
                "yaxis": {
                    "align": false,
                    "alignLevel": null
                }
            }
        ],
        "title": "Update alert rule via API",
        "uid": "dHEquNzGz",
        "version": 1
    }
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 78

{
  "id":      1,
  "uid":     "cIBgcSjkk",
  "url":     "/d/cIBgcSjkk/production-overview",
  "status":  "success",
  "version": 1,
  "slug":    "production-overview" //deprecated in Grafana v5.0
}

Status Codes:

200 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Access denied
412 – Precondition failed

The 412 status code is used for explaining that you cannot create the dashboard and why. There can be different reasons for this:

The dashboard has been changed by someone else, status=version-mismatch
A dashboard with the same name in the folder already exists, status=name-exists
A dashboard with the same uid already exists, status=name-exists
The dashboard belongs to plugin <plugin title>, status=plugin-dashboard

The response body will have the following properties:

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97

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

In case of title already exists the status property will be name-exists.

Get dashboard by uid

GET /api/dashboards/uid/:uid

Will return the dashboard given the dashboard unique identifier (uid). Information about the unique identifier of a folder containing the requested dashboard might be found in the metadata.

Example Request:

GET /api/dashboards/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "dashboard": {
    "id": 1,
    "uid": "cIBgcSjkk",
    "title": "Production Overview",
    "tags": [ "templated" ],
    "timezone": "browser",
    "schemaVersion": 16,
    "version": 0
  },
  "meta": {
    "isStarred": false,
    "url": "/d/cIBgcSjkk/production-overview",
    "folderId": 2,
    "folderUid": "l3KqBxCMz",
    "slug": "production-overview" //deprecated in Grafana v5.0
  }
}

Status Codes:

200 – Found
401 – Unauthorized
403 – Access denied
404 – Not found

Delete dashboard by uid

DELETE /api/dashboards/uid/:uid

Will delete the dashboard given the specified unique identifier (uid).

Example Request:

DELETE /api/dashboards/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

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

Status Codes:

200 – Deleted
401 – Unauthorized
403 – Access denied
404 – Not found

Gets the home dashboard

GET /api/dashboards/home

Will return the home dashboard.

Example Request:

GET /api/dashboards/home HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "dashboard": {
    "editable":false,
    "hideControls":true,
    "nav":[
      {
        "enable":false,
        "type":"timepicker"
      }
    ],
    "style":"dark",
    "tags":[],
    "templating":{
      "list":[
      ]
    },
    "time":{
    },
    "timezone":"browser",
    "title":"Home",
    "version":5
  },
  "meta":	{
    "isHome":true,
    "canSave":false,
    "canEdit":false,
    "canStar":false,
    "url":"",
    "expires":"0001-01-01T00:00:00Z",
    "created":"0001-01-01T00:00:00Z"
  }
}

Tags for Dashboard

GET /api/dashboards/tags

Get all tags of dashboards

Example Request:

GET /api/dashboards/tags HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "term":"tag1",
    "count":1
  },
  {
    "term":"tag2",
    "count":4
  }
]

Dashboard Search

See Folder/Dashboard Search API.

Dashboard Permissions HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Dashboard Permissions API

This API can be used to update/get the permissions for a dashboard.

Permissions with dashboardId=-1 are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything.

The permission levels for the permission field:

1 = View
2 = Edit
4 = Admin

Get permissions for a dashboard

GET /api/dashboards/id/:dashboardId/permissions

Gets all existing permissions for the dashboard with the given dashboardId.

Example request:

GET /api/dashboards/id/1/permissions HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 551

[
  {
    "id": 1,
    "dashboardId": -1,
    "created": "2017-06-20T02:00:00+02:00",
    "updated": "2017-06-20T02:00:00+02:00",
    "userId": 0,
    "userLogin": "",
    "userEmail": "",
    "teamId": 0,
    "team": "",
    "role": "Viewer",
    "permission": 1,
    "permissionName": "View",
    "uid": "",
    "title": "",
    "slug": "",
    "isFolder": false,
    "url": ""
  },
  {
    "id": 2,
    "dashboardId": -1,
    "created": "2017-06-20T02:00:00+02:00",
    "updated": "2017-06-20T02:00:00+02:00",
    "userId": 0,
    "userLogin": "",
    "userEmail": "",
    "teamId": 0,
    "team": "",
    "role": "Editor",
    "permission": 2,
    "permissionName": "Edit",
    "uid": "",
    "title": "",
    "slug": "",
    "isFolder": false,
    "url": ""
  }
]

Status Codes:

200 - Ok
401 - Unauthorized
403 - Access denied
404 - Dashboard not found

Update permissions for a dashboard

POST /api/dashboards/id/:dashboardId/permissions

Updates permissions for a dashboard. This operation will remove existing permissions if they’re not included in the request.

Example request:

POST /api/dashboards/id/1/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

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

JSON body schema:

items - The permission items to add/update. Items that are omitted from the list will be removed.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35

{"message":"Dashboard permissions updated"}

Status Codes:

200 - Ok
401 - Unauthorized
403 - Access denied
404 - Dashboard not found

Dashboard Versions HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Dashboard Versions

Get all dashboard versions

Query parameters:

limit - Maximum number of results to return
start - Version to start from when returning queries

GET /api/dashboards/id/:dashboardId/versions

Gets all existing dashboard versions for the dashboard with the given dashboardId.

Example request for getting all dashboard versions:

GET /api/dashboards/id/1/versions?limit=2?start=0 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 428

[
  {
    "id": 2,
    "dashboardId": 1,
    "parentVersion": 1,
    "restoredFrom": 0,
    "version": 2,
    "created": "2017-06-08T17:24:33-04:00",
    "createdBy": "admin",
    "message": "Updated panel title"
  },
  {
    "id": 1,
    "dashboardId": 1,
    "parentVersion": 0,
    "restoredFrom": 0,
    "version": 1,
    "created": "2017-06-08T17:23:33-04:00",
    "createdBy": "admin",
    "message": "Initial save"
  }
]

Status Codes:

200 - Ok
400 - Errors
401 - Unauthorized
404 - Dashboard version not found

Get dashboard version

GET /api/dashboards/id/:dashboardId/versions/:version

Get the dashboard version with the given version, for the dashboard with the given id.

Example request for getting a dashboard version:

GET /api/dashboards/id/1/versions/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 1300

{
  "id": 1,
  "dashboardId": 1,
  "parentVersion": 0,
  "restoredFrom": 0,
  "version": 1,
  "created": "2017-04-26T17:18:38-04:00",
  "message": "Initial save",
  "data": {
    "annotations": {
      "list": [

      ]
    },
    "editable": true,
    "gnetId": null,
    "graphTooltip": 0,
    "hideControls": false,
    "id": 1,
    "links": [

    ],
    "rows": [
      {
        "collapse": false,
        "height": "250px",
        "panels": [

        ],
        "repeat": null,
        "repeatIteration": null,
        "repeatRowId": null,
        "showTitle": false,
        "title": "Dashboard Row",
        "titleSize": "h6"
      }
    ],
    "schemaVersion": 14,
    "style": "dark",
    "tags": [

    ],
    "templating": {
      "list": [

      ]
    },
    "time": {
      "from": "now-6h",
      "to": "now"
    },
    "timepicker": {
      "refresh_intervals": [
        "5s",
        "10s",
        "30s",
        "1m",
        "5m",
        "15m",
        "30m",
        "1h",
        "2h",
        "1d"
      ],
      "time_options": [
        "5m",
        "15m",
        "1h",
        "6h",
        "12h",
        "24h",
        "2d",
        "7d",
        "30d"
      ]
    },
    "timezone": "browser",
    "title": "test",
    "version": 1
  },
  "createdBy": "admin"
}

Status Codes:

200 - Ok
401 - Unauthorized
404 - Dashboard version not found

Restore dashboard

POST /api/dashboards/id/:dashboardId/restore

Restores a dashboard to a given dashboard version.

Example request for restoring a dashboard version:

POST /api/dashboards/id/1/restore
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "version": 1
}

JSON body schema:

version - The dashboard version to restore to

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 67

{
  "slug": "my-dashboard",
  "status": "success",
  "version": 3
}

JSON response body schema:

slug - the URL friendly slug of the dashboard’s title
status - whether the restoration was successful or not
version - the new dashboard version, following the restoration

Status codes:

200 - OK
401 - Unauthorized
404 - Not found (dashboard not found or dashboard version not found)
500 - Internal server error (indicates issue retrieving dashboard tags from database)

Example error response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=UTF-8
Content-Length: 46

{
  "message": "Dashboard version not found"
}

JSON response body schema:

message - Message explaining the reason for the request failure.

Compare dashboard versions

POST /api/dashboards/calculate-diff

Compares two dashboard versions by calculating the JSON diff of them.

Example request:

POST /api/dashboards/calculate-diff HTTP/1.1
Accept: text/html
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "base": {
    "dashboardId": 1,
    "version": 1
  },
  "new": {
    "dashboardId": 1,
    "version": 2
  },
  "diffType": "json"
}

JSON body schema:

base - an object representing the base dashboard version
new - an object representing the new dashboard version
diffType - the type of diff to return. Can be “json” or “basic”.

Example response (JSON diff):

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

<p id="l1" class="diff-line diff-json-same">
  <!-- Diff omitted -->
</p>

The response is a textual representation of the diff, with the dashboard values being in JSON, similar to the diffs seen on sites like GitHub or GitLab.

Status Codes:

200 - Ok
400 - Bad request (invalid JSON sent)
401 - Unauthorized
404 - Not found

Example response (basic diff):

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

<div class="diff-group">
  <!-- Diff omitted -->
</div>

The response here is a summary of the changes, derived from the diff between the two JSON objects.

Status Codes:

200 - OK
400 - Bad request (invalid JSON sent)
401 - Unauthorized
404 - Not found

Data source HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Data source API

If you are running Grafana Enterprise and have Fine-grained access control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required.

Get all data sources

GET /api/datasources

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:read	datasources:*

Examples

Example Request:

GET /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
   {
     "id": 1,
     "orgId": 1,
     "uid": "H8joYFVGz"
     "name": "datasource_elastic",
     "type": "elasticsearch",
     "typeLogoUrl": "public/app/plugins/datasource/elasticsearch/img/elasticsearch.svg",
     "access": "proxy",
     "url": "http://mydatasource.com",
     "password": "",
     "user": "",
     "database": "grafana-dash",
     "basicAuth": false,
     "isDefault": false,
     "jsonData": {
         "esVersion": 5,
         "logLevelField": "",
         "logMessageField": "",
         "maxConcurrentShardRequests": 256,
         "timeField": "@timestamp"
     },
     "readOnly": false
   }
]

Get a single data source by Id

GET /api/datasources/:datasourceId

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:read	datasources:* datasources:id:* datasources:id:1 (single data source)

Examples

Example Request:

GET /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "kLtEtcRGk",
  "orgId": 1,
  "name": "test_datasource",
  "type": "graphite",
  "typeLogoUrl": "",
  "access": "proxy",
  "url": "http://mydatasource.com",
  "password": "",
  "user": "",
  "database": "",
  "basicAuth": false,
  "basicAuthUser": "",
  "basicAuthPassword": "",
  "withCredentials": false,
  "isDefault": false,
  "jsonData": {
    "graphiteType": "default",
    "graphiteVersion": "1.1"
  },
  "secureJsonFields": {},
  "version": 1,
  "readOnly": false
}

Get a single data source by UID

GET /api/datasources/uid/:uid

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:read	datasources:* datasources:uid:* datasources:uid:kLtEtcRGk (single data source)

Examples

Example request:

GET /api/datasources/uid/kLtEtcRGk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "kLtEtcRGk",
  "orgId": 1,
  "name": "test_datasource",
  "type": "graphite",
  "typeLogoUrl": "",
  "access": "proxy",
  "url": "http://mydatasource.com",
  "password": "",
  "user": "",
  "database": "",
  "basicAuth": false,
  "basicAuthUser": "",
  "basicAuthPassword": "",
  "withCredentials": false,
  "isDefault": false,
  "jsonData": {
    "graphiteType": "default",
    "graphiteVersion": "1.1"
  },
  "secureJsonFields": {},
  "version": 1,
  "readOnly": false
}

Get a single data source by Name

GET /api/datasources/name/:name

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:read	datasources:* datasources:name:* datasources:name:test_datasource (single data source)

Examples

Example Request:

GET /api/datasources/name/test_datasource HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "kLtEtcRGk",
  "orgId": 1,
  "name": "test_datasource",
  "type": "graphite",
  "typeLogoUrl": "",
  "access": "proxy",
  "url": "http://mydatasource.com",
  "password": "",
  "user": "",
  "database": "",
  "basicAuth": false,
  "basicAuthUser": "",
  "basicAuthPassword": "",
  "withCredentials": false,
  "isDefault": false,
  "jsonData": {
    "graphiteType": "default",
    "graphiteVersion": "1.1"
  },
  "secureJsonFields": {},
  "version": 1,
  "readOnly": false
}

Get data source Id by Name

GET /api/datasources/id/:name

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources.id:read	datasources:* datasources:name:* datasources:name:test_datasource (single data source)

Examples

Example Request:

GET /api/datasources/id/test_datasource HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1
}

Create a data source

POST /api/datasources

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:create	n/a

Examples

Example Graphite Request:

POST /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name":"test_datasource",
  "type":"graphite",
  "url":"http://mydatasource.com",
  "access":"proxy",
  "basicAuth":false
}

Example Graphite Response:

HTTP/1.1 200
Content-Type: application/json

{
  "datasource": {
    "id": 1,
    "orgId": 1,
    "name": "test_datasource",
    "type": "graphite",
    "typeLogoUrl": "",
    "access": "proxy",
    "url": "http://mydatasource.com",
    "password": "",
    "user": "",
    "database": "",
    "basicAuth": false,
    "basicAuthUser": "",
    "basicAuthPassword": "",
    "withCredentials": false,
    "isDefault": false,
    "jsonData": {},
    "secureJsonFields": {},
    "version": 1,
    "readOnly": false
  },
  "id": 1,
  "message": "Datasource added",
  "name": "test_datasource"
}

Note: By defining password and basicAuthPassword under secureJsonData Grafana encrypts them securely as an encrypted blob in the database. The response then lists the encrypted fields under secureJsonFields.

Example Graphite Request with basic auth enabled:

POST /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name": "test_datasource",
  "type": "graphite",
  "url": "http://mydatasource.com",
  "access": "proxy",
  "basicAuth": true,
  "basicAuthUser": "basicuser",
  "secureJsonData": {
    "basicAuthPassword": "basicpassword"
  }
}

Example Response with basic auth enabled:

HTTP/1.1 200
Content-Type: application/json

{
  "datasource": {
    "id": 1,
    "orgId": 1,
    "name": "test_datasource",
    "type": "graphite",
    "typeLogoUrl": "",
    "access": "proxy",
    "url": "http://mydatasource.com",
    "password": "",
    "user": "",
    "database": "",
    "basicAuth": true,
    "basicAuthUser": "basicuser",
    "basicAuthPassword": "",
    "withCredentials": false,
    "isDefault": false,
    "jsonData": {},
    "secureJsonFields": {
      "basicAuthPassword": true
    },
    "version": 1,
    "readOnly": false
  },
  "id": 102,
  "message": "Datasource added",
  "name": "test_datasource"
}

Example CloudWatch Request:

POST /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name": "test_datasource",
  "type": "cloudwatch",
  "url": "http://monitoring.us-west-1.amazonaws.com",
  "access": "proxy",
  "jsonData": {
    "authType": "keys",
    "defaultRegion": "us-west-1"
  },
  "secureJsonData": {
    "accessKey": "Ol4pIDpeKSA6XikgOl4p",
    "secretKey": "dGVzdCBrZXkgYmxlYXNlIGRvbid0IHN0ZWFs"
  }
}

Update an existing data source

PUT /api/datasources/:datasourceId

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:write	datasources:* datasources:id:* datasources:id:1 (single data source)

Examples

Example Request:

PUT /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "id":1,
  "orgId":1,
  "name":"test_datasource",
  "type":"graphite",
  "access":"proxy",
  "url":"http://mydatasource.com",
  "password":"",
  "user":"",
  "database":"",
  "basicAuth":true,
  "basicAuthUser":"basicuser",
  "secureJsonData": {
    "basicAuthPassword": "basicpassword"
  },
  "isDefault":false,
  "jsonData":null
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "datasource": {
    "id": 1,
    "orgId": 1,
    "name": "test_datasource",
    "type": "graphite",
    "typeLogoUrl": "",
    "access": "proxy",
    "url": "http://mydatasource.com",
    "password": "",
    "user": "",
    "database": "",
    "basicAuth": true,
    "basicAuthUser": "basicuser",
    "basicAuthPassword": "",
    "withCredentials": false,
    "isDefault": false,
    "jsonData": {},
    "secureJsonFields": {
      "basicAuthPassword": true
    },
    "version": 1,
    "readOnly": false
  },
  "id": 102,
  "message": "Datasource updated",
  "name": "test_datasource"
}

Note: Similar to creating a data source, password and basicAuthPassword should be defined under secureJsonData in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed under secureJsonFields section in the response.

Delete an existing data source by id

DELETE /api/datasources/:datasourceId

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:delete	datasources:* datasources:id:* datasources:id:1 (single data source)

Examples

Example Request:

DELETE /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Data source deleted"}

Delete an existing data source by UID

DELETE /api/datasources/uid/:uid

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:delete	datasources:* datasources:uid:* datasources:uid:kLtEtcRGk (single data source)

Examples

Example request:

DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200
Content-Type: application/json

{
    "message": "Data source deleted",
    "id": 1
}

Delete an existing data source by name

DELETE /api/datasources/name/:datasourceName

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources:delete	datasources:* datasources:name:* datasources:name:test_datasource (single data source)

Examples

Example Request:

DELETE /api/datasources/name/test_datasource HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message":"Data source deleted",
  "id": 1
}

Data source proxy calls

GET /api/datasources/proxy/:datasourceId/*

Proxies all calls to the actual data source.

Query a data source by ID

Queries a data source having backend implementation.

POST /api/tsdb/query

Note: Most of Grafana’s builtin data sources have backend implementation.

Example Request:

POST /api/tsdb/query HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "from": "1420066800000",
  "to": "1575845999999",
  "queries": [
    {
      "refId": "A",
      "intervalMs": 86400000,
      "maxDataPoints": 1092,
      "datasourceId": 86,
      "rawSql": "SELECT 1 as valueOne, 2 as valueTwo",
      "format": "table"
    }
  ]
}

Note: The from, to, and queries properties are required.

JSON Body schema:

from/to – Should be either absolute in epoch timestamps in milliseconds or relative using Grafana time units. For example, now-1h.
queries.refId – Specifies an identifier of the query. Is optional and default to “A”.
queries.datasourceId – Specifies the data source to be queried. Each query in the request must have an unique datasourceId.
queries.maxDataPoints - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100.
queries.intervalMs - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000.

In addition, each data source has its own specific properties that should be added in a request.

Example request for the MySQL data source:

POST /api/tsdb/query HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "from": "1420066800000",
  "to": "1575845999999",
  "queries": [
    {
      "refId": "A",
      "intervalMs": 86400000,
      "maxDataPoints": 1092,
      "datasourceId": 86,
      "rawSql": "SELECT\n  time,\n  sum(opened) AS \"Opened\",\n  sum(closed) AS \"Closed\"\nFROM\n  issues_activity\nWHERE\n  $__unixEpochFilter(time) AND\n  period = 'm' AND\n  repo IN('grafana/grafana') AND\n  opened_by IN('Contributor','Grafana Labs')\nGROUP BY 1\nORDER BY 1\n",
      "format": "time_series"
    }
  ]
}

Example MySQL time series query response:

HTTP/1.1 200
Content-Type: application/json

{
  "results": {
    "A": {
      "refId": "A",
      "meta": {
        "rowCount": 0,
        "sql": "SELECT\n  time,\n  sum(opened) AS \"Opened\",\n  sum(closed) AS \"Closed\"\nFROM\n  issues_activity\nWHERE\n  time >= 1420066800 AND time <= 1575845999 AND\n  period = 'm' AND\n  repo IN('grafana/grafana') AND\n  opened_by IN('Contributor','Grafana Labs')\nGROUP BY 1\nORDER BY 1\n"
      },
      "series": [
        {
          "name": "Opened",
          "points": [
            [
              109,
              1420070400000
            ],
            [
              122,
              1422748800000
            ]
          ]
        },
        {
          "name": "Closed",
          "points": [
            [
              89,
              1420070400000
            ]
          ]
        }
      ]
    }
  }
}

Datasource Permissions HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Data Source Permissions API

The Data Source Permissions is only available in Grafana Enterprise. Read more about Grafana Enterprise.

If you are running Grafana Enterprise and have Fine-grained access control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required.

This API can be used to enable, disable, list, add and remove permissions for a data source.

Permissions can be set for a user or a team. Permissions cannot be set for Admins - they always have access to everything.

The permission levels for the permission field:

1 = Query

Enable permissions for a data source

POST /api/datasources/:id/enable-permissions

Enables permissions for the data source with the given id. No one except Org Admins will be able to query the data source until permissions have been added which permit certain users or teams to query the data source.

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources.permissions:write	datasources:* datasources:id:* datasources:id:1 (single data source)

Examples

Example request:

POST /api/datasources/1/enable-permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35

{"message":"Datasource permissions enabled"}

Status codes:

200 - Ok
400 - Permissions cannot be enabled, see response body for details
401 - Unauthorized
403 - Access denied
404 - Datasource not found

Disable permissions for a data source

POST /api/datasources/:id/disable-permissions

Disables permissions for the data source with the given id. All existing permissions will be removed and anyone will be able to query the data source.

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources.permissions:write	datasources:* datasources:id:* datasources:id:1 (single data source)

Examples

Example request:

POST /api/datasources/1/disable-permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35

{"message":"Datasource permissions disabled"}

Status codes:

200 - Ok
400 - Permissions cannot be disabled, see response body for details
401 - Unauthorized
403 - Access denied
404 - Datasource not found

Get permissions for a data source

GET /api/datasources/:id/permissions

Gets all existing permissions for the data source with the given id.

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources.permissions:read	datasources:* datasources:id:* datasources:id:1 (single data source)

Examples

Example request:

GET /api/datasources/1/permissions HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 551

{
  "datasourceId": 1,
  "enabled": true,
  "permissions":
  [
    {
      "id": 1,
      "datasourceId": 1,
      "userId": 1,
      "userLogin": "user",
      "userEmail": "user@test.com",
      "userAvatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
      "permission": 1,
      "permissionName": "Query",
      "created": "2017-06-20T02:00:00+02:00",
      "updated": "2017-06-20T02:00:00+02:00",
    },
    {
      "id": 2,
      "datasourceId": 1,
      "teamId": 1,
      "team": "A Team",
      "teamAvatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
      "permission": 1,
      "permissionName": "Query",
      "created": "2017-06-20T02:00:00+02:00",
      "updated": "2017-06-20T02:00:00+02:00",
    }
  ]
}

Status codes:

200 - Ok
401 - Unauthorized
403 - Access denied
404 - Datasource not found

Add permission for a data source

POST /api/datasources/:id/permissions

Adds a user permission for the data source with the given id.

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources.permissions:write	datasources:* datasources:id:* datasources:id:1 (single data source)

Examples

Example request:

POST /api/datasources/1/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "userId": 1,
  "permission": 1
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35

{"message":"Datasource permission added"}

Adds a team permission for the data source with the given id.

Example request:

POST /api/datasources/1/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "teamId": 1,
  "permission": 1
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35

{"message":"Datasource permission added"}

Status codes:

200 - Ok
400 - Permission cannot be added, see response body for details
401 - Unauthorized
403 - Access denied
404 - Datasource not found

Remove permission for a data source

DELETE /api/datasources/:id/permissions/:permissionId

Removes the permission with the given permissionId for the data source with the given id.

Required permissions

See note in the introduction for an explanation.

Action	Scope
datasources.permissions:write	datasources:* datasources:id:* datasources:id:1 (single data source)

Examples

Example request:

DELETE /api/datasources/1/permissions/2
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35

{"message":"Datasource permission removed"}

Status codes:

200 - Ok
401 - Unauthorized
403 - Access denied
404 - Datasource not found or permission not found

External Group Sync HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

External Group Synchronization API

External Group Synchronization is only available in Grafana Enterprise. Read more about Grafana Enterprise.

If you have Fine-grained access control enabled, access to endpoints will be controlled by Fine-grained access control permissions. Refer to specific endpoints to understand what permissions are required.

Get External Groups

GET /api/teams/:teamId/groups

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams.permissions:read	teams:*

Example Request:

GET /api/teams/1/groups HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId": 1,
    "teamId": 1,
    "groupId": "cn=editors,ou=groups,dc=grafana,dc=org"
  }
]

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied

Add External Group

POST /api/teams/:teamId/groups

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams.permissions:write	teams:*

Example Request:

POST /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "groupId": "cn=editors,ou=groups,dc=grafana,dc=org"
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Group added to Team"}

Status Codes:

200 - Ok
400 - Group is already added to this team
401 - Unauthorized
403 - Permission denied
404 - Team not found

Remove External Group

DELETE /api/teams/:teamId/groups/:groupId

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams.permissions:write	teams:*

Example Request:

DELETE /api/teams/1/groups/cn=editors,ou=groups,dc=grafana,dc=org HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team Group removed"}

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied
404 - Team not found/Group not found

Fine-grained access control HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Fine-grained access control API

Fine-grained access control API is only available in Grafana Enterprise. Read more about Grafana Enterprise.

The API can be used to create, update, get and list roles, and create or remove built-in role assignments. To use the API, you would need to enable fine-grained access control.

The API does not currently work with an API Token. So in order to use these API endpoints you will have to use Basic auth.

Get status

GET /api/access-control/status

Returns an indicator to check if fine-grained access control is enabled or not.

Required permissions

Action	Scope
status:accesscontrol	services:accesscontrol

Example request

GET /api/access-control/status
Accept: application/json
Content-Type: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "enabled": true
}

Status codes

Code	Description
200	Returned a flag indicating if the fine-grained access control is enabled or no.
403	Access denied
404	Not found, an indication that fine-grained access control is not available at all.
500	Unexpected error. Refer to body and/or server logs for more details.

Create and manage custom roles

Get all roles

GET /api/access-control/roles

Gets all existing roles. The response contains all global and organization local roles, for the organization which user is signed in.

Refer to the Role scopes for more information.

Required permissions

Action	Scope
roles:list	roles:*

Example request

GET /api/access-control/roles
Accept: application/json
Content-Type: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 3,
        "uid": "XvHQJq57z",
        "name": "fixed:reports:reader",
        "displayName": "Report reader",
        "description": "Read all reports and shared report settings.",
        "group": "Reports",
        "updated": "2021-11-19T10:48:00+01:00",
        "created": "2021-11-19T10:48:00+01:00",
        "global": false
    },
    {
        "version": 5,
        "uid": "vi9mlLjGz",
        "name": "fixed:datasources.permissions:writer",
        "description: "Create, read or delete data source permissions.",
        "global": true,
        "updated": "2021-05-13T22:41:49+02:00",
        "created": "2021-05-13T16:24:26+02:00"
    }
]

Status codes

Code	Description
200	Global and organization local roles are returned.
403	Access denied
500	Unexpected error. Refer to body and/or server logs for more details.

Get a role

GET /api/access-control/roles/:uid

Get a role for the given UID.

Required permissions

Action	Scope
roles:read	roles:*

Example request

GET /api/access-control/roles/PYnDO3rMk
Accept: application/json
Content-Type: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version": 4,
    "uid": "6dNwJq57z",
    "name": "fixed:reports:writer",
    "displayName": "Report writer",
    "description": "Create, read, update, or delete all reports and shared report settings.",
    "group": "Reports",
    "permissions": [
        {
            "action": "reports:delete",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:read",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:send",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.admin:create",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.admin:write",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.settings:read",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.settings:write",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        }
    ],
    "updated": "2021-11-19T10:48:00+01:00",
    "created": "2021-11-19T10:48:00+01:00",
    "global": false
}

Status codes

Code	Description
200	Role is returned.
403	Access denied.
500	Unexpected error. Refer to body and/or server logs for more details.

Create a new custom role

POST /api/access-control/roles

Creates a new custom role and maps given permissions to that role. Note that roles with the same prefix as Fixed Roles can’t be created.

Required permissions

permission:delegate scope ensures that users can only create custom roles with the same, or a subset of permissions which the user has. For example, if a user does not have required permissions for creating users, they won’t be able to create a custom role which allows to do that. This is done to prevent escalation of privileges.

Action	Scope
roles:write	permissions:delegate

Example request

POST /api/access-control/roles
Accept: application/json
Content-Type: application/json

{
    "version": 1,
    "uid": "jZrmlLCGka",
    "name": "custom:delete:roles",
    "displayName": "custom delete roles",
    "description": "My custom role which gives users permissions to delete roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:delegate"
        }
    ]
}

JSON body schema

Field Name	Date Type	Required	Description
uid	string	No	UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the Custom roles for more information.
global	boolean	No	A flag indicating if the role is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. Refer to the Role scopes for more information.
version	number	No	Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the Custom roles for more information.
name	string	Yes	Name of the role. Refer to Custom roles for more information.
description	string	No	Description of the role.
displayName	string	No	Display name of the role, visible in the UI.
group	string	No	The group name the role belongs to.
permissions	Permission	No	If not present, the role will be created without any permissions.

Permission

Field Name	Data Type	Required	Description
action	string	Yes	Refer to Permissions for full list of available actions.
scope	string	No	If not present, no scope will be mapped to the permission. Refer to Permissions for full list of available scopes.

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version": 2,
    "uid": "jZrmlLCGka",
    "name": "custom:delete:create:roles",
    "displayName": "custom delete create roles",
    "description": "My custom role which gives users permissions to delete and create roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:delegate",
            "updated": "2021-05-13T23:19:46+02:00",
            "created": "2021-05-13T23:19:46+02:00"
        }
    ],
    "updated": "2021-05-13T23:20:51.416518+02:00",
    "created": "2021-05-13T23:19:46+02:00"
}

Status codes

Code	Description
200	Role is updated.
400	Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403	Access denied
500	Unexpected error. Refer to body and/or server logs for more details.

Update a custom role

PUT /api/access-control/roles/:uid

Update the role with the given UID, and it’s permissions with the given UID. The operation is idempotent and all permissions of the role will be replaced with what is in the request. You would need to increment the version of the role with each update, otherwise the request will fail.

Required permissions

permission:delegate scope ensures that users can only update custom roles with the same, or a subset of permissions which the user has. For example, if a user does not have required permissions for creating users, they won’t be able to update a custom role which allows to do that. This is done to prevent escalation of privileges.

Action	Scope
roles:write	permissions:delegate

Example request

PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json

{
    "version": 3,
    "name": "custom:delete:write:roles",
    "displayName": "custom delete write roles",
    "description": "My custom role which gives users permissions to delete and write roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:delegate"
        },
        {
            "action": "roles:write",
            "scope": "permissions:delegate"
        }
    ]
}

JSON body schema

Field Name	Data Type	Required	Description
version	number	Yes	Version of the role. Must be incremented for update to work.
name	string	Yes	Name of the role.
description	string	No	Description of the role.
displayName	string	No	Display name of the role, visible in the UI.
group	string	No	The group name the role belongs to.
permissions	List of Permissions	No	The full list of permissions the role should have after the update.

Permission

Field Name	Data Type	Required	Description
action	string	Yes	Refer to Permissions for full list of available actions.
scope	string	No	If not present, no scope will be mapped to the permission. Refer to Permissions for full list of available scopes.

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version":3,
    "uid":"jZrmlLCGka",
    "name":"custom:delete:write:roles",
    "displayName":"custom delete write roles",
    "description":"My custom role which gives users permissions to delete and write roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "permissions":[
        {
            "action":"roles:delete",
            "scope":"permissions:delegate",
            "updated":"2021-08-06T18:27:40+02:00",
            "created":"2021-08-06T18:27:40+02:00"
        },
        {
            "action":"roles:write",
            "scope":"permissions:delegate",
            "updated":"2021-08-06T18:27:41+02:00",
            "created":"2021-08-06T18:27:41+02:00"
        }
    ],
    "updated":"2021-08-06T18:27:41+02:00",
    "created":"2021-08-06T18:27:40+02:00",
    "global":false
}

Status codes

Code	Description
200	Role is updated.
400	Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403	Access denied
404	Role was not found to update.
500	Unexpected error. Refer to body and/or server logs for more details.

Delete a custom role

DELETE /api/access-control/roles/:uid?force=false

Delete a role with the given UID, and it’s permissions. If the role is assigned to a built-in role, the deletion operation will fail, unless force query param is set to true, and in that case all assignments will also be deleted.

Required permissions

permission:delegate scope ensures that users can only delete a custom role with the same, or a subset of permissions which the user has. For example, if a user does not have required permissions for creating users, they won’t be able to delete a custom role which allows to do that.

Action	Scope
roles:delete	permissions:delegate

Example request

DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=false
Accept: application/json

Query parameters

Param	Type	Required	Description
force	boolean	No	When set to `true`, the role will be deleted with all it’s assignments.
global	boolean	No	A flag indicating if the role is global or not. If set to false, the default org ID of the authenticated user will be used from the request. Refer to the Role scopes for more information.

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role deleted"
}

Status codes

Code	Description
200	Role is deleted.
400	Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403	Access denied
500	Unexpected error. Refer to body and/or server logs for more details.

Create and remove user role assignments

List roles assigned to a user

GET /api/access-control/users/:userId/roles

Lists the roles that have been directly assigned to a given user. The list does not include built-in roles (Viewer, Editor, Admin or Grafana Admin), and it does not include roles that have been inherited from a team.

Required permissions

Action	Scope
users.roles:list	users:id:`<user ID>`

Example request

GET /api/access-control/users/1/roles
Accept: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 4,
        "uid": "6dNwJq57z",
        "name": "fixed:reports:writer",
        "displayName": "Report writer",
        "description": "Create, read, update, or delete all reports and shared report settings.",
        "group": "Reports",
        "updated": "2021-11-19T10:48:00+01:00",
        "created": "2021-11-19T10:48:00+01:00",
        "global": false
    }
]

Status codes

Code	Description
200	Set of assigned roles is returned.
403	Access denied.
500	Unexpected error. Refer to body and/or server logs for more details.

List permissions assigned to a user

GET /api/access-control/users/:userId/permissions

Lists the permissions that a given user has.

Required permissions

Action	Scope
users.permissions:list	users:id:`<user ID>`

Example request

GET /api/access-control/users/1/permissions
Accept: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "action": "ldap.status:read",
        "scope": ""
    },
    {
        "action": "ldap.user:read",
        "scope": ""
    }
]

Status codes

Code	Description
200	Set of assigned permissions is returned.
403	Access denied.
500	Unexpected error. Refer to body and/or server logs for more details.

Add a user role assignment

POST /api/access-control/users/:userId/roles

Assign a role to a specific user.

For bulk updates consider Set user role assignments.

Required permissions

permission:delegate scope ensures that users can only assign roles which have same, or a subset of permissions which the user has. For example, if a user does not have required permissions for creating users, they won’t be able to assign a role which will allow to do that. This is done to prevent escalation of privileges.

Action	Scope
users.roles:add	permissions:delegate

Example request

POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUid": "XvHQJq57z"
}

JSON body schema

Field Name	Data Type	Required	Description
roleUid	string	Yes	UID of the role.
global	boolean	No	A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment.

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the user."
}

Status codes

Code	Description
200	Role is assigned to a user.
403	Access denied.
404	Role not found.
500	Unexpected error. Refer to body and/or server logs for more details.

Remove a user role assignment

DELETE /api/access-control/users/:userId/roles/:roleUID

Revoke a role from a user.

For bulk updates consider Set user role assignments.

Required permissions

permission:delegate scope ensures that users can only unassign roles which have same, or a subset of permissions which the user has. For example, if a user does not have required permissions for creating users, they won’t be able to unassign a role which will allow to do that. This is done to prevent escalation of privileges.

Action	Scope
users.roles:remove	permissions:delegate

Query parameters

Param	Type	Required	Description
global	boolean	No	A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment.

Example request

DELETE /api/access-control/users/1/roles/AFUXBHKnk
Accept: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role removed from user."
}

Status codes

Code	Description
200	Role is unassigned.
403	Access denied.
500	Unexpected error. Refer to body and/or server logs for more details.

Set user role assignments

PUT /api/access-control/users/:userId/roles

Update the user’s role assignments to match the provided set of UIDs. This will remove any assigned roles that aren’t in the request and add roles that are in the set but are not already assigned to the user.

If you want to add or remove a single role, consider using Add a user role assignment or Remove a user role assignment instead.

Required permissions

permission:delegate scope ensures that users can only assign or unassign roles which have same, or a subset of permissions which the user has. For example, if a user does not have required permissions for creating users, they won’t be able to assign or unassign a role which will allow to do that. This is done to prevent escalation of privileges.

Action	Scope
users.roles:add	permissions:delegate
users.roles:remove	permissions:delegate

Example request

PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

JSON body schema

Field Name	Date Type	Required	Description
global	boolean	No	A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request.
roleUids	list	Yes	List of role UIDs.

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "User roles have been updated."
}

Status codes

Code	Description
200	Roles have been assigned.
403	Access denied.
404	Role not found.
500	Unexpected error. Refer to body and/or server logs for more details.

Create and remove built-in role assignments

API set allows to create or remove built-in role assignments and list current assignments.

Get all built-in role assignments

GET /api/access-control/builtin-roles

Gets all built-in role assignments.

Required permissions

Action	Scope
roles.builtin:list	roles:*

Example request

GET /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "Admin": [
        {
            "version": 1,
            "uid": "qQui_LCMk",
            "name": "fixed:users:writer",
            "name": "User writer",
            "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users",
            "global": true,
            "updated": "2021-05-13T16:24:26+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        },
        {
            "version": 1,
            "uid": "PeXmlYjMk",
            "name": "fixed:users:reader",
            "displayName": "User reader",
            "description": "Allows every read action for user organizations and in addition allows to administer user organizations",
            "global": true,
            "updated": "2021-05-13T16:24:26+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        }
    ],
    "Grafana Admin": [
        {
            "version": 1,
            "uid": "qQui_LCMk",
            "name": "fixed:users:writer",
            "displayName": "User writer",
            "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users",
            "global": true,
            "updated": "2021-05-13T16:24:26+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        }
    ]
}

Status codes

Code	Description
200	Built-in role assignments are returned.
403	Access denied
500	Unexpected error. Refer to body and/or server logs for more details.

Create a built-in role assignment

POST /api/access-control/builtin-roles

Creates a new built-in role assignment.

Required permissions

permission:delegate scope ensures that users can only create built-in role assignments with the roles which have same, or a subset of permissions which the user has. For example, if a user does not have required permissions for creating users, they won’t be able to create a built-in role assignment which will allow to do that. This is done to prevent escalation of privileges.

Action	Scope
roles.builtin:add	permissions:delegate

Example request

POST /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json

{
    "roleUid": "LPMGN99Mk",
    "builtinRole": "Grafana Admin",
    "global": false
}

JSON body schema

Field Name	Date Type	Required	Description
roleUid	string	Yes	UID of the role.
builtinRole	boolean	Yes	Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`.
global	boolean	No	A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. Refer to the Built-in role assignments for more information.

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Built-in role grant added"
}

Status codes

Code	Description
200	Role was assigned to built-in role.
400	Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403	Access denied
404	Role not found
500	Unexpected error. Refer to body and/or server logs for more details.

Remove a built-in role assignment

DELETE /api/access-control/builtin-roles/:builtinRole/roles/:roleUID

Deletes a built-in role assignment (for one of Viewer, Editor, Admin, or Grafana Admin) to the role with the provided UID.

Required permissions

permission:delegate scope ensures that users can only remove built-in role assignments with the roles which have same, or a subset of permissions which the user has. For example, if a user does not have required permissions for creating users, they won’t be able to remove a built-in role assignment which allows to do that.

Action	Scope
roles.builtin:remove	permissions:delegate

Example request

DELETE /api/access-control/builtin-roles/Grafana%20Admin/roles/LPMGN99Mk?global=false
Accept: application/json

Query parameters

Param	Type	Required	Description
global	boolean	No	A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. Refer to the Built-in role assignments for more information.

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Built-in role grant removed"
}

Status codes

Code	Description
200	Role was unassigned from built-in role.
400	Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403	Access denied
404	Role not found.
500	Unexpected error. Refer to body and/or server logs for more details.

Folder HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Folder API

Identifier (id) vs unique identifier (uid)

The identifier (id) of a folder is an auto-incrementing numeric value and is only unique per Grafana install.

The unique identifier (uid) of a folder can be used for uniquely identify folders between multiple Grafana installs. It’s automatically generated if not provided when creating a folder. The uid allows having consistent URLs for accessing folders and when syncing folders between multiple Grafana installs. This means that changing the title of a folder will not break any bookmarked links to that folder.

The uid can have a maximum length of 40 characters.

A note about the General folder

The General folder (id=0) is special and is not part of the Folder API which means that you cannot use this API for retrieving information about the General folder.

Get all folders

GET /api/folders

Returns all folders that the authenticated user has permission to view. You can control the maximum number of folders returned through the limit query parameter, the default is 1000. You can also pass the page query parameter for fetching folders from a page other than the first one.

Example Request:

GET /api/folders?limit=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "uid": "nErXDvCkzz",
    "title": "Department ABC"
  },
  {
    "id":2,
    "uid": "k3S1cklGk",
    "title": "Department RND"
  }
]

Get folder by uid

GET /api/folders/:uid

Will return the folder given the folder uid.

Example Request:

GET /api/folders/nErXDvCkzzh HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

Status Codes:

200 – Found
401 – Unauthorized
403 – Access Denied
404 – Folder not found

Create folder

POST /api/folders

Creates a new folder.

Example Request:

POST /api/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "uid": "nErXDvCkzz",
  "title": "Department ABC"
}

JSON Body schema:

uid – Optional unique identifier.
title – The title of the folder.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

Status Codes:

200 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Access Denied
409 - Folder already exists

Update folder

PUT /api/folders/:uid

Updates an existing folder identified by uid.

Example Request:

PUT /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "title":"Department DEF",
  "version": 1
}

JSON Body schema:

uid – Provide another unique identifier than stored to change the unique identifier.
title – The title of the folder.
version – Provide the current version to be able to update the folder. Not needed if overwrite=true.
overwrite – Set to true if you want to overwrite existing folder with newer version.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department DEF",
  "url": "/dashboards/f/nErXDvCkzz/department-def",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

Status Codes:

200 – Updated
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Access Denied
404 – Folder not found
412 – Precondition failed

The 412 status code is used for explaining that you cannot update the folder and why. There can be different reasons for this:

The folder has been changed by someone else, status=version-mismatch

The response body will have the following properties:

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97

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

Delete folder

DELETE /api/folders/:uid

Deletes an existing folder identified by UID along with all dashboards (and their alerts) stored in the folder. This operation cannot be reverted.

If Grafana 8 Alerts are enabled, you can set an optional query parameter forceDeleteRules=false so that requests will fail with 400 (Bad Request) error if the folder contains any Grafana 8 Alerts. However, if this parameter is set to true then it will delete any Grafana 8 Alerts under this folder.

Example Request:

DELETE /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message":"Folder deleted",
  "id": 2
}

Status Codes:

200 – Deleted
401 – Unauthorized
400 – Bad Request
403 – Access Denied
404 – Folder not found

Get folder by id

GET /api/folders/id/:id

Will return the folder identified by id.

Example Request:

GET /api/folders/id/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

Status Codes:

200 – Found
401 – Unauthorized
403 – Access Denied
404 – Folder not found

Folder Permissions HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Folder Permissions API

This API can be used to update/get the permissions for a folder.

Permissions with folderId=-1 are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything.

The permission levels for the permission field:

1 = View
2 = Edit
4 = Admin

Get permissions for a folder

GET /api/folders/:uid/permissions

Gets all existing permissions for the folder with the given uid.

Example request:

GET /api/folders/nErXDvCkzz/permissions HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 551

[
  {
    "id": 1,
    "folderId": -1,
    "created": "2017-06-20T02:00:00+02:00",
    "updated": "2017-06-20T02:00:00+02:00",
    "userId": 0,
    "userLogin": "",
    "userEmail": "",
    "teamId": 0,
    "team": "",
    "role": "Viewer",
    "permission": 1,
    "permissionName": "View",
    "uid": "nErXDvCkzz",
    "title": "",
    "slug": "",
    "isFolder": false,
    "url": ""
  },
  {
    "id": 2,
    "dashboardId": -1,
    "created": "2017-06-20T02:00:00+02:00",
    "updated": "2017-06-20T02:00:00+02:00",
    "userId": 0,
    "userLogin": "",
    "userEmail": "",
    "teamId": 0,
    "team": "",
    "role": "Editor",
    "permission": 2,
    "permissionName": "Edit",
    "uid": "",
    "title": "",
    "slug": "",
    "isFolder": false,
    "url": ""
  }
]

Status Codes:

200 - Ok
401 - Unauthorized
403 - Access denied
404 - Folder not found

Update permissions for a folder

POST /api/folders/:uid/permissions

Updates permissions for a folder. This operation will remove existing permissions if they’re not included in the request.

Example request:

POST /api/folders/nErXDvCkzz/permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
  "items": [
    {
      "role": "Viewer",
      "permission": 1
    },
    {
      "role": "Editor",
      "permission": 2
    },
    {
      "teamId": 1,
      "permission": 1
    },
    {
      "userId": 11,
      "permission": 4
    }
  ]
}

JSON body schema:

items - The permission items to add/update. Items that are omitted from the list will be removed.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35

{"message":"Folder permissions updated","id":1,"title":"Department ABC"}

Status Codes:

200 - Ok
401 - Unauthorized
403 - Access denied
404 - Dashboard not found

Folder/Dashboard Search HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Folder/Dashboard Search API

Search folders and dashboards

GET /api/search/

Query parameters:

query – Search Query
tag – List of tags to search for
type – Type to search for, dash-folder or dash-db
dashboardIds – List of dashboard id’s to search for
folderIds – List of folder id’s to search in for dashboards
starred – Flag indicating if only starred Dashboards should be returned
limit – Limit the number of returned results (max is 5000; default is 1000)
page – Use this parameter to access hits beyond limit. Numbering starts at 1. limit param acts as page size. Only available in Grafana v6.2+.

Example request for retrieving folders and dashboards of the general folder:

GET /api/search?folderIds=0&query=&starred=false HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response for retrieving folders and dashboards of the general folder:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 163,
    "uid": "000000163",
    "title": "Folder",
    "url": "/dashboards/f/000000163/folder",
    "type": "dash-folder",
    "tags": [],
    "isStarred": false,
    "uri":"db/folder" // deprecated in Grafana v5.0
  },
  {
    "id":1,
    "uid": "cIBgcSjkk",
    "title":"Production Overview",
    "url": "/d/cIBgcSjkk/production-overview",
    "type":"dash-db",
    "tags":[prod],
    "isStarred":true,
    "uri":"db/production-overview" // deprecated in Grafana v5.0
  }
]

Example request searching for dashboards:

GET /api/search?query=Production%20Overview&starred=true&tag=prod HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response searching for dashboards:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "uid": "cIBgcSjkk",
    "title":"Production Overview",
    "url": "/d/cIBgcSjkk/production-overview",
    "type":"dash-db",
    "tags":[prod],
    "isStarred":true,
    "folderId": 2,
    "folderUid": "000000163",
    "folderTitle": "Folder",
    "folderUrl": "/dashboards/f/000000163/folder",
    "uri":"db/production-overview" // deprecated in Grafana v5.0
  }
]

HTTP Preferences API

Sat, 04 Apr 2026 12:26:57 +0000

User and Org Preferences API

Keys:

theme - One of: light, dark, or an empty string for the default theme
homeDashboardId - The numerical :id of a favorited dashboard, default: 0
timezone - One of: utc, browser, or an empty string for the default

Omitting a key will cause the current value to be replaced with the system default value.

Get Current User Prefs

GET /api/user/preferences

Example Request:

GET /api/user/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"theme":"","homeDashboardId":0,"timezone":""}

Update Current User Prefs

PUT /api/user/preferences

Example Request:

PUT /api/user/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "theme": "",
  "homeDashboardId":0,
  "timezone":"utc"
}

Example Response:

HTTP/1.1 200
Content-Type: text/plain; charset=utf-8

{"message":"Preferences updated"}

Get Current Org Prefs

GET /api/org/preferences

Example Request:

GET /api/org/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"theme":"","homeDashboardId":0,"timezone":""}

Update Current Org Prefs

PUT /api/org/preferences

Example Request:

PUT /api/org/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "theme": "",
  "homeDashboardId":0,
  "timezone":"utc"
}

Example Response:

HTTP/1.1 200
Content-Type: text/plain; charset=utf-8

{"message":"Preferences updated"}

HTTP Snapshot API

Sat, 04 Apr 2026 12:26:57 +0000

Snapshot API

Create new snapshot

POST /api/snapshots

Example Request:

    POST /api/snapshots HTTP/1.1
    Accept: application/json
    Content-Type: application/json
    Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    {
      "dashboard": {
        "editable":false,
        "hideControls":true,
        "nav":[
        {
          "enable":false,
        "type":"timepicker"
        }
        ],
        "rows": [
          {

          }
        ],
        "style":"dark",
        "tags":[],
        "templating":{
          "list":[
          ]
        },
        "time":{
        },
        "timezone":"browser",
        "title":"Home",
        "version":5
        },
      "expires": 3600
    }

JSON Body schema:

dashboard – Required. The complete dashboard model.
name – Optional. snapshot name
expires - Optional. When the snapshot should expire in seconds. 3600 is 1 hour, 86400 is 1 day. Default is never to expire.
external - Optional. Save the snapshot on an external server rather than locally. Default is false.
key - Optional. Define the unique key. Required if external is true.
deleteKey - Optional. Unique key used to delete the snapshot. It is different from the key so that only the creator can delete the snapshot. Required if external is true.

Note: When creating a snapshot using the API, you have to provide the full dashboard payload including the snapshot data. This endpoint is designed for the Grafana UI.

Example Response:

    HTTP/1.1 200
    Content-Type: application/json
    {
      "deleteKey":"XXXXXXX",
      "deleteUrl":"myurl/api/snapshots-delete/XXXXXXX",
      "key":"YYYYYYY",
      "url":"myurl/dashboard/snapshot/YYYYYYY",
      "id": 1
    }

Keys:

deleteKey – Key generated to delete the snapshot
key – Key generated to share the dashboard

Get list of Snapshots

GET /api/dashboard/snapshots

Query parameters:

query – Search Query
limit – Limit the number of returned results

Example Request:

GET /api/dashboard/snapshots HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":8,
    "name":"Home",
    "key":"YYYYYYY",
    "orgId":1,
    "userId":1,
    "external":false,
    "externalUrl":"",
    "expires":"2200-13-32T25:23:23+02:00",
    "created":"2200-13-32T28:24:23+02:00",
    "updated":"2200-13-32T28:24:23+02:00"
  }
]

Get Snapshot by Key

GET /api/snapshots/:key

Example Request:

GET /api/snapshots/YYYYYYY HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "meta":{
    "isSnapshot":true,
    "type":"snapshot",
    "canSave":false,
    "canEdit":false,
    "canStar":false,
    "slug":"",
    "expires":"2200-13-32T25:23:23+02:00",
    "created":"2200-13-32T28:24:23+02:00"
  },
  "dashboard": {
    "editable":false,
    "hideControls":true,
    "nav": [
      {
        "enable":false,
        "type":"timepicker"
      }
    ],
    "rows": [
      {

      }
    ],
    "style":"dark",
    "tags":[],
    "templating":{
      "list":[
      ]
    },
    "time":{
    },
    "timezone":"browser",
    "title":"Home",
    "version":5
  }
}

Delete Snapshot by Key

DELETE /api/snapshots/:key

Example Request:

DELETE /api/snapshots/YYYYYYY HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Snapshot deleted. It might take an hour before it's cleared from any CDN caches.", "id": 1}

Delete Snapshot by deleteKey

This API call can be used without authentication by using the secret delete key for the snapshot.

GET /api/snapshots-delete/:deleteKey

Example Request:

GET /api/snapshots-delete/XXXXXXX HTTP/1.1
Accept: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Snapshot deleted. It might take an hour before it's cleared from any CDN caches.", "id": 1}

Library Element HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Library Element API

Identifier (id) vs unique identifier (uid)

The identifier (ID) of a library element is an auto-incrementing numeric value that is unique per Grafana install.

The unique identifier (UID) of a library element uniquely identifies library elements between multiple Grafana installs. It’s automatically generated unless you specify it during library element creation. The UID provides consistent URLs for accessing library elements and when syncing library elements between multiple Grafana installs.

The maximum length of a UID is 40 characters.

Get all library elements

GET /api/library-elements

Returns a list of all library elements the authenticated user has permission to view. Use the perPage query parameter to control the maximum number of library elements returned; the default limit is 100. You can also use the page query parameter to fetch library elements from any page other than the first one.

Query parameters:

searchString – Part of the name or description searched for.
kind – Kind of element to search for. Use 1 for library panels or 2 for library variables.
sortDirection – Sort order of elements. Use alpha-asc for ascending and alpha-desc for descending sort order.
typeFilter – A comma separated list of types to filter the elements by.
excludeUid – Element UID to exclude from search results.
folderFilter – A comma separated list of folder ID(s) to filter the elements by.
perPage – The number of results per page; default is 100.
page – The page for a set of records, given that only perPage records are returned at a time. Numbering starts at 1.

Example Request:

GET /api/library-elements?perPage=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "result": {
     "totalCount": 15,
     "page": 1,
     "perPage": 10
     "elements": [
        {
            "id": 25,
            "orgId": 1,
            "folderId": 0,
            "uid": "V--OrYHnz",
            "name": "API docs Example",
            "kind": 1,
            "type": "text",
            "description": "",
            "model": {...},
            "version": 1,
            "meta": {
                "folderName": "General",
                "folderUid": "",
                "connectedDashboards": 1,
                "created": "2021-09-27T09:56:17+02:00",
                "updated": "2021-09-27T09:56:17+02:00",
                "createdBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                },
                "updatedBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                }
            }
        },
        {...}
        {...}
     ],
  }
}

Status Codes:

200 – Found
401 – Unauthorized

Get library element by uid

GET /api/library-elements/:uid

Returns a library element with the given UID.

Example Request:

GET /api/library-elements/V--OrYHnz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
      "id": 25,
      "orgId": 1,
      "folderId": 0,
      "uid": "V--OrYHnz",
      "name": "API docs Example",
      "kind": 1,
      "type": "text",
      "description": "",
      "model": {...},
      "version": 1,
      "meta": {
          "folderName": "General",
          "folderUid": "",
          "connectedDashboards": 1,
          "created": "2021-09-27T09:56:17+02:00",
          "updated": "2021-09-27T09:56:17+02:00",
          "createdBy": {
              "id": 1,
              "name": "admin",
              "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
          },
          "updatedBy": {
              "id": 1,
              "name": "admin",
              "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
          }
      }
   }
}

Status Codes:

200 – Found
401 – Unauthorized
404 – Library element not found

Get library element by name

GET /api/library-elements/name/:name

Returns a library element with the given name

Example Request:

GET /api/library-elements/name/API docs Example HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "result": [
        {
            "id": 25,
            "orgId": 1,
            "folderId": 0,
            "uid": "V--OrYHnz",
            "name": "API docs Example",
            "kind": 1,
            "type": "text",
            "description": "",
            "model": {...},
            "version": 1,
            "meta": {
                "folderName": "General",
                "folderUid": "",
                "connectedDashboards": 1,
                "created": "2021-09-27T09:56:17+02:00",
                "updated": "2021-09-27T09:56:17+02:00",
                "createdBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                },
                "updatedBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                }
            }
        }
    ]
}

Status Codes:

200 – Found
401 – Unauthorized
404 – Library element not found

Get library element connections

GET /api/library-elements/:uid/connections

Returns a list of connections for a library element based on the UID specified.

Example Request:

GET /api/library-elements/V--OrYHnz/connections HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "result": [
        {
            "id": 148,
            "kind": 1,
            "elementId": 25,
            "connectionId": 527,
            "created": "2021-09-27T10:00:07+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    ]
}

Status Codes:

200 – Found
401 – Unauthorized
404 – Library element not found

Create library element

POST /api/library-elements

Creates a new library element.

JSON Body schema:

folderId – Optional, the ID of the folder where the library element is stored.
name – Optional, the name of the library element.
model – The JSON model for the library element.
kind – Kind of element to create, Use 1 for library panels or 2 for library variables.
uid – Optional, the unique identifier.

Example Request:

POST /api/library-elements HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "uid": "nErXDvCkzz",
  "folderId": 0,
  "name": "Example library panel",
  "model": {...},
  "kind": 1
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "id": 28,
        "orgId": 1,
        "folderId": 0,
        "uid": "nErXDvCkzz",
        "name": "Example library panel",
        "kind": 1,
        "type": "",
        "description": "",
        "model": {...},
        "version": 1,
        "meta": {
            "folderName": "General",
            "folderUid": "",
            "connectedDashboards": 0,
            "created": "2021-09-30T09:14:22.378307+02:00",
            "updated": "2021-09-30T09:14:22.378307+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            },
            "updatedBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    }
}

Status Codes:

200 – Created
400 – Errors (for example, name or UID already exists, invalid JSON, missing or invalid fields, and so on).
401 – Unauthorized
403 – Access denied

Update library element

PATCH /api/library-elements/:uid

Updates an existing library element identified by uid.

JSON Body schema:

folderId – ID of the folder where the library element is stored.
name – Name of the library element.
model – The JSON model for the library element.
kind – Kind of element to create. Use 1 for library panels or 2 for library variables.
version – Version of the library element you are updating.
uid – Optional, the unique identifier.

Example Request:

PATCH /api/library-elements/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name": "Renamed library panel",
  "kind": 1,
  "version": 1
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "id": 28,
        "orgId": 1,
        "folderId": 0,
        "uid": "nErXDvCkzz",
        "name": "Renamed library panel",
        "kind": 1,
        "type": "",
        "description": "",
        "model": {
            "description": "",
            "type": ""
        },
        "version": 2,
        "meta": {
            "folderName": "General",
            "folderUid": "",
            "connectedDashboards": 0,
            "created": "2021-09-30T09:14:22+02:00",
            "updated": "2021-09-30T09:25:57.697214+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            },
            "updatedBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    }
}

Status Codes:

200 – Updated
400 – Errors (for example, name or UID already exists, invalid JSON, missing or invalid fields, and so on).
401 – Unauthorized
403 – Access denied
404 – Library element not found
412 – Version mismatch

Delete library element

DELETE /api/library-elements/:uid

Deletes an existing library element as specified by the UID. This operation cannot be reverted.

Note: You cannot delete a library element that is connected. This operation cannot be reverted.

Example Request:

DELETE /api/library-elements/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
    "message": "Library element deleted",
    "id": 28
}

Status Codes:

200 – Deleted
401 – Unauthorized
400 – Bad request
403 – Access denied
404 – Library element not found

Licensing HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Enterprise License API

Licensing is only available in Grafana Enterprise. Read more about Grafana Enterprise.

If you are running Grafana Enterprise and have Fine-grained access control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required.

Check license availability

Note: Available in Grafana Enterprise v7.4+.

GET /api/licensing/check

Checks if a valid license is available.

Required permissions

See note in the introduction for an explanation.

Action	Scope
licensing:read	n/a

Examples

Example request:

GET /api/licensing/check
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4

true

Status codes:

200 - OK

Manually force license refresh

Note: Available in Grafana Enterprise v7.4+.

POST /api/licensing/token/renew

Manually ask license issuer for a new token.

Required permissions

See note in the introduction for an explanation.

Action	Scope
licensing:update	n/a

Examples

Example request:

POST /api/licensing/token/renew
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 357

{
  "jti":"2",
  "iss":"https://grafana.com",
  "sub":"https://play.grafana.org/"
  "lid":"1",
  "included_admins":5,
  "included_viewers":10,
  "lic_exp_warn_days":30,
  "tok_exp_warn_days":2,
  "update_days":1,
  "prod":["grafana-enterprise"],
  "company":"Grafana Labs"
}

The response is a JSON blob available for debugging purposes. The available fields may change at any time without any prior notice.

Status Codes:

200 - OK
401 - Unauthorized
403 - Access denied

Remove license from database

Note: Available in Grafana Enterprise v7.4+.

DELETE /api/licensing/token

Removes the license stored in the Grafana database.

Required permissions

See note in the introduction for an explanation.

Action	Scope
licensing:delete	n/a

Examples

Example request:

DELETE /api/licensing/token
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{"instance": "http://play.grafana.org/"}

JSON Body schema:

instance – Root URL for the instance for which the license should be deleted. Required.

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 2

{}

Status codes:

202 - Accepted, license removed or did not exist.
401 - Unauthorized
403 - Access denied
422 - Unprocessable entity, incorrect instance name provided.

Organization HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Organization API

The Organization HTTP API is divided in two resources, /api/org (current organization) and /api/orgs (admin organizations). One big difference between these are that the admin of all organizations API only works with basic authentication, see Admin Organizations API for more information.

If you are running Grafana Enterprise and have Fine-grained access control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required.

Current Organization API

Get current Organization

GET /api/org/

Required permissions

See note in the introduction for an explanation.

Action	Scope
orgs:read	N/A

Example Request:

GET /api/org/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "name":"Main Org."
}

Get all users within the current organization

GET /api/org/users

Returns all org users within the current organization. Accessible to users with org admin role.

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users:read	users:*

Example Request:

GET /api/org/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId": 1,
    "userId": 1,
    "email": "admin@localhost",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
    "login": "admin",
    "role": "Admin",
    "lastSeenAt": "2019-08-09T11:02:49+02:00",
    "lastSeenAtAge": "< 1m"
  }
]

Get all users within the current organization (lookup)

GET /api/org/users/lookup

Returns all org users within the current organization, but with less detailed information. Accessible to users with org admin role, admin in any folder or admin of any team. Mainly used by Grafana UI for providing list of users when adding team members and when editing folder/dashboard permissions.

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users:read	users:*

Example Request:

GET /api/org/users/lookup HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "userId": 1,
    "login": "admin",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
  }
]

Updates the given user

PATCH /api/org/users/:userId

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users.role:update	users:*

Example Request:

PATCH /api/org/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "role": "Viewer",
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization user updated"}

Delete user in current organization

DELETE /api/org/users/:userId

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users:remove	users:*

Example Request:

DELETE /api/org/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"User removed from organization"}

Update current Organization

PUT /api/org

Required permissions

See note in the introduction for an explanation.

Action	Scope
orgs:write	N/A

Example Request:

PUT /api/org HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name":"Main Org."
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization updated"}

Add a new user to the current organization

POST /api/org/users

Adds a global user to the current organization.

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users:add	users:*

Example Request:

POST /api/org/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "role": "Admin",
  "loginOrEmail": "admin"
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"User added to organization","userId":1}

Admin Organizations API

The Admin Organizations HTTP API does not currently work with an API Token. API Tokens are currently only linked to an organization and an organization role. They cannot be given the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user must have the Grafana Admin permission (The default admin user is called admin and has permission to use this API).

Get Organization by Id

GET /api/orgs/:orgId

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope
orgs:read	N/A

Example Request:

GET /api/orgs/1 HTTP/1.1
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

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

Get Organization by Name

GET /api/orgs/name/:orgName

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope	Note
orgs:read	N/A	Needs to be assigned globally.

Example Request:

GET /api/orgs/name/Main%20Org%2E HTTP/1.1
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

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

Create Organization

POST /api/orgs

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope	Note
orgs:create	N/A	Needs to be assigned globally.

Example Request:

POST /api/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "name":"New Org."
}

Note: The api will work in the following two ways

Need to set GF_USERS_ALLOW_ORG_CREATE=true
Set the config value users.allow_org_create to true in ini file

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "orgId":"1",
  "message":"Organization created"
}

Search all Organizations

GET /api/orgs?perpage=10&page=1

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope	Note
orgs:read	N/A	Needs to be assigned globally.

Example Request:

GET /api/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json

Note: The api will only work when you pass the admin name and password to the request HTTP URL, like http://admin:admin@localhost:3000/api/orgs

Default value for the perpage parameter is 1000 and for the page parameter is 0.

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "name":"Main Org."
  }
]

Update Organization

PUT /api/orgs/:orgId

Update Organization, fields Address 1, Address 2, City are not implemented yet. Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope
orgs:write	N/A

Example Request:

PUT /api/orgs/1 HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "name":"Main Org 2."
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization updated"}

Delete Organization

DELETE /api/orgs/:orgId

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope
orgs:delete	N/A

Example Request:

DELETE /api/orgs/1 HTTP/1.1
Accept: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization deleted"}

Get Users in Organization

GET /api/orgs/:orgId/users

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users:read	users:*

Example Request:

GET /api/orgs/1/users HTTP/1.1
Accept: application/json
Content-Type: application/json

Note: The api will only work when you pass the admin name and password to the request HTTP URL, like http://admin:admin@localhost:3000/api/orgs/1/users

Example Response:

HTTP/1.1 200
Content-Type: application/json
[
  {
    "orgId":1,
    "userId":1,
    "email":"admin@mygraf.com",
    "login":"admin",
    "role":"Admin"
  }
]

Add User in Organization

POST /api/orgs/:orgId/users

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users:add	users:*

Example Request:

POST /api/orgs/1/users HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "loginOrEmail":"user",
  "role":"Viewer"
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"User added to organization", "userId": 1}

Update Users in Organization

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

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users.role:update	users:*

Example Request:

PATCH /api/orgs/1/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "role":"Admin"
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization user updated"}

Delete User in Organization

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

Only works with Basic Authentication (username and password), see introduction.

Required permissions

See note in the introduction for an explanation.

Action	Scope
org.users:remove	users:*

Example Request:

DELETE /api/orgs/1/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"User removed from organization"}

Other HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Frontend Settings API

Get Settings

GET /api/frontend/settings

Example Request:

GET /api/frontend/settings HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "allowOrgCreate":true,
  "appSubUrl":"",
  "buildInfo":{
    "buildstamp":xxxxxx,
    "commit":"vyyyy",
    "version":"zzzzz"
  },
  "datasources":{
    "datasourcename":{
      "index":"grafana-dash",
      "meta":{
        "annotations":true,
        "module":"plugins/datasource/grafana/datasource",
        "name":"Grafana",
        "partials":{
          "annotations":"app/plugins/datasource/grafana/partials/annotations.editor.html",
          "config":"app/plugins/datasource/grafana/partials/config.html"
        },
        "pluginType":"datasource",
        "serviceName":"Grafana",
        "type":"grafanasearch"
      }
    }
  },
  "defaultDatasource": "Grafana"
}

GET /api/login/ping

Example Request:

GET /api/login/ping HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message": "Logged in"}

Health API

Returns health information about Grafana

GET /api/health

Example Request

GET /api/health
Accept: application/json

Example Response:

HTTP/1.1 200 OK

{
  "commit": "087143285",
  "database": "ok",
  "version": "5.1.3"
}

Playlist HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Playlist API

Search Playlist

GET /api/playlists

Get all existing playlist for the current organization using pagination

Example Request:

GET /api/playlists HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Querystring Parameters:

These parameters are used as querystring parameters.

query - Limit response to playlist having a name like this value.
limit - Limit response to X number of playlist.

Example Response:

HTTP/1.1 200
Content-Type: application/json
[
  {
    "id": 1,
    "name": "my playlist",
    "interval": "5m"
  }
]

Get one playlist

GET /api/playlists/:id

Example Request:

GET /api/playlists/1 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json
{
  "id" : 1,
  "name": "my playlist",
  "interval": "5m",
  "orgId": "my org",
  "items": [
    {
      "id": 1,
      "playlistId": 1,
      "type": "dashboard_by_id",
      "value": "3",
      "order": 1,
      "title":"my third dashboard"
    },
    {
      "id": 2,
      "playlistId": 1,
      "type": "dashboard_by_tag",
      "value": "myTag",
      "order": 2,
      "title":"my other dashboard"
    }
  ]
}

Get Playlist items

GET /api/playlists/:id/items

Example Request:

GET /api/playlists/1/items HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json
[
  {
    "id": 1,
    "playlistId": 1,
    "type": "dashboard_by_id",
    "value": "3",
    "order": 1,
    "title":"my third dashboard"
  },
  {
    "id": 2,
    "playlistId": 1,
    "type": "dashboard_by_tag",
    "value": "myTag",
    "order": 2,
    "title":"my other dashboard"
  }
]

Get Playlist dashboards

GET /api/playlists/:id/dashboards

Example Request:

GET /api/playlists/1/dashboards HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json
[
  {
    "id": 3,
    "title": "my third dashboard",
    "order": 1,
  },
  {
    "id": 5,
    "title":"my other dashboard"
    "order": 2,

  }
]

Create a playlist

POST /api/playlists/

Example Request:

PUT /api/playlists/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  {
    "name": "my playlist",
    "interval": "5m",
    "items": [
      {
        "type": "dashboard_by_id",
        "value": "3",
        "order": 1,
        "title":"my third dashboard"
      },
      {
        "type": "dashboard_by_tag",
        "value": "myTag",
        "order": 2,
        "title":"my other dashboard"
      }
    ]
  }

Example Response:

HTTP/1.1 200
Content-Type: application/json
  {
    "id": 1,
    "name": "my playlist",
    "interval": "5m"
  }

Update a playlist

PUT /api/playlists/:id

Example Request:

PUT /api/playlists/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  {
    "name": "my playlist",
    "interval": "5m",
    "items": [
      {
        "playlistId": 1,
        "type": "dashboard_by_id",
        "value": "3",
        "order": 1,
        "title":"my third dashboard"
      },
      {
        "playlistId": 1,
        "type": "dashboard_by_tag",
        "value": "myTag",
        "order": 2,
        "title":"my other dashboard"
      }
    ]
  }

Example Response:

HTTP/1.1 200
Content-Type: application/json
{
  "id" : 1,
  "name": "my playlist",
  "interval": "5m",
  "orgId": "my org",
  "items": [
    {
      "id": 1,
      "playlistId": 1,
      "type": "dashboard_by_id",
      "value": "3",
      "order": 1,
      "title":"my third dashboard"
    },
    {
      "id": 2,
      "playlistId": 1,
      "type": "dashboard_by_tag",
      "value": "myTag",
      "order": 2,
      "title":"my other dashboard"
    }
  ]
}

Delete a playlist

DELETE /api/playlists/:id

Example Request:

DELETE /api/playlists/1 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json
{}

Query History HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Query history API

This API can be used to add queries to Query history. It requires that the user is logged in and that Query history feature is enabled in config file.

Add query to Query history

POST /api/query-history

Adds query to query history.

Example request:

POST /api/query-history HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
  "dataSourceUid": "PE1C5CBDA0504A6A3",
  "queries": [
    {
        "refId": "A",
        "key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
        "scenarioId": "csv_content",
        "datasource": {
            "type": "testdata",
            "uid": "PD8C576611E62080A"
        }
    }
]
}

JSON body schema:

datasourceUid – Data source uid.
queries – JSON of query or queries.

Example response:

HTTP/1.1 200
Content-Type: application/json
{
  "message": "Query successfully added to query history",
}

Status codes:

200 – OK
500 – Errors (invalid JSON, missing or invalid fields)

Reporting API

Sat, 04 Apr 2026 12:26:57 +0000

Reporting API

This API allows you to interact programmatically with the Reporting feature.

Reporting is only available in Grafana Enterprise. Read more about Grafana Enterprise.

If you have Fine-grained access Control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required.

Send a report

Only available in Grafana Enterprise v7.0+.

This API endpoint is experimental and may be deprecated in a future release. On deprecation, a migration strategy will be provided and the endpoint will remain functional until the next major release of Grafana.

POST /api/reports/email

Generate and send a report. This API waits for the report to be generated before returning. We recommend that you set the client’s timeout to at least 60 seconds.

Required permissions

See note in the introduction for an explanation.

Action	Scope
reports:send	n/a

Example request

POST /api/reports/email HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "id":"3",
  "useEmailsFromReport": true
}

JSON Body Schema

Field name	Data type	Description
id	string	ID of the report to send. It is the same as in the URL when editing a report, not to be confused with the ID of the dashboard. Required.
emails	string	Comma-separated list of emails to which to send the report to. Overrides the emails from the report. Required if useEmailsFromReport is not present.
useEmailsFromReport	boolean	Send the report to the emails specified in the report. Required if emails is not present.

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 29

{"message":"Report was sent"}

Status Codes

Code	Description
200	Report was sent.
400	Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
401	Authentication failed, refer to Authentication API.
403	User is authenticated but is not authorized to generate the report.
404	Report not found.
500	Unexpected error or server misconfiguration. Refer to server logs for more details.

Short URL HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Short URL API

Use this API to create shortened URLs. A short URL represents a longer URL containing complex query parameters in a smaller and simpler format.

Create short URL

POST /api/short-urls

Creates a short URL.

Example request:

POST /api/short-urls HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "path": "d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894"
}

JSON body schema:

path – The path to shorten, relative to the Grafana root_url.

Example response:

HTTP/1.1 200
Content-Type: application/json

{
  "uid": AT76wBvGk,
  "url": http://localhost:3000/goto/AT76wBvGk?orgId=1
}

Status codes:

200 – Created
400 – Errors (invalid JSON, missing or invalid fields)

Team HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

Team API

This API can be used to manage Teams and Team Memberships.

Access to these API endpoints is restricted as follows:

All authenticated users are able to view details of teams they are a member of.
Organization Admins are able to manage all teams and team members.
If you enable editors_can_admin configuration flag, then Organization Editors can create teams and manage teams where they are Admin.
- If you enable editors_can_admin configuration flag, Editors can find out whether a team that they are not members of exists by trying to create a team with the same name.

If you are running Grafana Enterprise and have Fine-grained access control enabled, access to endpoints will be controlled by Fine-grained access control permissions. Refer to specific endpoints to understand what permissions are required.

Team Search With Paging

GET /api/teams/search?perpage=50&page=1&query=myteam

GET /api/teams/search?name=myteam

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams:read	teams:*

Example Request:

GET /api/teams/search?perpage=10&page=1&query=mytestteam HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "totalCount": 1,
  "teams": [
    {
      "id": 1,
      "orgId": 1,
      "name": "MyTestTeam",
      "email": "",
      "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398",
      "memberCount": 1
    }
  ],
  "page": 1,
  "perPage": 1000
}

Using the query parameter

Default value for the perpage parameter is 1000 and for the page parameter is 1.

The totalCount field in the response can be used for pagination of the teams list E.g. if totalCount is equal to 100 teams and the perpage parameter is set to 10 then there are 10 pages of teams.

The query parameter is optional and it will return results where the query value is contained in the name field. Query values with spaces need to be URL encoded e.g. query=my%20team.

Using the name parameter

The name parameter returns a single team if the parameter matches the name field.

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied
404 - Team not found (if searching by name)

Get Team By Id

GET /api/teams/:id

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams:read	teams:*

Example Request:

GET /api/teams/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "orgId": 1,
  "name": "MyTestTeam",
  "email": "",
  "created": "2017-12-15T10:40:45+01:00",
  "updated": "2017-12-15T10:40:45+01:00"
}

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied
404 - Team not found

Add Team

The Team name needs to be unique. name is required and email,orgId is optional.

POST /api/teams

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams:create	N/A

Example Request:

POST /api/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "name": "MyTestTeam",
  "email": "email@test.com",
  "orgId": 2
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team created","teamId":2}

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied
409 - Team name is taken

Update Team

There are two fields that can be updated for a team: name and email.

PUT /api/teams/:id

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams:write	teams:*

Example Request:

PUT /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "name": "MyTestTeam",
  "email": "email@test.com"
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team updated"}

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied
404 - Team not found
409 - Team name is taken

Delete Team By Id

DELETE /api/teams/:id

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams:delete	teams:*

Example Request:

DELETE /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team deleted"}

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied
404 - Failed to delete Team. ID not found

Get Team Members

GET /api/teams/:teamId/members

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams.permissions:read	teams:*

Example Request:

GET /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId": 1,
    "teamId": 1,
    "userId": 3,
    "email": "user1@email.com",
    "login": "user1",
    "avatarUrl": "\/avatar\/1b3c32f6386b0185c40d359cdc733a79"
  },
  {
    "orgId": 1,
    "teamId": 1,
    "userId": 2,
    "email": "user2@email.com",
    "login": "user2",
    "avatarUrl": "\/avatar\/cad3c68da76e45d10269e8ef02f8e73e"
  }
]

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied

Add Team Member

POST /api/teams/:teamId/members

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams.permissions:write	teams:*

Example Request:

POST /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "userId": 2
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Member added to Team"}

Status Codes:

200 - Ok
400 - User is already added to this team
401 - Unauthorized
403 - Permission denied
404 - Team not found

Remove Member From Team

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

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams.permissions:write	teams:*

Example Request:

DELETE /api/teams/2/members/3 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team Member removed"}

Status Codes:

200 - Ok
401 - Unauthorized
403 - Permission denied
404 - Team not found/Team member not found

Get Team Preferences

GET /api/teams/:teamId/preferences

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams:read	teams:*

Example Request:

GET /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "theme": "",
  "homeDashboardId": 0,
  "timezone": ""
}

Update Team Preferences

PUT /api/teams/:teamId/preferences

Required permissions

See note in the introduction for an explanation.

Action	Scope
teams:write	teams:*

Example Request:

PUT /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "theme": "dark",
  "homeDashboardId": 39,
  "timezone": "utc"
}

JSON Body Schema:

theme - One of: light, dark, or an empty string for the default theme
homeDashboardId - The numerical :id of a dashboard, default: 0
timezone - One of: utc, browser, or an empty string for the default

Omitting a key will cause the current value to be replaced with the system default value.

Example Response:

HTTP/1.1 200
Content-Type: text/plain; charset=utf-8

{
  "message":"Preferences updated"
}

User HTTP API

Sat, 04 Apr 2026 12:26:57 +0000

User API

If you are running Grafana Enterprise and have Fine-grained access control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required.

Search Users

GET /api/users?perpage=10&page=1

Required permissions

See note in the introduction for an explanation.

Action	Scope
users:read	global:users:*

Example Request:

GET /api/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Default value for the perpage parameter is 1000 and for the page parameter is 1. Requires basic authentication and that the authenticated user is a Grafana Admin.

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 1,
    "name": "Admin",
    "login": "admin",
    "email": "admin@mygraf.com",
    "isAdmin": true,
    "isDisabled": false,
    "lastSeenAt": "2020-04-10T20:29:27+03:00",
    "lastSeenAtAge': "2m",
    "authLabels": ["OAuth"]
  },
  {
    "id": 2,
    "name": "User",
    "login": "user",
    "email": "user@mygraf.com",
    "isAdmin": false,
    "isDisabled": false,
    "lastSeenAt": "2020-01-24T12:38:47+02:00",
    "lastSeenAtAge": "2M",
    "authLabels": []
  }
]

Search Users with Paging

GET /api/users/search?perpage=10&page=1&query=mygraf

Required permissions

See note in the introduction for an explanation.

Action	Scope
users:read	global:users:*

Example Request:

GET /api/users/search?perpage=10&page=1&query=mygraf HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Default value for the perpage parameter is 1000 and for the page parameter is 1. The totalCount field in the response can be used for pagination of the user list E.g. if totalCount is equal to 100 users and the perpage parameter is set to 10 then there are 10 pages of users. The query parameter is optional and it will return results where the query value is contained in one of the name, login or email fields. Query values with spaces need to be URL encoded e.g. query=Jane%20Doe.

Requires basic authentication and that the authenticated user is a Grafana Admin.

Example Response:

HTTP/1.1 200
Content-Type: application/json
{
  "totalCount": 2,
  "users": [
    {
      "id": 1,
      "name": "Admin",
      "login": "admin",
      "email": "admin@mygraf.com",
      "isAdmin": true,
      "isDisabled": false,
      "lastSeenAt": "2020-04-10T20:29:27+03:00",
      "lastSeenAtAge': "2m",
      "authLabels": ["OAuth"]
    },
    {
      "id": 2,
      "name": "User",
      "login": "user",
      "email": "user@mygraf.com",
      "isAdmin": false,
      "isDisabled": false,
      "lastSeenAt": "2020-01-24T12:38:47+02:00",
      "lastSeenAtAge": "2M",
      "authLabels": []
    }
  ],
  "page": 1,
  "perPage": 10
}

Get single user by Id

GET /api/users/:id

Required permissions

See note in the introduction for an explanation.

Action	Scope
users:read	users:*

Example Request:

GET /api/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Requires basic authentication and that the authenticated user is a Grafana Admin.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": "1",
  "email": "user@mygraf.com",
  "name": "admin",
  "login": "admin",
  "theme": "light",
  "orgId": 1,
  "isGrafanaAdmin": true,
  "isDisabled": true,
  "isExternal": false,
  "authLabels": [],
  "updatedAt": "2019-09-09T11:31:26+01:00",
  "createdAt": "2019-09-09T11:31:26+01:00",
  "avatarUrl": ""
}

Get single user by Username(login) or Email

GET /api/users/lookup?loginOrEmail=user@mygraf.com

Required permissions

See note in the introduction for an explanation.

Action	Scope
users:read	global:users:*

Example Request using the email as option:

GET /api/users/lookup?loginOrEmail=user@mygraf.com HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Request using the username as option:

GET /api/users/lookup?loginOrEmail=admin HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Requires basic authentication and that the authenticated user is a Grafana Admin.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "email": "user@mygraf.com",
  "name": "admin",
  "login": "admin",
  "theme": "light",
  "orgId": 1,
  "isGrafanaAdmin": true,
  "isDisabled": false,
  "isExternal": false,
  "authLabels": null,
  "updatedAt": "2019-09-25T14:44:37+01:00",
  "createdAt": "2019-09-25T14:44:37+01:00",
  "avatarUrl":""
}

User Update

PUT /api/users/:id

Required permissions

See note in the introduction for an explanation.

Action	Scope
users:write	users:*

Example Request:

PUT /api/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "email":"user@mygraf.com",
  "name":"User2",
  "login":"user",
  "theme":"light"
}

Requires basic authentication and that the authenticated user is a Grafana Admin.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"User updated"}

Get Organizations for user

GET /api/users/:id/orgs

Required permissions

See note in the introduction for an explanation.

Action	Scope
users:read	users:*

Example Request:

GET /api/users/1/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Requires basic authentication and that the authenticated user is a Grafana Admin.

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId":1,
    "name":"Main Org.",
    "role":"Admin"
  }
]

Get Teams for user

GET /api/users/:id/teams

Required permissions

See note in the introduction for an explanation.

Action	Scope
users.teams:read	users:*

Example Request:

GET /api/users/1/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Requires basic authentication and that the authenticated user is a Grafana Admin.

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "orgId":1,
    "name":"team1",
    "email":"",
    "avatarUrl":"/avatar/3fcfe295eae3bcb67a49349377428a66",
    "memberCount":1
  }
]

User

Actual User

GET /api/user

Example Request:

GET /api/user HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Requires basic authentication.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "email":"admin@mygraf.com",
  "name":"Admin",
  "login":"admin",
  "theme":"light",
  "orgId":1,
  "isGrafanaAdmin":true,
  "isDisabled":false
  "isExternal": false,
  "authLabels": [],
  "updatedAt": "2019-09-09T11:31:26+01:00",
  "createdAt": "2019-09-09T11:31:26+01:00",
  "avatarUrl": ""
}

Change Password

PUT /api/user/password

Changes the password for the user. Requires basic authentication.

Example Request:

PUT /api/user/password HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "oldPassword": "old_password",
  "newPassword": "new_password"
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"User password changed"}

Change Password with a Script

If you need to change a password with a script, here is an example of changing the Admin password using curl with basic auth:

curl -X PUT -H "Content-Type: application/json" -d '{
  "oldPassword": "oldpass",
  "newPassword": "newpass",
  "confirmNew": "newpass"
}' http://admin:oldpass@<your_grafana_host>:3000/api/user/password

Switch user context for a specified user

POST /api/users/:userId/using/:organizationId

Switch user context to the given organization. Requires basic authentication and that the authenticated user is a Grafana Admin.

Example Request:

POST /api/users/7/using/2 HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Active organization changed"}

Switch user context for signed in user

POST /api/user/using/:organizationId

Switch user context to the given organization.

Example Request:

POST /api/user/using/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Active organization changed"}

Organizations of the actual User

GET /api/user/orgs

Return a list of all organizations of the current user. Requires basic authentication.

Example Request:

GET /api/user/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId":1,
    "name":"Main Org.",
    "role":"Admin"
  }
]

Teams that the actual User is member of

GET /api/user/teams

Return a list of all teams that the current user is member of.

Example Request:

GET /api/user/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 1,
    "orgId": 1,
    "name": "MyTestTeam",
    "email": "",
    "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398",
    "memberCount": 1
  }
]

Star a dashboard

POST /api/user/stars/dashboard/:dashboardId

Stars the given Dashboard for the actual user.

Example Request:

POST /api/user/stars/dashboard/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Dashboard starred!"}

Unstar a dashboard

DELETE /api/user/stars/dashboard/:dashboardId

Deletes the starring of the given Dashboard for the actual user.

Example Request:

DELETE /api/user/stars/dashboard/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{"message":"Dashboard unstarred"}

Auth tokens of the actual User

GET /api/user/auth-tokens

Return a list of all auth tokens (devices) that the actual user currently have logged in from.

Example Request:

GET /api/user/auth-tokens HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 361,
    "isActive": true,
    "clientIp": "127.0.0.1",
    "browser": "Chrome",
    "browserVersion": "72.0",
    "os": "Linux",
    "osVersion": "",
    "device": "Other",
    "createdAt": "2019-03-05T21:22:54+01:00",
    "seenAt": "2019-03-06T19:41:06+01:00"
  },
  {
    "id": 364,
    "isActive": false,
    "clientIp": "127.0.0.1",
    "browser": "Mobile Safari",
    "browserVersion": "11.0",
    "os": "iOS",
    "osVersion": "11.0",
    "device": "iPhone",
    "createdAt": "2019-03-06T19:41:19+01:00",
    "seenAt": "2019-03-06T19:41:21+01:00"
  }
]

Revoke an auth token of the actual User

POST /api/user/revoke-auth-token

Revokes the given auth token (device) for the actual user. User of issued auth token (device) will no longer be logged in and will be required to authenticate again upon next activity.

Example Request:

POST /api/user/revoke-auth-token HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "authTokenId": 364
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "User auth token revoked"
}