HTTP API on Grafana Labs

API structure in Grafana

Thu, 16 Apr 2026 14:18:24 +0000

The new API structure in Grafana

Note
Available in Grafana 12 and later.

Grafana 13 marks the deprecation of legacy API endpoints (/api) in favor of a new generation of improved APIs (/apis), a Kubernetes-style API layer which follows a standardized API structure alongside consistent API versioning.

Migrate from legacy `api` endpoints

Legacy APIs are not being disabled for the moment. Removal of legacy APIs is planned for a future major release, and any breaking changes will be announced well in advance to avoid disruptions.

Note that while Grafana is working on migrating existing APIs to the new /apis model, currently there may not be an exact match to the legacy API you’re using.

API structure

API path

All Grafana APIs follow this standardized format:

/apis/<group>/<version>/namespaces/<namespace>/<resource>[/<name>]

Where the final /<name> segment is used for operations on individual resources (like Get, Update, Delete) and omitted for collection operations (like List, Create).

API response format

All Grafana API responses follow this structure:

{
  "kind": "<kind>",
  "apiVersion": "<group>/<version>",
  "metadata": {
    "name": "<name>",
    "namespace": "<namespace>",
    "uid": "db323171-c78a-42fa-be98-16a3d799a779",
    "resourceVersion": "1758777451428472",
    "generation": 10,
    "creationTimestamp": "2026-01-23T22:06:40Z",
    "annotations": {}
  },
  "spec": {
    // resource-specific fields
  }
}

Understand the components

Group (`<group>`)

Groups organize related functionality into logical collections. For example dashboard.grafana.app will be used for all dashboard-related operations.

Version (`<version>`)

These APIs will also uses semantic versioning with three stability levels:

Level	Format	Description	Use Case	Enabled By Default?
Alpha	`v1alpha1`	Early development stage. Unstable, may contain bugs, and subject to removal	For testing new features	No
Beta	`v1beta1`	More stable than alpha, but may still have some changes	For non-critical use	No
GA	`v1`	Generally Available. Stable with backward compatibility guarantees	For production use	Yes

Alpha

Alpha versions should not be served unless explicitly enabled by a feature flag, and should be considered completely experimental and subject to major changes. An alpha version may undergo breaking changes without adding an additional version, and should not be relied upon by production workflows. Alpha versions may be removed completely, even without being promoted to a more stable level (e.g. an experimental API may be introduced as alpha for a new feature and subsequently removed completely, in case that feature gets canceled).

Beta

Beta versions should not contain breaking changes in the schema, but still may be subject to changes in handling logic or semantics. Breaking schema changes require a new published beta version (such as publishing v1beta2 for breaking changes to the v1beta1 schema). While beta versions are no longer considered experimental like alpha versions, they should still be disabled by default.

GA

GA versions are enabled by default, and can be treated as completely stable. The only changes that can be made to these APIs are bug fixes, and any other changes should instead result in a new published version of the API.

Namespace (`<namespace>`)

Namespaces isolate resources within your Grafana instance. The format varies by deployment type:

OSS & On-Premise Grafana

Default organization (org 1): default
Additional organizations: org-<org_id>

Grafana Cloud

Format: stacks-<stack_id>
Your instance ID is the stack_id. You can find this value by either:
- Going to grafana.com, clicking on your stack, and selecting “Details” on your Grafana instance
- Accessing the /swagger page in your cloud instance, where the namespace will be automatically populated on the relevant endpoints

Resource (`<resource>`)

The resource type you want to interact with, such as:

dashboards
playlists
folders

Kind (`<kind>`)

The kind identifies the resource type in API responses and corresponds to the singular form of the resource. For example, the dashboards resource has a kind of Dashboard.

Name (`<name>`)

The <name> is the unique identifier for a specific instance of a resource within its namespace and resource type. <name> is distinct from the metadata.uid field. The URL path will always use the metadata.name.

For example, to get a dashboard defined as:

{
  "kind": "Dashboard",
  "apiVersion": "dashboard.grafana.app/v1",
  "metadata": {
    "name": "production-overview", // This value IS used in the URL path
    "namespace": "default",
    "uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8" // This value is NOT used in the URL path
    // ... other metadata
  },
  "spec": {
    // ... dashboard spec
  }
}

You would use the following API call:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/production-overview

Metadata

The metadata section contains information about the resource instance. This section includes name and namespace, which are described earlier in this document, along with the following fields:

UID

An internal identifier that can be ignored for most use cases. Use the name field as the unique identifier instead. This value is not the same as the Grafana UID.

ResourceVersion

A value that changes whenever any part of the resource changes, including metadata or status.

Use this field for:

Change detection
Optimistic concurrency control

Generation

A monotonically increasing number that increments only when the spec changes. Updates to metadata or status don’t affect this value.

CreationTimestamp

The time the object was created, formatted as an RFC 3339 UTC timestamp (for example, 2026-01-23T22:06:40Z).

Annotations

A map of key-value pairs.

Common annotations include:

grafana.app/createdBy / grafana.app/updatedBy: Identifies who created or last updated the resource. Format: <user-type>:<uid> (for example, user:u000000839)
grafana.app/folder: If the resource supports folders, contains the folder UID the object belongs to.
grafana.app/updatedTimestamp: Timestamp of the last update, formatted as RFC 3339 UTC (for example, 2026-01-23T05:17:31Z).

Labels

An optional map of key-value pairs for organizing and selecting resources.

Spec

The spec field describes the desired state of the resource. Its structure is specific to the resource type and API version. Refer to the Swagger / OpenAPI documentation for the exact schema of each resource’s spec.

Dashboard HTTP API

Wed, 15 Apr 2026 10:30:32 +0000

Dashboard APIs

Note
Available in Grafana 12 and later.

This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.

Requirements

If you’re running Grafana Enterprise, you’ll need to have specific permissions for some endpoints. Refer to Role-based access control permissions for more information.

Create Dashboard

POST /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards

Creates a new dashboard.

namespace: to read more about the namespace to use, see the API overview.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`dashboards:create`	`folders:` `folders:uid:`
`dashboards:write`	`dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

Example Create Request:

POST /apis/dashboard.grafana.app/v1/namespaces/default/dashboards HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "metadata": {
    "name": "gdxccn",
    "annotations": {
      "grafana.app/folder": "fef30w4jaxla8b"
    },
  },
  "spec": {
    "annotations": {
    "list": [
      {
        "datasource": {
          "type": "datasource",
          "uid": "grafana"
        },
        "enable": true,
        "hide": false,
        "iconColor": "red",
        "name": "Example annotation",
        "target": {
          "limit": 100,
          "matchAny": false,
          "tags": [],
          "type": "dashboard"
        }
      }]
    },
    "editable": true,
    "fiscalYearStartMonth": 0,
    "graphTooltip": 0,
    "links": [
      {
        "asDropdown": false,
        "icon": "external link",
        "includeVars": false,
        "keepTime": false,
        "tags": [],
        "targetBlank": false,
        "title": "Example Link",
        "tooltip": "",
        "type": "dashboards",
        "url": ""
      }
    ],
    "panels": [
      {
        "datasource": {
          "type": "datasource",
          "uid": "grafana"
        },
        "description": "With a description",
        "fieldConfig": {
          "defaults": {
            "color": {
              "mode": "palette-classic"
            },
            "custom": {
              "axisBorderShow": false,
              "axisCenteredZero": false,
              "axisColorMode": "text",
              "axisLabel": "",
              "axisPlacement": "auto",
              "barAlignment": 0,
              "barWidthFactor": 0.6,
              "drawStyle": "line",
              "fillOpacity": 0,
              "gradientMode": "none",
              "hideFrom": {
                "legend": false,
                "tooltip": false,
                "viz": false
              },
              "insertNulls": false,
              "lineInterpolation": "linear",
              "lineWidth": 1,
              "pointSize": 5,
              "scaleDistribution": {
                "type": "linear"
              },
              "showPoints": "auto",
              "spanNulls": false,
              "stacking": {
                "group": "A",
                "mode": "none"
              },
              "thresholdsStyle": {
                "mode": "off"
              }
            },
            "mappings": [],
            "thresholds": {
              "mode": "absolute",
              "steps": [
                {
                  "color": "green"
                },
                {
                  "color": "red",
                  "value": 80
                }
              ]
            }
          },
          "overrides": []
        },
        "gridPos": {
          "h": 8,
          "w": 12,
          "x": 0,
          "y": 0
        },
        "id": 1,
        "options": {
          "legend": {
            "calcs": [],
            "displayMode": "list",
            "placement": "bottom",
            "showLegend": true
          },
          "tooltip": {
            "hideZeros": false,
            "mode": "single",
            "sort": "none"
          }
        },
        "pluginVersion": "12.0.0",
        "targets": [
          {
            "datasource": {
              "type": "datasource",
              "uid": "grafana"
            },
            "refId": "A"
          }
        ],
        "title": "Example panel",
        "type": "timeseries"
      }
    ],
    "preload": false,
    "schemaVersion": 41,
    "tags": ["example"],
    "templating": {
      "list": [
        {
          "current": {
            "text": "",
            "value": ""
          },
          "definition": "",
          "description": "example description",
          "label": "ExampleLabel",
          "name": "ExampleVariable",
          "options": [],
          "query": "",
          "refresh": 1,
          "regex": "cluster",
          "type": "query"
        }
      ]
    },
    "time": {
      "from": "now-6h",
      "to": "now"
    },
    "timepicker": {},
    "timezone": "browser",
    "title": "Example Dashboard",
    "version": 0
  }
}

JSON Body schema:

metadata.name – The Grafana unique identifier. If you do not want to provide this, set metadata.generateName instead to the prefix you would like for the randomly generated uid (cannot be an empty string).
metadata.annotations.grafana.app/folder - Optional field, the unique identifier of the folder under which the dashboard should be created.
spec – The dashboard json.

Note
Custom labels and annotations in the metadata field are supported on some instances, with full support planned for all instances when these APIs reach general availability. If they are not yet supported on your instance, they will be ignored.

Example Response:

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

{
  "kind": "Dashboard",
  "apiVersion": "dashboard.grafana.app/v1",
  "metadata": {
    "name": "gdxccn",
    "namespace": "default",
    "uid": "Cc7fA5ffHY94NnHZyMxXvFlpFtOmkK3qkBcVZPKSPXcX",
    "resourceVersion": "1",
    "generation": 1,
    "creationTimestamp": "2025-04-24T20:35:29Z",
    "labels": {
      "grafana.app/deprecatedInternalID": "11"
    },
    "annotations": {
      "grafana.app/createdBy": "service-account:dejwtrofg77y8d",
      "grafana.app/folder": "fef30w4jaxla8b"
    },
    "managedFields": [
      {
        "manager": "curl",
        "operation": "Update",
        "apiVersion": "dashboard.grafana.app/v0alpha1",
        "time": "2025-04-24T20:35:29Z",
        "fieldsType": "FieldsV1",
        "fieldsV1": {
          "f:spec": {
            "f:annotations": {
              ".": {},
              "f:list": {}
            },
            "f:editable": {},
            "f:fiscalYearStartMonth": {},
            "f:graphTooltip": {},
            "f:links": {},
            "f:panels": {},
            "f:preload": {},
            "f:schemaVersion": {},
            "f:tags": {},
            "f:templating": {
              ".": {},
              "f:list": {}
            },
            "f:time": {
              ".": {},
              "f:from": {},
              "f:to": {}
            },
            "f:timepicker": {},
            "f:timezone": {},
            "f:title": {},
            "f:version": {}
          }
        }
      }
    ]
  },
  "spec": {
    "annotations": {
      "list": [
        {
          "datasource": {
            "type": "datasource",
            "uid": "grafana"
          },
          "enable": true,
          "hide": false,
          "iconColor": "red",
          "name": "Example annotation",
          "target": {
            "limit": 100,
            "matchAny": false,
            "tags": [],
            "type": "dashboard"
          }
        }
      ]
    },
    "editable": true,
    "fiscalYearStartMonth": 0,
    "graphTooltip": 0,
    "links": [
      {
        "asDropdown": false,
        "icon": "external link",
        "includeVars": false,
        "keepTime": false,
        "tags": [],
        "targetBlank": false,
        "title": "Example Link",
        "tooltip": "",
        "type": "dashboards",
        "url": ""
      }
    ],
    "panels": [
      {
        "datasource": {
          "type": "datasource",
          "uid": "grafana"
        },
        "description": "With a description",
        "fieldConfig": {
          "defaults": {
            "color": {
              "mode": "palette-classic"
            },
            "custom": {
              "axisBorderShow": false,
              "axisCenteredZero": false,
              "axisColorMode": "text",
              "axisLabel": "",
              "axisPlacement": "auto",
              "barAlignment": 0,
              "barWidthFactor": 0.6,
              "drawStyle": "line",
              "fillOpacity": 0,
              "gradientMode": "none",
              "hideFrom": {
                "legend": false,
                "tooltip": false,
                "viz": false
              },
              "insertNulls": false,
              "lineInterpolation": "linear",
              "lineWidth": 1,
              "pointSize": 5,
              "scaleDistribution": {
                "type": "linear"
              },
              "showPoints": "auto",
              "spanNulls": false,
              "stacking": {
                "group": "A",
                "mode": "none"
              },
              "thresholdsStyle": {
                "mode": "off"
              }
            },
            "mappings": [],
            "thresholds": {
              "mode": "absolute",
              "steps": [
                {
                  "color": "green"
                },
                {
                  "color": "red",
                  "value": 80
                }
              ]
            }
          },
          "overrides": []
        },
        "gridPos": {
          "h": 8,
          "w": 12,
          "x": 0,
          "y": 0
        },
        "id": 1,
        "options": {
          "legend": {
            "calcs": [],
            "displayMode": "list",
            "placement": "bottom",
            "showLegend": true
          },
          "tooltip": {
            "hideZeros": false,
            "mode": "single",
            "sort": "none"
          }
        },
        "pluginVersion": "12.0.0",
        "targets": [
          {
            "datasource": {
              "type": "datasource",
              "uid": "grafana"
            },
            "refId": "A"
          }
        ],
        "title": "Example panel",
        "type": "timeseries"
      }
    ],
    "preload": false,
    "schemaVersion": 41,
    "tags": [
      "example"
    ],
    "templating": {
      "list": [
        {
          "current": {
            "text": "",
            "value": ""
          },
          "definition": "",
          "description": "example description",
          "label": "ExampleLabel",
          "name": "ExampleVariable",
          "options": [],
          "query": "",
          "refresh": 1,
          "regex": "cluster",
          "type": "query"
        }
      ]
    },
    "time": {
      "from": "now-6h",
      "to": "now"
    },
    "timepicker": {},
    "timezone": "browser",
    "title": "Example Dashboard"
  },
  "status": {}

Status Codes:

201 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Access denied
409 – Conflict (dashboard with the same uid already exists)

Update Dashboard

PUT /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards/:uid

Updates an existing dashboard via the dashboard uid.

namespace: to read more about the namespace to use, see the API overview.
uid: the unique identifier of the dashboard to update. this will be the name in the dashboard response

Required permissions

See note in the introduction for an explanation.

Action	Scope
`dashboards:write`	`dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

Example Update Request:

POST /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/gdxccn HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "metadata": {
    "name": "gdxccn",
    "annotations": {
      "grafana.app/folder": "fef30w4jaxla8b",
      "grafana.app/message": "commit message"
    },
  },
  "spec": {
    "title": "New dashboard - updated",
    "schemaVersion": 41,
    ...
  }
}

JSON Body schema:

metadata.name – The unique identifier.
metadata.annotations.grafana.app/folder - Optional field, the unique identifier of the folder under which the dashboard should be created.
metadata.annotations.grafana.app/message - Optional field, to set a commit message for the version history.
spec – The dashboard json.

Note
Custom labels and annotations in the metadata field are supported on some instances, with full support planned for all instances when these APIs reach general availability. If they are not yet supported on your instance, they will be ignored.

Example Response:

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

{
  "kind": "Dashboard",
  "apiVersion": "dashboard.grafana.app/v1",
  "metadata": {
    "name": "gdxccn",
    "namespace": "default",
    "uid": "Cc7fA5ffHY94NnHZyMxXvFlpFtOmkK3qkBcVZPKSPXcX",
    "resourceVersion": "2",
    "generation": 2,
    "creationTimestamp": "2025-03-06T19:57:18Z",
    "annotations": {
      "grafana.app/folder": "fef30w4jaxla8b",
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedTimestamp": "2025-03-07T02:58:36Z"
    }
  },
  "spec": {
    "schemaVersion": 41,
    "title": "New dashboard - updated",
    ...
  }
}

Status Codes:

200 – OK
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Access denied
409 – Conflict (dashboard with the same version already exists)

Get Dashboard

GET /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards/:uid

Gets a dashboard via the dashboard uid.

namespace: to read more about the namespace to use, see the API overview.
uid: the unique identifier of the dashboard to update. this will be the name in the dashboard response

Required permissions

See note in the introduction for an explanation.

Action	Scope
`dashboards:read`	`dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

Example Get Request:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/gdxccn 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: 485

{
  "kind": "Dashboard",
  "apiVersion": "dashboard.grafana.app/v1",
  "metadata": {
    "name": "gdxccn",
    "namespace": "default",
    "uid": "Cc7fA5ffHY94NnHZyMxXvFlpFtOmkK3qkBcVZPKSPXcX",
    "resourceVersion": "2",
    "generation": 2,
    "creationTimestamp": "2025-03-06T19:57:18Z",
    "annotations": {
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedTimestamp": "2025-03-07T02:58:36Z"
    }
  },
  "spec": {
    "schemaVersion": 41,
    "title": "New dashboard - updated",
    ...
  }
}

Status Codes:

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

Retrieve additional access information

GET /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards/:uid/dto

Retrieves a dashboard with additional access information.

The GET response includes an additional access section with data such as if it’s a public dashboard, or the dashboard permissions (admin, editor) of the user who made the request.

List Dashboards

GET /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards

Lists all dashboards in the given organization. You can control the maximum number of dashboards returned through the limit query parameter. You can then use the continue token returned to fetch the next page of dashboards.

namespace: to read more about the namespace to use, see the API overview.

Query parameters:

limit (optional): Maximum number of dashboards to return
continue (optional): Continue token from a previous response to fetch the next page

Required permissions

See note in the introduction for an explanation.

Action	Scope
`dashboards:read`	`dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

Example Get Request:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards?limit=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: 644

{
  "kind": "DashboardList",
  "apiVersion": "dashboard.grafana.app/v1alpha1",
  "metadata": {
    "resourceVersion": "1741315830000",
    "continue": "eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ=="
  },
  "items": [
    {
      "kind": "Dashboard",
      "apiVersion": "dashboard.grafana.app/v1alpha1",
      "metadata": {
        "name": "gpqcmf",
        "namespace": "default",
        "uid": "VQyL7pNTpfGPNlPM6HRJSePrBg5dXmxr4iPQL7txLtwX",
        "resourceVersion": "1",
        "generation": 1,
        "creationTimestamp": "2025-03-06T19:50:30Z",
        "annotations": {
          "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedTimestamp": "2025-03-06T19:50:30Z"
        }
      },
      "spec": {
        "schemaVersion": 41,
        "title": "New dashboard",
        "uid": "gpqcmf",
        "version": 1,
        ...
      }
    }
  ]
}

The metadata.continue field contains a token to fetch the next page.

Example subsequent request using continue token:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards?limit=1&continue=eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ== HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example subsequent response:

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

{
  "kind": "DashboardList",
  "apiVersion": "dashboard.grafana.app/v1alpha1",
  "items": [
    {
      "kind": "Dashboard",
      "apiVersion": "dashboard.grafana.app/v1alpha1",
      "metadata": {
        "name": "hpqcmg",
        "namespace": "default",
        "uid": "WQyL7pNTpfGPNlPM6HRJSePrBg5dXmxr4iPQL7txLtwY",
        "resourceVersion": "1",
        "generation": 1,
        "creationTimestamp": "2025-03-06T19:51:31Z",
        "annotations": {
          "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedTimestamp": "2025-03-06T19:51:31Z"
        }
      },
      "spec": {
        "schemaVersion": 41,
        "title": "Another dashboard",
        "uid": "hpqcmg",
        "version": 1,
        ...
      }
    }
  ]
}

Continue making requests with the updated continue token until you receive a response without a continue field in the metadata, indicating you’ve reached the last page.

Status Codes:

200 – OK
401 – Unauthorized
403 – Access denied

List dashboard history

You can retrieve the full version history of a dashboard using the List endpoint with specific query parameters. For details and examples, refer to Resource history HTTP API.

Delete Dashboard

DELETE /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards/:uid

Deletes a dashboard via the dashboard uid.

namespace: To read more about the namespace to use, see the API overview.
uid: The unique identifier of the dashboard to update. This is the metadata.name field in the dashboard response and not the metadata.uid field.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`dashboards:delete`	`dashboards:` `dashboards:uid:` `folders:` `folders:uid:`

Example Delete Request:

DELETE /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/gdxccn 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: 78

{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {},
  "status": "Success",
  "details": {
    "name": "gdxccn",
    "group": "dashboard.grafana.app",
    "kind": "dashboards",
    "uid": "Cc7fA5ffHY94NnHZyMxXvFlpFtOmkK3qkBcVZPKSPXcX"
  }
}

Status Codes:

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

Folder HTTP API

Wed, 15 Apr 2026 10:30:32 +0000

New Folders APIs

Note
Available in Grafana 12 and later.

This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.

Requirements

If you’re running Grafana Enterprise, you’ll need to have specific permissions for some endpoints. Refer to Role-based access control permissions for more information.

Get all folders

GET /apis/folder.grafana.app/v1/namespaces/:namespace/folders

Returns all folders that the authenticated user has permission to view within the given organization. Use the limit query parameter to control the maximum number of dashboards returned. To retrieve additional dashboards, utilize the continue token provided in the response to fetch the next page.

namespace: to read more about the namespace to use, see the API overview.

Query parameters:

limit (optional): Maximum number of folders to return
continue (optional): Continue token from a previous response to fetch the next page

Required permissions

See note in the introduction for an explanation.

Action	Scope
`folders:read`	`folders:*`

Example Request:

GET /apis/folder.grafana.app/v1/namespaces/default/folders?limit=1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "FolderList",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "continue": "eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ=="
  },
  "items": [
    {
      "kind": "Folder",
      "apiVersion": "folder.grafana.app/v1",
      "metadata": {
        "name": "aef30vrzxs3y8d",
        "namespace": "default",
        "uid": "KCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb4X",
        "resourceVersion": "1741343686000",
        "creationTimestamp": "2025-03-07T10:34:46Z",
        "annotations": {
          "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedTimestamp": "2025-03-07T10:34:46Z"
        }
      },
      "spec": {
        "title": "example"
      }
    }
  ]
}

The metadata.continue field contains a token to fetch the next page.

Example subsequent request using continue token:

GET /apis/folder.grafana.app/v1/namespaces/default/folders?limit=1&continue=eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ== HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example subsequent response:

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "FolderList",
  "apiVersion": "folder.grafana.app/v1",
  "items": [
    {
      "kind": "Folder",
      "apiVersion": "folder.grafana.app/v1",
      "metadata": {
        "name": "bef30vrzxs3y8e",
        "namespace": "default",
        "uid": "YCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb5Y",
        "resourceVersion": "1741343687000",
        "creationTimestamp": "2025-03-07T10:35:47Z",
        "annotations": {
          "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedTimestamp": "2025-03-07T10:35:47Z"
        }
      },
      "spec": {
        "title": "another folder"
      }
    }
  ]
}

Continue making requests with the updated continue token until you receive a response without a continue field in the metadata, indicating you’ve reached the last page.

Status Codes:

200 – OK
401 – Unauthorized
403 – Access Denied

Get folder by uid

GET /apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid

Will return the folder given the folder uid.

namespace: to read more about the namespace to use, see the API overview.
uid: the unique identifier of the folder to update. this will be the name in the folder response

Required permissions

See note in the introduction for an explanation.

Action	Scope
`folders:read`	`folders:*`

Example Request:

GET /apis/folder.grafana.app/v1/namespaces/default/folders/aef30vrzxs3y8d HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "name": "aef30vrzxs3y8d",
    "namespace": "default",
    "uid": "KCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb4X",
    "resourceVersion": "1741343686000",
    "creationTimestamp": "2025-03-07T10:34:46Z",
    "annotations": {
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedTimestamp": "2025-03-07T10:34:46Z",
      "grafana.app/folder": "fef30w4jaxla8b"
    }
  },
  "spec": {
    "title": "test"
  }
}

Note the annotation grafana.app/folder which contains the uid of the parent folder.

Status Codes:

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

Create folder

POST /apis/folder.grafana.app/v1/namespaces/:namespace/folders

Creates a new folder.

namespace: to read more about the namespace to use, see the API overview.

Required permissions

See note in the introduction for an explanation.

folders:create allows creating folders and subfolders. If granted with scope folders:uid:general, allows creating root level folders. Otherwise, allows creating subfolders under the specified folders.

Action	Scope
`folders:create`	`folders:*`
`folders:write`	`folders:*`

Example Request:

POST /apis/folder.grafana.app/v1/namespaces/default/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "metadata": {
    "name": "aef30vrzxs3y8d",
    "annotations": {
      "grafana.app/folder": "fef30w4jaxla8b"
    }
  }
  "spec": {
    "title": "child-folder"
  },
}

JSON Body schema:

metadata.name – The Grafana unique identifier. If you do not want to provide this, set metadata.generateName to the prefix you would like for the uid.
metadata.annotations.grafana.app/folder - Optional field, the unique identifier of the parent folder under which the folder should be created. Requires nested folders to be enabled.
spec.title – The title of the folder.

Note
Custom labels and annotations in the metadata field are supported on some instances, with full support planned for all instances when these APIs reach general availability. If they are not yet supported on your instance, they will be ignored.

Example Response:

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "name": "eef33r1fprd34d",
    "namespace": "default",
    "uid": "X8momvVZnsXdOqvLD9I4ngqLVif2CgRWXHy9xb2UgjQX",
    "resourceVersion": "1741320415009",
    "creationTimestamp": "2025-03-07T04:06:55Z",
    "labels": {
      "grafana.app/deprecatedInternalID": "1159"
    },
    "annotations": {
      "grafana.app/folder": "fef30w4jaxla8b",
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb"
    }
  },
  "spec": {
    "title": "child-folder"
  }
}

Status Codes:

201 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Access denied
409 – Conflict (folder with the same uid already exists)

Update folder

PUT /apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid

Updates an existing folder identified by uid.

namespace: to read more about the namespace to use, see the API overview.
uid: the unique identifier of the folder to update. this will be the name in the folder response

Required permissions

See note in the introduction for an explanation.

Action	Scope
`folders:write`	`folders:*`

Example Request:

PUT /apis/folder.grafana.app/v1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

"metadata": {
    "name": "aef30vrzxs3y8d",
    "annotations": {
      "grafana.app/folder": "xkj92m5pqw3vn4"
    }
  }
  "spec": {
    "title": "updated title"
  },

JSON Body schema:

metadata.name – The unique identifier of the folder.
metadata.annotations.grafana.app/folder - Optional field, the unique identifier of the parent folder under which the folder should be - update this to move the folder under a different parent folder. Requires nested folders to be enabled.
spec.title – The title of the folder.

Note
Custom labels and annotations in the metadata field are supported on some instances, with full support planned for all instances when these APIs reach general availability. If they are not yet supported on your instance, they will be ignored.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "name": "fef30w4jaxla8b",
    "namespace": "default",
    "uid": "YaWLsFrMwEaTlIQwX2iMnhHlJuZHtZugps50BQoyjXEX",
    "resourceVersion": "1741345736000",
    "creationTimestamp": "2025-03-07T11:08:56Z",
    "annotations": {
      "grafana.app/folder": "xkj92m5pqw3vn4",
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedTimestamp": "2025-03-07T11:08:56Z"
    }
  },
  "spec": {
    "title": "updated title"
  }
}

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 folder has been changed by someone else). With this status code, 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 /apis/folder.grafana.app/v1/namespaces/:namespace/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 Alerting is 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 alerts. However, if this parameter is set to true then it will delete any Grafana alerts under this folder.

namespace: to read more about the namespace to use, see the API overview.
uid: the unique identifier of the folder to delete. this will be the name in the folder response

Required permissions

See note in the introduction for an explanation.

Action	Scope
`folders:delete`	`folders:*`

Example Request:

DELETE /apis/folder.grafana.app/v1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "name": "fef30w4jaxla8b",
    "namespace": "default",
    "uid": "YaWLsFrMwEaTlIQwX2iMnhHlJuZHtZugps50BQoyjXEX",
    "resourceVersion": "1741345736000",
    "creationTimestamp": "2025-03-07T11:08:56Z",
    "annotations": {
      "grafana.app/folder": "xkj92m5pqw3vn4",
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedTimestamp": "2025-03-07T11:08:56Z"
    }
  },
  "spec": {
    "title": "updated title"
  }
}

Status Codes:

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

Playlist HTTP API

Wed, 15 Apr 2026 10:30:32 +0000

Playlist API

Note
Available in Grafana 12 and later.

This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.

List Playlists

GET /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists

Lists all playlists in the specified namespace.

namespace: To learn more about which namespace to use, refer to the API overview.

Example Request:

GET /apis/playlist.grafana.app/v1/namespaces/default/playlists HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "PlaylistList",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {},
  "items": [
    {
      "kind": "Playlist",
      "apiVersion": "playlist.grafana.app/v1",
      "metadata": {
        "name": "my-playlist-uid",
        "namespace": "default",
        "resourceVersion": "1234567890",
        "creationTimestamp": "2024-01-15T10:30:00Z"
      },
      "spec": {
        "title": "My Playlist",
        "interval": "5m",
        "items": [
          {
            "type": "dashboard_by_uid",
            "value": "dashboard-uid-1"
          },
          {
            "type": "dashboard_by_tag",
            "value": "important"
          }
        ]
      }
    }
  ]
}

Get a Playlist

GET /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists/:name

Retrieves a specific playlist by name.

namespace: To learn more about which namespace to use, refer to the API overview.
name: The UID of the playlist.

Example Request:

GET /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567890",
    "creationTimestamp": "2024-01-15T10:30:00Z"
  },
  "spec": {
    "title": "My Playlist",
    "interval": "5m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_tag",
        "value": "important"
      }
    ]
  }
}

Create a Playlist

POST /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists

Creates a new playlist.

namespace: To learn more about which namespace to use, refer to the API overview.

Example Request:

POST /apis/playlist.grafana.app/v1/namespaces/default/playlists HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-new-playlist-uid"
  },
  "spec": {
    "title": "My New Playlist",
    "interval": "5m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_tag",
        "value": "monitoring"
      }
    ]
  }
}

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-new-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567891",
    "creationTimestamp": "2024-01-15T10:35:00Z"
  },
  "spec": {
    "title": "My New Playlist",
    "interval": "5m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_tag",
        "value": "monitoring"
      }
    ]
  }
}

Update a Playlist

PUT /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists/:name

Updates an existing playlist. The entire playlist spec must be provided.

namespace: To learn more about which namespace to use, refer to the API overview.
name: The UID of the playlist.

Example Request:

PUT /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567890"
  },
  "spec": {
    "title": "My Updated Playlist",
    "interval": "10m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-2"
      },
      {
        "type": "dashboard_by_tag",
        "value": "updated-tag"
      }
    ]
  }
}

Example Response:

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

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567892",
    "creationTimestamp": "2024-01-15T10:30:00Z"
  },
  "spec": {
    "title": "My Updated Playlist",
    "interval": "10m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-2"
      },
      {
        "type": "dashboard_by_tag",
        "value": "updated-tag"
      }
    ]
  }
}

Delete a Playlist

DELETE /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists/:name

Deletes a playlist.

namespace: To learn more about which namespace to use, refer to the API overview.
name: The UID of the playlist.

Example Request:

DELETE /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

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

{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {},
  "status": "Success",
  "code": 200
}

Playlist Item Types

Playlist items support three types:

dashboard_by_uid: Include a specific dashboard by its UID
dashboard_by_tag: Include all dashboards with a specific tag
dashboard_by_id: (Deprecated) Include a dashboard by internal ID

Resource history HTTP API

Wed, 15 Apr 2026 10:30:32 +0000

Resource History HTTP API

Note
Available in Grafana 12 and later.

This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.

The new Grafana APIs track version history for resources. You can retrieve the history of any resource by using the standard List endpoint with specific query parameters. This page documents how to list resource history, using dashboards as an example. The same pattern applies to any resource.

Resource history is available on all stable (GA) API versions (for example, v1, v2). Alpha or beta versions may not support it.

List resource history

GET /apis/<group>/<version>/namespaces/<namespace>/<resource>?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name=<NAME>

Lists the version history of a specific resource. This uses the standard List endpoint with two required query parameters:

labelSelector: Must be set to grafana.app/get-history=true to request history instead of a normal list.
fieldSelector: Must be set to metadata.name=<NAME> to identify the specific resource. <NAME> is the metadata.name field of the resource (the Grafana UID).

You can control pagination through additional query parameters:

limit (optional): Maximum number of history entries to return per page.
continue (optional): Token from a previous response to fetch the next page.

History entries are returned in reverse chronological order (newest first).

Dashboard example

The following request retrieves the version history for a dashboard with metadata.name of production-overview in the default namespace:

Example request:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name=production-overview HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

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

{
  "kind": "DashboardList",
  "apiVersion": "dashboard.grafana.app/v1",
  "metadata": {
    "resourceVersion": "1758777451428472",
    "continue": "eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ=="
  },
  "items": [
    {
      "kind": "Dashboard",
      "apiVersion": "dashboard.grafana.app/v1",
      "metadata": {
        "name": "production-overview",
        "namespace": "default",
        "uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
        "resourceVersion": "1758777451428472",
        "generation": 3,
        "creationTimestamp": "2026-03-15T14:22:10Z",
        "annotations": {
          "grafana.app/updatedBy": "user:u000000001",
          "grafana.app/message": "Added latency panel"
        }
      },
      "spec": {
        "title": "Production Overview",
        "schemaVersion": 41,
        ...
      }
    },
    {
      "kind": "Dashboard",
      "apiVersion": "dashboard.grafana.app/v1",
      "metadata": {
        "name": "production-overview",
        "namespace": "default",
        "uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
        "resourceVersion": "1758777451428100",
        "generation": 2,
        "creationTimestamp": "2026-03-10T09:15:30Z",
        "annotations": {
          "grafana.app/updatedBy": "user:u000000001",
          "grafana.app/message": "Updated thresholds"
        }
      },
      "spec": {
        "title": "Production Overview",
        "schemaVersion": 41,
        ...
      }
    }
  ]
}

Each item in the items array represents a historical version of the resource. The following metadata fields are especially relevant for history:

metadata.generation: The version number. This increments each time the resource’s spec changes.
metadata.resourceVersion: A unique identifier for this specific version. Use this for pagination and change detection.
metadata.creationTimestamp: When this specific version was saved.
metadata.annotations.grafana.app/updatedBy: The user who saved this version, in the format <user-type>:<uid>.
metadata.annotations.grafana.app/message: An optional commit message set during the update. You can set this annotation when updating a resource.
spec: The full resource spec as it existed at that version.

Pagination

You can paginate through history using limit and continue, the same way you paginate a standard List request.

Example request with pagination:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name=production-overview&limit=2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

If the response includes a metadata.continue field, pass it as the continue query parameter in the next request to fetch the next page. When the response doesn’t include a continue field, you’ve reached the last page.

Example request for the next page:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name=production-overview&limit=2&continue=eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ== HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Retrieve a specific version

To retrieve the full resource at a specific historical version, use the standard Get endpoint with the resourceVersion query parameter set to the metadata.resourceVersion from the history list.

Example request:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/production-overview?resourceVersion=1758777451428100 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

This returns the complete resource as it existed at that version.

Status codes

200: OK
400: Bad request (missing fieldSelector, invalid labelSelector, etc.)
401: Unauthorized
403: Access denied

Secrets Management HTTP API

Wed, 15 Apr 2026 10:30:32 +0000

Secrets Management API

Note
Available in Grafana 12 and later.

This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.

The Grafana Secrets Management API allows you to manage secrets that are used by other services and applications within your Grafana instance.

Caution
The API is currently in public preview and might be subject to changes.

Requirements

If you’re running Grafana Enterprise, you’ll need to have specific permissions for some endpoints. Refer to Role-based access control permissions for more information.

Decrypters

The decrypters field is an allowlist that lets the secure value know which services and apps can decrypt the secret value.

Currently available decrypters:

k6-cloud (for Grafana Cloud k6)
provisioning.grafana.app (for GitSync/Provisioning)
synthetic-monitoring (for Synthetic Monitoring checks)

Create a secure value

POST /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues

Creates a new secure value.

URL parameters

namespace: To read more about which namespace to use, see the API overview.

Request body

metadata.name: The Grafana unique identifier. If you do not want to provide this, set metadata.generateName instead to the prefix you would like for the randomly generated uid (can’t be an empty string).
spec.description: Short description that explains the purpose of this secure value. Required. Up to 25 characters long.
spec.value: The secret value to store. Required. Up to 24576 bytes long.
spec.decrypters: List of services allowed to decrypt this secure value. Up to 64 items, see note in decrypters for a list of supported values.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:create`	`secret.securevalues:*`

Example create request:

POST /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "metadata": {
    "name": "api-key"
  },
  "spec": {
    "description": "External API Key",
    "value": "secret-api-key-12345",
    "decrypters": ["synthetic-monitoring"]
  }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Content-Length: 343

{
  "apiVersion": "secret.grafana.app/v1beta1",
  "kind": "SecureValue",
  "metadata": {
    "name": "api-key",
    "namespace": "default",
    "uid": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "creationTimestamp": "2024-01-15T10:35:00Z"
  },
  "spec": {
    "description": "External API Key",
    "decrypters": ["synthetic-monitoring"]
  },
  "status": {}
}

Status Codes:

201 – Created
400 – Errors (invalid JSON, missing or invalid fields, etc)
401 – Unauthorized
403 – Access denied
409 – Conflict (secure value with the same name already exists)

Note
The spec.value field is never returned by API endpoints. Users cannot not decrypt secrets.

List secure values

GET /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues

List all secure values in a namespace.

URL parameters

namespace: To read more about which namespace to use, see the API overview.

Query parameters

labelSelector: Filter secure values by labels.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:read`	`secret.securevalues:*`

Example list request:

GET /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues 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: 383

{
  "apiVersion": "secret.grafana.app/v1beta1",
  "kind": "SecureValueList",
  "metadata": {
    "resourceVersion": "12345"
  },
  "items": [
    {
      "apiVersion": "secret.grafana.app/v1beta1",
      "kind": "SecureValue",
      "metadata": {
        "name": "database-password",
        "namespace": "default",
        "creationTimestamp": "2024-01-15T10:30:00Z"
      },
      "spec": {
        "description": "Production DB Password",
        "decrypters": ["synthetic-monitoring"]
      },
      "status": {}
    }
  ]
}

Status Codes:

200 – OK
401 – Unauthorized
403 – Access denied

Get a secure value

GET /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name

Get the details of a specific secure value. It will not return the secret value.

URL parameters

namespace: To read more about which namespace to use, see the API overview.
name: The name of the secure value.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:read`	`secret.securevalues:*`

Example get request:

GET /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key 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: 294

{
  "apiVersion": "secret.grafana.app/v1beta1",
  "kind": "SecureValue",
  "metadata": {
    "name": "api-key",
    "namespace": "default",
    "uid": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "creationTimestamp": "2024-01-15T10:35:00Z"
  },
  "spec": {
    "description": "External API Key",
    "decrypters": ["synthetic-monitoring"]
  },
  "status": {}
}

Status Codes:

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

Update a secure value

PUT /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name

Replace an existing secure value with a new specification.

URL parameters

namespace: To read more about which namespace to use, see the API overview.
name: The name of the secure value.

Request body

spec.description: Short description that explains the purpose of this secure value. Required. Up to 25 characters long.
spec.value: The secret value to store. Required. Up to 24576 bytes long.
spec.decrypters: List of services allowed to decrypt this secure value. Up to 64 items, see note in decrypters for a list of supported values.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:write`	`secret.securevalues:*`

Example update request:

PUT /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "metadata": {
    "name": "api-key"
  },
  "spec": {
    "description": "External API Key",
    "value": "new-value-12345",
    "decrypters": ["synthetic-monitoring"]
  }
}

Example response:

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

{
  "apiVersion": "secret.grafana.app/v1beta1",
  "kind": "SecureValue",
  "metadata": {
    "name": "api-key",
    "namespace": "default",
    "uid": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "creationTimestamp": "2024-01-15T10:35:00Z"
  },
  "spec": {
    "description": "External API Key",
    "decrypters": ["synthetic-monitoring"]
  }
}

Status Codes:

200 – OK
400 – Errors (invalid JSON, missing or invalid fields, etc)
401 – Unauthorized
403 – Access denied
404 – Not found

Delete a secure value

DELETE /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name

Permanently delete a secure value. This also deletes the underlying stored secret value.

URL parameters

namespace: To read more about the namespace to use, see the API overview.
name: The name of the secure value.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:delete`	`secret.securevalues:*`

Example delete request:

DELETE /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key 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: 65

{
  "apiVersion": "v1",
  "kind": "Status",
  "status": "Success",
  "code": 200
}

Status Codes:

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

Legacy Grafana HTTP API

Thu, 16 Apr 2026 14:18:24 +0000

Legacy Grafana HTTP API

Note
Starting in Grafana 13, /api endpoints are being deprecated in favor of the /apis route. Note that while Grafana is working on migrating existing APIs, currently there may not be an exact match to the legacy API you’re using.

This change doesn’t disrupt or break your current setup. Legacy APIs are not being disabled and remain fully accessible and operative, but /api routes will no longer be updated.

To learn more refer to the new API structure in Grafana.

The following legacy APIs are available:

Authentication options for the HTTP API
You can authenticate HTTP API requests using basic authentication or a service account token.
Admin HTTP API
Grafana Admin HTTP API
Alerting Provisioning HTTP API
Grafana Alerts HTTP API
Annotations HTTP API
Grafana Annotations HTTP API
Correlations HTTP API
Grafana Correlations HTTP API
Dashboard Permissions HTTP API
Grafana Dashboard Permissions HTTP API
Dashboard Versions HTTP API
Grafana Dashboard Versions HTTP API
Data source HTTP API
Grafana Data source HTTP API
Data source LBAC rules HTTP API
Data Source LBAC rules API
Data source permissions HTTP API
Data Source Permissions API
Folder Permissions HTTP API
Grafana Folder Permissions HTTP API
Folder/Dashboard Search HTTP API
Grafana Folder/Dashboard Search HTTP API
Library Element HTTP API
Grafana Library Element HTTP API
Licensing HTTP API
Enterprise Licensing HTTP API
Organization HTTP API
Grafana Organization HTTP API
Other HTTP API
Grafana Other HTTP API
Preferences API
Grafana HTTP API
Query and Resource Caching HTTP API
Grafana Enterprise Query and Resource Caching HTTP API
Query History HTTP API
Grafana Query History HTTP API
RBAC HTTP API
Reporting API
Grafana Enterprise APIs
Service account HTTP API
Grafana service account HTTP API
Shared Dashboards HTTP API
Grafana Shared Dashboards HTTP API
Short URL HTTP API
Grafana Short URL HTTP API
Snapshot API
Grafana HTTP API
SSO Settings API
Grafana SSO Settings API
Team HTTP API
Grafana Team HTTP API
Team Sync HTTP API
Grafana Team Sync HTTP API
User HTTP API
Grafana User HTTP API

HTTP API examples

Wed, 15 Apr 2026 10:30:32 +0000

HTTP API on Grafana Labs

API structure in Grafana

The new API structure in Grafana

Migrate from legacy api endpoints

API structure

API path

API response format

Understand the components

Group (<group>)

Version (<version>)

Alpha

Beta

GA

Namespace (<namespace>)

OSS & On-Premise Grafana

Grafana Cloud

Resource (<resource>)

Kind (<kind>)

Name (<name>)

Metadata

UID

ResourceVersion

Generation

CreationTimestamp

Annotations

Labels

Spec

Dashboard HTTP API

Dashboard APIs

Requirements

Create Dashboard

Update Dashboard

Get Dashboard

Retrieve additional access information

List Dashboards

List dashboard history

Delete Dashboard

Folder HTTP API

New Folders APIs

Requirements

Get all folders

Get folder by uid

Create folder

Update folder

Delete folder

Playlist HTTP API

Playlist API

List Playlists

Get a Playlist

Create a Playlist

Update a Playlist

Delete a Playlist

Playlist Item Types

Resource history HTTP API

Resource History HTTP API

List resource history

Dashboard example

Pagination

Retrieve a specific version

Status codes

Secrets Management HTTP API

Secrets Management API

Requirements

Decrypters

Create a secure value

List secure values

Get a secure value

Update a secure value

Delete a secure value

Legacy Grafana HTTP API

Legacy Grafana HTTP API

HTTP API examples

HTTP API examples

Migrate from legacy `api` endpoints

Group (`<group>`)

Version (`<version>`)

Namespace (`<namespace>`)

Resource (`<resource>`)

Kind (`<kind>`)

Name (`<name>`)