Dashboards API

Create, read, update, and delete dashboards via the API

Dashboards API

The Dashboards API provides endpoints for managing Grafana dashboards programmatically.

Get Dashboard by UID

Retrieve a dashboard by its unique identifier (UID).

cURL

curl -X GET http://localhost:3000/api/dashboards/uid/nHz3SXiiz \
  -u admin:admin

{
  "meta": {
    "isStarred": false,
    "slug": "my-dashboard",
    "type": "db",
    "canSave": true,
    "canEdit": true,
    "canAdmin": true,
    "canDelete": true,
    "created": "2021-06-01T10:00:00Z",
    "updated": "2021-06-01T12:00:00Z",
    "version": 1,
    "folderUid": "folder-uid",
    "folderTitle": "My Folder"
  },
  "dashboard": {
    "uid": "nHz3SXiiz",
    "title": "My Dashboard",
    "panels": [],
    "schemaVersion": 38
  }
}

uid · string · required

Dashboard unique identifier

meta · object

Dashboard metadata

meta.isStarred · boolean

Whether the dashboard is starred by the current user

meta.canSave · boolean

Whether the current user can save the dashboard

meta.version · integer

Dashboard version number

meta.folderUid · string

UID of the folder containing this dashboard

dashboard · object

Dashboard JSON model

Create/Update Dashboard

Create a new dashboard or update an existing one.

cURL

curl -X POST http://localhost:3000/api/dashboards/db \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "dashboard": {
      "title": "My Dashboard",
      "tags": ["templated"],
      "timezone": "browser",
      "schemaVersion": 38,
      "panels": []
    },
    "folderUid": "folder-uid",
    "message": "Initial version",
    "overwrite": false
  }'

{
  "status": "success",
  "slug": "my-dashboard",
  "version": 1,
  "id": 1,
  "uid": "nHz3SXiiz",
  "url": "/d/nHz3SXiiz/my-dashboard",
  "folderUid": "folder-uid"
}

dashboard · object · required

Dashboard JSON model

dashboard.title · string · required

Dashboard title

dashboard.uid · string

Dashboard UID (auto-generated if not provided)

dashboard.panels · array

Array of panel configurations

folderUid · string

UID of the folder to save the dashboard in

message · string

Commit message for this dashboard version

overwrite · boolean · default: "false"

Whether to overwrite existing dashboard with same UID

status · string

Operation status (“success”)

uid · string

Dashboard UID

url · string

Relative URL to access the dashboard

version · integer

New version number

Delete Dashboard by UID

Delete a dashboard by its UID.

cURL

curl -X DELETE http://localhost:3000/api/dashboards/uid/nHz3SXiiz \
  -u admin:admin

{
  "title": "My Dashboard",
  "message": "Dashboard My Dashboard deleted",
  "uid": "nHz3SXiiz"
}

uid · string · required

Dashboard unique identifier

title · string

Title of the deleted dashboard

message · string

Deletion confirmation message

Get Dashboard Versions

Retrieve all versions of a dashboard.

cURL

curl -X GET http://localhost:3000/api/dashboards/uid/nHz3SXiiz/versions \
  -u admin:admin

{
  "versions": [
    {
      "id": 1,
      "dashboardId": 1,
      "dashboardUid": "nHz3SXiiz",
      "version": 1,
      "created": "2021-06-01T10:00:00Z",
      "createdBy": "admin",
      "message": "Initial save"
    }
  ]
}

uid · string · required

Dashboard unique identifier

limit · integer

Maximum number of versions to return

start · integer

Version number to start from

versions · array

Array of dashboard versions

versions[].version · integer

Version number

versions[].created · string

Creation timestamp (ISO 8601)

versions[].createdBy · string

Username of creator

versions[].message · string

Commit message for this version

Get Dashboard Version

Retrieve a specific version of a dashboard.

cURL

curl -X GET http://localhost:3000/api/dashboards/uid/nHz3SXiiz/versions/1 \
  -u admin:admin

{
  "id": 1,
  "dashboardId": 1,
  "dashboardUid": "nHz3SXiiz",
  "version": 1,
  "created": "2021-06-01T10:00:00Z",
  "createdBy": "admin",
  "message": "Initial save",
  "data": {
    "title": "My Dashboard",
    "panels": []
  }
}

uid · string · required

Dashboard unique identifier

id · integer · required

Version ID

Get Dashboard Tags

Get all dashboard tags for the current organization.

cURL

curl -X GET http://localhost:3000/api/dashboards/tags \
  -u admin:admin

[
  {
    "term": "templated",
    "count": 5
  },
  {
    "term": "production",
    "count": 3
  }
]

term · string

Tag name

count · integer

Number of dashboards with this tag

Get Home Dashboard

Get the home dashboard for the current user.

cURL

curl -X GET http://localhost:3000/api/dashboards/home \
  -u admin:admin

{
  "meta": {
    "canEdit": false,
    "folderTitle": "General"
  },
  "dashboard": {
    "title": "Home",
    "panels": []
  }
}

Permissions

If you are running Grafana Enterprise with Fine-grained access control enabled:

• Read: Requires dashboards:read permission with scope dashboards:uid:<uid>
• Create: Requires dashboards:create permission
• Update: Requires dashboards:write permission with scope dashboards:uid:<uid>
• Delete: Requires dashboards:delete permission with scope dashboards:uid:<uid>