openapi: 3.0.3
info:
title: Grafana HTTP Access Dashboards API
description: The Grafana HTTP API provides programmatic access to Grafana's core functionality including dashboards, data sources, alerts, users, organizations, folders, annotations, and teams. Authentication is handled via API keys, basic auth, or OAuth tokens passed in the Authorization header.
version: 11.0.0
contact:
name: Grafana Labs
url: https://grafana.com
license:
name: AGPL-3.0
url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: https://{instance}.grafana.net/api
description: Grafana Cloud
variables:
instance:
default: your-instance
- url: http://localhost:3000/api
description: Local Grafana instance
security:
- BearerAuth: []
- BasicAuth: []
- ApiKeyAuth: []
tags:
- name: Dashboards
description: Manage dashboards
paths:
/dashboards/db:
parameters: []
post:
tags:
- Dashboards
operationId: createUpdateDashboard
summary: Create or update a dashboard
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SaveDashboardCommand'
responses:
'200':
description: Dashboard saved
content:
application/json:
schema:
$ref: '#/components/schemas/SaveDashboardResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/dashboards/uid/{uid}:
parameters: []
get:
tags:
- Dashboards
operationId: getDashboardByUid
summary: Get dashboard by UID
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Dashboard found
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardFullWithMeta'
'404':
$ref: '#/components/responses/NotFound'
delete:
tags:
- Dashboards
operationId: deleteDashboardByUid
summary: Delete dashboard by UID
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Dashboard deleted
'404':
$ref: '#/components/responses/NotFound'
/search:
get:
tags:
- Dashboards
operationId: searchDashboards
summary: Search dashboards and folders
parameters:
- name: query
in: query
schema:
type: string
- name: tag
in: query
schema:
type: array
items:
type: string
- name: type
in: query
schema:
type: string
enum:
- dash-folder
- dash-db
- name: folderIds
in: query
schema:
type: array
items:
type: integer
- name: limit
in: query
schema:
type: integer
default: 1000
- name: page
in: query
schema:
type: integer
default: 1
responses:
'200':
description: Search results
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DashboardSearchHit'
/reports/dashboards/{uid}:
parameters: []
get:
tags:
- Dashboards
summary: Grafana Get Reports By Dashboard UID
description: This API operation retrieves all reports associated with a specific Grafana dashboard by using its unique identifier (UID). When you make a GET request to the endpoint /reports/dashboards/{uid}, where {uid} is replaced with the actual dashboard's UID, Grafana returns a list of all reports that have been configured for that particular dashboard. This is useful for administrators or users who need to view, audit, or manage the reporting configurations linked to a specific dashboard, allowing them to see details such as report schedules, recipients, formats, and other report-specific settings without having to search through all reports in the system.
operationId: getReportsByDashboardUID
parameters:
- name: uid
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Report'
description: ''
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/admin/provisioning/dashboards/reload:
parameters: []
post:
tags:
- Dashboards
summary: Grafana Admin Provisioning Reload Dashboards
description: This API operation is a POST request to the '/admin/provisioning/dashboards/reload' endpoint in Grafana that allows administrators to trigger a reload of provisioned dashboards without requiring a full Grafana server restart. When invoked, this endpoint scans the configured provisioning directories and reloads all dashboard configurations, applying any changes made to the provisioning files such as new dashboards, modifications to existing ones, or deletions. This is particularly useful in automated environments or when managing dashboards as code, as it enables administrators to update dashboard configurations dynamically and see changes reflected immediately in the Grafana instance without service interruption.
operationId: adminProvisioningReloadDashboards
parameters: []
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
security:
- basic: []
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboard/snapshots:
parameters: []
get:
tags:
- Dashboards
summary: Grafana Search Dashboard Snapshots
description: Retrieves a list of dashboard snapshots based on specified search criteria. This operation allows users to query and filter existing snapshots that have been created from Grafana dashboards, returning metadata about each snapshot such as its name, key, creation timestamp, and expiration details. Users can apply various parameters to narrow down results, including searching by snapshot name, limiting the number of results returned, or filtering by tags. The endpoint is useful for managing and discovering previously created dashboard snapshots without needing to access the full dashboard interface.
operationId: searchDashboardSnapshots
parameters:
- name: query
in: query
description: Search Query
style: form
explode: true
schema:
type: string
- name: limit
in: query
description: Limit the number of returned results
style: form
explode: true
schema:
type: integer
contentEncoding: int64
default: 1000
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DashboardSnapshotDTO'
description: ''
contentMediaType: application/json
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/home:
parameters: []
get:
tags:
- Dashboards
summary: Grafana Get Home Dashboard
description: The Grafana Get Home Dashboard API operation retrieves the dashboard that is configured as the home dashboard for the current user or organization. When a GET request is made to the /dashboards/home endpoint, it returns the dashboard data that should be displayed when a user first logs into Grafana or navigates to the home page. This endpoint is useful for applications that need to programmatically access the default landing dashboard, whether it's a custom dashboard set by an administrator or the default Grafana home dashboard. The response includes the dashboard JSON model along with metadata such as the dashboard's unique identifier, title, and other configuration settings.
operationId: getHomeDashboard
parameters: []
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Gethomedashboardresponse.'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: true
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/id/{DashboardID}/permissions:
parameters: []
get:
tags:
- Dashboards
summary: Grafana Get Dashboard Permissions List By ID
description: This API operation retrieves the complete list of permissions associated with a specific Grafana dashboard by providing its unique dashboard identifier. It returns details about which users, teams, or roles have access to the dashboard and what level of permissions they possess (such as view, edit, or admin rights). The GET request to this endpoint allows administrators to audit and review the current access control settings for a dashboard, making it useful for security compliance, permission management, and understanding who can interact with specific dashboards within the Grafana instance.
operationId: getDashboardPermissionsListByID
parameters:
- name: DashboardID
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DashboardACLInfoDTO'
description: ''
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: true
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
post:
tags:
- Dashboards
summary: Grafana Update Dashboard Permissions By ID
description: This API operation allows administrators to modify the access control permissions for a specific Grafana dashboard by providing its unique dashboard ID in the URL path. By sending a POST request to this endpoint with the appropriate permission payload, users can grant or revoke access rights for teams, users, or roles, defining who can view, edit, or administer the dashboard. The operation requires proper authentication and authorization, typically at an administrator or dashboard owner level, and accepts a JSON body containing the new permission settings that specify the permission level (viewer, editor, or admin) along with the corresponding user IDs, team IDs, or role identifiers to be applied to the target dashboard.
operationId: updateDashboardPermissionsByID
parameters:
- name: DashboardID
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDashboardACLCommand'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: true
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/id/{DashboardID}/versions:
parameters: []
get:
tags:
- Dashboards
summary: Grafana Get Dashboard Versions By ID
description: Retrieves the version history of a specific Grafana dashboard identified by its unique dashboard ID. This operation returns a list of all saved versions for the dashboard, including metadata such as version numbers, timestamps, user information who made the changes, and version messages or notes. It allows administrators and users to track changes made to a dashboard over time, compare different versions, and understand the evolution of dashboard configurations, which is useful for auditing purposes, troubleshooting issues introduced by recent changes, or reverting to previous dashboard states if needed.
operationId: getDashboardVersionsByID
parameters:
- name: DashboardID
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardVersionResponseMeta'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: true
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/id/{DashboardID}/versions/{DashboardVersionID}:
parameters: []
get:
tags:
- Dashboards
summary: Grafana Get Dashboard Version By ID
description: This API operation retrieves a specific version of a Grafana dashboard by providing both the dashboard's unique identifier and the desired version identifier. When invoked using the GET method, it returns the complete configuration and metadata for that particular version of the dashboard, allowing users to view historical snapshots, compare changes between versions, or restore previous dashboard states. This is particularly useful for auditing dashboard modifications, understanding what changes were made over time, and recovering from unwanted updates by accessing earlier working versions of a dashboard's configuration.
operationId: getDashboardVersionByID
parameters:
- name: DashboardID
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
- name: DashboardVersionID
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardVersionMeta'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: true
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/import:
parameters: []
post:
tags:
- Dashboards
summary: Grafana Import Dashboard
description: This API operation allows users to import a dashboard into Grafana by sending a POST request to the /dashboards/import endpoint. The operation accepts dashboard configuration data, typically in JSON format, which can include the complete dashboard definition, settings, and panel configurations. Users can import dashboards that were previously exported from Grafana or created externally, specify the target folder for the imported dashboard, and optionally override certain properties like the dashboard's unique identifier or data source mappings. This endpoint is commonly used for sharing dashboards between Grafana instances, automating dashboard deployment, or restoring dashboard backups, making it an essential tool for dashboard management and migration workflows.
operationId: importDashboard
parameters: []
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ImportDashboardRequestrequestobjectforimportingadashboard.'
required: true
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ImportDashboardResponseresponseobjectreturnedwhenimportingadashboard.'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'412':
description: PreconditionFailedError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'422':
description: UnprocessableEntityError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/interpolate:
parameters: []
post:
tags:
- Dashboards
summary: Grafana Interpolate Dashboard
description: This API operation performs variable interpolation on Grafana dashboard elements by resolving template variables within dashboard configurations. When invoked via POST request to the /dashboards/interpolate endpoint, it processes dashboard JSON payloads containing template variable syntax (such as $variable or [[variable]]) and replaces these placeholders with their actual values based on the current dashboard context, time range, data source queries, or user-defined variable values, returning the fully interpolated dashboard configuration that can be rendered with concrete values rather than abstract variable references.
operationId: interpolateDashboard
parameters: []
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
contentMediaType: application/json
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'422':
description: UnprocessableEntityError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/public-dashboards:
parameters: []
get:
tags:
- Dashboards
summary: Grafana List Public Dashboards
description: This API operation retrieves a list of all public dashboards available in Grafana. It uses a GET request to the /dashboards/public-dashboards endpoint and returns information about dashboards that have been made publicly accessible, meaning they can be viewed without authentication. The response typically includes details such as dashboard UIDs, titles, access tokens, and configuration settings for each public dashboard. This endpoint is useful for administrators who need to audit or manage which dashboards are publicly shared and review their sharing settings.
operationId: listPublicDashboards
parameters: []
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/PublicDashboardListResponseWithPagination'
'401':
description: UnauthorisedPublicError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/publicError1'
'403':
description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/publicError1'
'500':
description: InternalServerPublicError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/publicError1'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/tags:
parameters: []
get:
tags:
- Dashboards
summary: Grafana Get Dashboard Tags
description: This API operation retrieves all tags that have been assigned to dashboards within the Grafana instance. When called, it returns a list of unique tags used across all dashboards, which can be helpful for filtering, organizing, or discovering dashboards based on their categorization. The endpoint is accessed via a GET request to /dashboards/tags and typically returns an array of tag objects containing information about each tag's name and count of associated dashboards. This is commonly used in dashboard management interfaces or when building custom dashboard discovery tools.
operationId: getDashboardTags
parameters: []
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DashboardTagCloudItem'
description: ''
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/dashboards/uid/{dashboardUid}/public-dashboards:
parameters: []
get:
tags:
- Dashboards
summary: Grafana Get Public Dashboard
description: This API operation retrieves the public dashboard configuration for a specific Grafana dashboard identified by its unique identifier (dashboardUid). When a dashboard has been made publicly accessible, this GET endpoint returns the
# --- truncated at 32 KB (123 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-dashboards-api-openapi.yml