api-reference

37 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

GET /api/frontend/settings endpoint

The GET /api/frontend/settings endpoint returns frontend settings for Grafana. It accepts JSON content type and requires Bearer token authentication. The response includes allowOrgCreate (boolean), appSubUrl (string), buildInfo object with buildstamp, commit, and version fields, datasources object containing datasource configurations with index and meta information, and defaultDatasource (string) field.

GET /api/login/ping endpoint

The GET /api/login/ping endpoint renews a session based on the remember cookie. It accepts JSON content type and requires Bearer token authentication. The response returns a simple JSON message field containing 'Logged in' text.

GET /api/health endpoint

The GET /api/health endpoint returns health information about a Grafana instance. It accepts JSON content type and does not require authentication. The response returns a 200 OK status with commit (string), database (string indicating status), and version (string) fields.

Frontend Settings API is deprecated

The Frontend Settings API is documented in a deprecated APIs section and should not be used for new integrations.

Team Sync API overview and availability

Team Sync API is only available in Grafana Enterprise. It provides endpoints for managing external group synchronization with teams. For some endpoints, specific permissions based on role-based access control are required.

Get External Groups endpoint

GET /api/teams/:teamId/groups retrieves external groups associated with a team. Required permission: teams.permissions:read with scope teams:*. Returns 200 Ok with array of objects containing orgId, teamId, and groupId. Status codes: 200 Ok, 401 Unauthorized, 403 Permission denied.

Add External Group endpoint

POST /api/teams/:teamId/groups adds an external group to a team. Required permission: teams.permissions:write with scope teams:*. Request body contains groupId field. Returns 200 Ok with 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 endpoint

DELETE /api/teams/:teamId/groups?groupId=external-group-id removes an external group from a team. Required permission: teams.permissions:write with scope teams:*. The groupId query parameter must contain the external group ID. Returns 200 Ok with message 'Team Group removed'. Status codes: 200 Ok, 401 Unauthorized, 403 Permission denied, 404 Team not found/Group not found.

Search Team Groups endpoint

GET /api/teams/:teamId/groups/search searches for team groups with pagination support. Required permission: teams.permissions:read with scope teams:*. Query parameters include name, query, page, and perpage. Returns 200 Ok with object containing totalCount, teamGroups array, page, and perPage fields. Status codes: 200 Ok, 400 Bad Request (invalid team ID format or missing query parameter), 401 Unauthorized, 403 Permission denied, 500 Internal Server Error.

Playlist metadata fields

Playlist metadata contains: name (the UID of the playlist, required for creation and operations), namespace (typically 'default'), resourceVersion (returned by server, required for updates), and creationTimestamp (set by server).

Playlist API available in Grafana 12 and later

The Playlist API is available in Grafana 12 and later. It complies with the new Grafana API structure.

Get a Playlist endpoint

GET /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists/:name retrieves a specific playlist by name (UID). Requires Bearer token authentication. Returns a single Playlist object.

Create a Playlist endpoint

POST /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists creates a new playlist. Requires Bearer token authentication and Content-Type: application/json header. Request body must include kind, apiVersion, metadata with name, and spec with title, interval, and items array. Returns HTTP 201 Created with the created Playlist object.

Update a Playlist endpoint

PUT /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists/:name updates an existing playlist. Requires Bearer token authentication and Content-Type: application/json header. The entire playlist spec must be provided in the request body including resourceVersion. Returns HTTP 200 OK with the updated Playlist object.

Delete a Playlist endpoint

DELETE /apis/playlist.grafana.app/v1/namespaces/:namespace/playlists/:name deletes a playlist. Requires Bearer token authentication. Returns HTTP 200 OK with a Status object indicating success.

Playlist spec fields

A Playlist spec contains: title (string, required), interval (string, required, format example: '5m'), and items (array of playlist items, required).

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), and dashboard_by_id (deprecated, include a dashboard by internal ID). Each item has a type field and a value field.

Dashboard metadata fields in API response

The Dashboard API response metadata includes: name (unique identifier), namespace, uid (the full unique identifier), resourceVersion, generation, creationTimestamp, labels (including grafana.app/deprecatedInternalID), and annotations (including grafana.app/createdBy, grafana.app/updatedBy, grafana.app/updatedTimestamp, and optionally grafana.app/folder). The managedFields section tracks API operations and field modifications.

Dashboard HTTP API endpoints available in Grafana 12+

The Dashboard HTTP API is available in Grafana 12 and later and complies with the new Grafana API structure. It provides six main endpoints: POST to create dashboards, PUT to update dashboards, GET to retrieve dashboards (standard or DTO format), GET to list dashboards, and DELETE to remove dashboards. All endpoints use the base path /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards with optional :uid parameter for individual dashboard operations.

Create Dashboard endpoint and permissions

The POST /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards endpoint creates a new dashboard. Required permissions are: dashboards:create with scope folders:* or folders:uid:*, OR dashboards:write with scope dashboards:* OR dashboards:uid:* OR folders:* OR folders:uid:*.

Dashboard Create request body schema

The Create Dashboard request body must contain: metadata.name (the unique identifier, or set metadata.generateName with a prefix for random uid generation), metadata.annotations.grafana.app/folder (optional, the folder uid where dashboard should be created), and spec (the dashboard JSON configuration). Custom labels and annotations in the metadata field are supported on some instances with full support planned.

Create Dashboard response status codes

The Create Dashboard endpoint returns: 201 (Created), 400 (Errors such as invalid json or missing fields), 401 (Unauthorized), 403 (Access denied), or 409 (Conflict when dashboard with same uid already exists).

Update Dashboard endpoint and permissions

The PUT /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards/:uid endpoint updates an existing dashboard via the dashboard uid. Required permission is dashboards:write with scope dashboards:* OR dashboards:uid:* OR folders:* OR folders:uid:*.

Dashboard Update request body schema

The Update Dashboard request body must contain: metadata.name (the unique identifier), metadata.annotations.grafana.app/folder (optional, the folder uid), metadata.annotations.grafana.app/message (optional, for setting a commit message in version history), and spec (the dashboard JSON configuration). The uid in the URL path must match the dashboard being updated.

Update Dashboard response status codes

The Update Dashboard endpoint returns: 200 (OK), 400 (Errors such as invalid json or missing fields), 401 (Unauthorized), 403 (Access denied), or 409 (Conflict when dashboard with same version already exists).

Get Dashboard DTO endpoint for access information

The GET /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards/:uid/dto endpoint retrieves a dashboard with additional access information in an access section, including whether it is a public dashboard and the dashboard permissions (admin, editor) of the requesting user.

List Dashboards endpoint and permissions

The GET /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards endpoint lists all dashboards in the given organization. Required permission is dashboards:read with scope dashboards:* OR dashboards:uid:* OR folders:* OR folders:uid:*.

List Dashboards query parameters

The List Dashboards endpoint accepts two optional query parameters: limit (maximum number of dashboards to return) and continue (a token from a previous response to fetch the next page of dashboards). Pagination is handled by including the metadata.continue token from the response in subsequent requests until a response without a continue field is received.

List Dashboards response status codes

The List Dashboards endpoint returns: 200 (OK), 401 (Unauthorized), or 403 (Access denied).

Delete Dashboard endpoint and permissions

The DELETE /apis/dashboard.grafana.app/v1/namespaces/:namespace/dashboards/:uid endpoint deletes a dashboard via the dashboard uid. Required permission is dashboards:delete with scope dashboards:* OR dashboards:uid:* OR folders:* OR folders:uid:*.

Dashboard version history retrieval

The full version history of a dashboard can be retrieved using the List endpoint with specific query parameters, with details and examples available in the Resource history HTTP API documentation.

Delete Dashboard uid parameter clarification

The uid parameter in the DELETE endpoint path must be the metadata.name field from the dashboard response, not the metadata.uid field.

Delete Dashboard response status codes

The Delete Dashboard endpoint returns: 200 (OK), 401 (Unauthorized), 403 (Access denied), or 404 (Not found).

Create Dashboard example with all required fields

Example Create Dashboard request showing metadata with name "gdxccn" and optional folder annotation, and spec containing annotations list, editable flag, fiscal year start month, graph tooltip, links array, panels array with datasource, field config with defaults and overrides, grid position, options, and targets, preload flag, schema version 41, tags, templating list with variables, time range, timepicker, timezone "browser", title, and version. The example includes a timeseries panel with custom field options for axis, line style, stacking, thresholds, and legend/tooltip display.

Dashboard API schema version

The dashboard schema version used in the API examples is 41.

/api endpoints deprecated in Grafana 13

Starting in Grafana 13, /api endpoints are being deprecated in favor of the /apis route. Legacy APIs are not being disabled and remain fully accessible and operative, but /api routes will no longer be updated.

Legacy API deprecation does not break current setup

The transition from /api to /apis endpoints does not disrupt or break current setups. Legacy APIs remain fully accessible and operative.

Give your agent this brain