This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.
Notebooks HTTP API
Note
Available in Grafana 13.2 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 dashboard.grafana.app/v2beta1 in Swagger.
This API is in
beta, so it might change in future releases.
Use this API to manage notebooks. A notebook combines text, code, and visualization panels in a single document, so you can investigate a problem, explain what you found, and share the supporting data with your team.
Before you begin
This API is in beta (v2beta1) and might change. For more details about versioning, refer to
New API versioning.
Notebooks are in public preview and disabled by default. To enable them, turn on the dashboard.notebooks
feature toggle. If the feature toggle is off, requests to the endpoints on this page return 403.
Notebooks can’t be stored in folders. Requests that set the grafana.app/folder annotation are rejected.
Requirements
By default, users with the Viewer role can read all notebooks in the organization, and users with the Editor role can also create, update, and delete them. To customize access, use the notebooks:read, notebooks:create, notebooks:write, and notebooks:delete actions. For more information, refer to
Role-based access control permissions.
Endpoints
The following table lists the main endpoints. The Swagger documentation also includes endpoints to apply partial updates with PATCH, delete a collection of notebooks, search notebooks, and list notebook keys.
Base path: /apis/dashboard.grafana.app/v2beta1/namespaces/{namespace}/
Replace {namespace} with your namespace. To learn which namespace to use, refer to the
API overview.
Notebook structure
A notebook spec is similar to a dashboard v2 spec, but it uses a notebook layout. It has the following fields:
- title – The title of the notebook. If you create a notebook without a title, Grafana names it after the creation time, in UTC, for example
Notebook 2026-11-05 07:30. - description – Optional. The description of the notebook.
- tags – Tags associated with the notebook. Use
[]for no tags. - timeSettings – The default time range of the notebook. It uses the same fields as the dashboard v2
timeSettings, such asfrom,to, andtimezone. Grafana always setshideTimepickertofalse. - elements – A map of the notebook content, keyed by element name. Each element is one of the following:
- Cell – Narrative content.
spec.contentis either aMarkdowncontent withtext, or aCodecontent withlanguage,code, and, optionally,highlight(a list of line numbers) andannotation. - Panel – A visualization panel with its queries, in the dashboard v2 panel format.
- LibraryPanel – A reference to a library panel.
- Cell – Narrative content.
- layout – The order of the elements.
kindmust beNotebookLayout, and Grafana rejects requests with dashboard layouts such asGridLayout.spec.cellsis an ordered list ofNotebookLayoutItemobjects, each with the following fields:- element – A reference to an entry in
elements, withkindset toElementReferenceandnameset to the element name. - source – Who authored the cell:
userorassistant. - collapsed – Optional. Whether the cell body is hidden in the UI.
- element – A reference to an entry in
List notebooks
GET /apis/dashboard.grafana.app/v2beta1/namespaces/{namespace}/notebooks
Returns the notebooks in the organization. Use the limit query parameter to control the maximum number of notebooks returned. To retrieve more notebooks, use the continue token from the response to fetch the next page.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Query parameters:
limit(optional): Maximum number of notebooks to return.continue(optional): Continue token from a previous response to fetch the next page.
Required permissions: notebooks:read
Example request
The following example shows a request to list notebooks:
GET /apis/dashboard.grafana.app/v2beta1/namespaces/default/notebooks?limit=1 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "NotebookList",
"apiVersion": "dashboard.grafana.app/v2beta1",
"metadata": {
"resourceVersion": "1762327800000000",
"continue": "eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ=="
},
"items": [
{
"kind": "Notebook",
"apiVersion": "dashboard.grafana.app/v2beta1",
"metadata": {
"name": "high-latency-investigation",
"namespace": "default",
"resourceVersion": "1762327800000000",
"creationTimestamp": "2026-11-05T07:30:00Z"
},
"spec": {
"title": "High latency investigation",
"tags": ["incident"],
...
}
}
]
}Get a notebook
GET /apis/dashboard.grafana.app/v2beta1/namespaces/{namespace}/notebooks/{name}
Returns the notebook with the given name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of the notebook, frommetadata.name.
Required permissions: notebooks:read
Example request
The following example shows a request to get a notebook:
GET /apis/dashboard.grafana.app/v2beta1/namespaces/default/notebooks/high-latency-investigation HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response contains the full notebook. For an example, refer to the response in Create a notebook.
Create a notebook
POST /apis/dashboard.grafana.app/v2beta1/namespaces/{namespace}/notebooks
Creates a notebook.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Required permissions: notebooks:create
Example request
The following notebook has a Markdown cell followed by a time series panel:
POST /apis/dashboard.grafana.app/v2beta1/namespaces/default/notebooks HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"metadata": {
"name": "high-latency-investigation"
},
"spec": {
"title": "High latency investigation",
"tags": ["incident"],
"timeSettings": {
"from": "now-6h",
"to": "now",
"timezone": "browser",
"autoRefresh": "",
"autoRefreshIntervals": ["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"],
"hideTimepicker": false,
"fiscalYearStartMonth": 0
},
"elements": {
"cell-1": {
"kind": "Cell",
"spec": {
"content": {
"kind": "Markdown",
"spec": {
"text": "## Summary\nLatency increased after the 07:00 deployment."
}
}
}
},
"panel-1": {
"kind": "Panel",
"spec": {
"id": 1,
"title": "Targets up",
"links": [],
"data": {
"kind": "QueryGroup",
"spec": {
"queries": [
{
"kind": "PanelQuery",
"spec": {
"refId": "A",
"hidden": false,
"query": {
"kind": "DataQuery",
"group": "prometheus",
"version": "v0",
"datasource": {
"name": "prometheus-uid"
},
"spec": {
"expr": "up"
}
}
}
}
],
"transformations": [],
"queryOptions": {}
}
},
"vizConfig": {
"kind": "VizConfig",
"group": "timeseries",
"version": "13.0.0",
"spec": {
"options": {},
"fieldConfig": {
"defaults": {},
"overrides": []
}
}
}
}
}
},
"layout": {
"kind": "NotebookLayout",
"spec": {
"cells": [
{
"kind": "NotebookLayoutItem",
"spec": {
"element": {
"kind": "ElementReference",
"name": "cell-1"
},
"source": "user"
}
},
{
"kind": "NotebookLayoutItem",
"spec": {
"element": {
"kind": "ElementReference",
"name": "panel-1"
},
"source": "user"
}
}
]
}
}
}
}JSON body schema:
- metadata.name – Optional. The unique identifier of the notebook. To let Grafana generate one, use
metadata.generateNameinstead. - spec – The notebook content. For details, refer to Notebook structure.
Example response
The following example shows the response:
HTTP/1.1 201
Content-Type: application/json
{
"kind": "Notebook",
"apiVersion": "dashboard.grafana.app/v2beta1",
"metadata": {
"name": "high-latency-investigation",
"namespace": "default",
"uid": "b6b4ea2a-0d4b-4b6f-9a0b-5d2a1c0f0e11",
"resourceVersion": "1762327800000000",
"generation": 1,
"creationTimestamp": "2026-11-05T07:30:00Z",
"annotations": {
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb"
}
},
"spec": {
"title": "High latency investigation",
"tags": ["incident"],
...
}
}Update a notebook
PUT /apis/dashboard.grafana.app/v2beta1/namespaces/{namespace}/notebooks/{name}
Replaces the notebook with the given name. Send the full notebook, including metadata.resourceVersion from the latest version you read, to prevent overwriting changes made by other users.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of the notebook.
Required permissions: notebooks:write
Example request
The following example shows a request to update a notebook:
PUT /apis/dashboard.grafana.app/v2beta1/namespaces/default/notebooks/high-latency-investigation HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"metadata": {
"name": "high-latency-investigation",
"resourceVersion": "1762327800000000"
},
"spec": {
"title": "High latency investigation - resolved",
"tags": ["incident", "resolved"],
...
}
}JSON body schema:
- metadata.name – The name of the notebook. It must match
namein the path. - metadata.resourceVersion – Optional. The resource version you’re updating. If the notebook changed since you read it, the request fails with
409. - spec – The complete notebook content. For details, refer to Notebook structure.
The response contains the updated notebook.
Example response
The response contains the updated notebook. For an example, refer to the response in Create a notebook.
Delete a notebook
DELETE /apis/dashboard.grafana.app/v2beta1/namespaces/{namespace}/notebooks/{name}
Deletes the notebook with the given name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of the notebook.
Required permissions: notebooks:delete
Example request
The following example shows a request to delete a notebook:
DELETE /apis/dashboard.grafana.app/v2beta1/namespaces/default/notebooks/high-latency-investigation HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Success",
"details": {
"name": "high-latency-investigation",
"group": "dashboard.grafana.app",
"kind": "notebooks",
"uid": "b6b4ea2a-0d4b-4b6f-9a0b-5d2a1c0f0e11"
}
}Status codes
The endpoints on this page return the following status codes:


