This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Enterprise Open source Grafana Cloud

Playlist API

Note

Available in Grafana 12.4 and later.

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

This document may not contain the latest version of the API. For the most up-to-date list of available endpoints, refer to playlist.grafana.app/v1 in Swagger.

Requirements

By default, users with the Viewer role can read playlists, and users with the Editor or Admin role can also create, update, and delete them. Users with the None role can also read playlists. If the playlistsRBAC feature toggle is turned on, access uses the playlists:read and playlists:write actions instead. For the related fixed roles, refer to RBAC role definitions. For more information about the default access, refer to Organization roles.

Endpoints

These are the available endpoints:

Base path: /apis/playlist.grafana.app/v1/namespaces/{namespace}/

Replace {namespace} with your namespace. To learn which namespace to use, refer to the API overview.

MethodSummaryPath
GETList Playlistsplaylists
GETGet a Playlistplaylists/{name}
POSTCreate a Playlistplaylists
PUTUpdate a Playlistplaylists/{name}
DELETEDelete a Playlistplaylists/{name}

List Playlists

GET /apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists

Lists all playlists in the specified namespace.

Path parameters:

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

Example request

The following example shows a request to list playlists:

http
GET /apis/playlist.grafana.app/v1/namespaces/default/playlists HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Example response

The following example shows the response:

http
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.

Path parameters:

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

Example request

The following example shows a request to get a playlist:

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

Example response

The following example shows the response:

http
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.

Path parameters:

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

Example request

The following example shows a request to create a playlist:

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

{
  "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

The following example shows the response:

http
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. Provide the entire playlist, including metadata.resourceVersion from the latest version you read.

Path parameters:

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

Example request

The following example shows a request to update a playlist:

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

{
  "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

The following example shows the response:

http
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.

Path parameters:

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

Example request

The following example shows a request to delete a playlist:

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

Example response

The following example shows the response:

http
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

Status codes

The endpoints on this page return the following status codes:

CodeMeaningReturned by
200OK.List, Get, Update, Delete
201Created.Create
400Bad request (invalid JSON).Create, Update
401Unauthorized.All endpoints
403Access denied.All endpoints
404Playlist not found.Get, Update, Delete
409Conflict (a playlist with the same metadata.name already exists).Create
409Conflict (the playlist changed since you read it).Update
422Invalid playlist, for example because metadata.resourceVersion is missing.Update