Grafana HTTP API
RESTful API for managing Grafana resources including dashboards, data sources, alert rules, users, organizations, folders, annotations, and teams. Supports authentication via API keys, basic auth, and OAuth tokens.
OpenAPI Specification
openapi: 3.0.3
info:
title: Grafana HTTP 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
- name: Data Sources
description: Manage data source connections
- name: Alerts
description: Alerting rules and notifications
- name: Users
description: User management
- name: Organizations
description: Organization management
- name: Folders
description: Dashboard folder management
- name: Annotations
description: Dashboard annotations
- name: Teams
description: Team management
paths:
# ── Dashboards ──────────────────────────────────────────────
/dashboards/db:
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}:
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'
# ── Data Sources ────────────────────────────────────────────
/datasources:
get:
tags: [Data Sources]
operationId: getDataSources
summary: List all data sources
responses:
'200':
description: Data sources list
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataSource'
post:
tags: [Data Sources]
operationId: createDataSource
summary: Create a data source
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDataSourceCommand'
responses:
'200':
description: Data source created
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'409':
description: Data source with same name already exists
/datasources/{id}:
get:
tags: [Data Sources]
operationId: getDataSourceById
summary: Get data source by ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Data source found
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'404':
$ref: '#/components/responses/NotFound'
put:
tags: [Data Sources]
operationId: updateDataSource
summary: Update data source by ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDataSourceCommand'
responses:
'200':
description: Data source updated
delete:
tags: [Data Sources]
operationId: deleteDataSourceById
summary: Delete data source by ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Data source deleted
/datasources/uid/{uid}:
get:
tags: [Data Sources]
operationId: getDataSourceByUid
summary: Get data source by UID
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Data source found
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
# ── Alert Rules (Unified Alerting) ─────────────────────────
/v1/provisioning/alert-rules:
get:
tags: [Alerts]
operationId: getAlertRules
summary: List all alert rules
responses:
'200':
description: Alert rules
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AlertRule'
post:
tags: [Alerts]
operationId: createAlertRule
summary: Create an alert rule
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AlertRule'
responses:
'201':
description: Alert rule created
content:
application/json:
schema:
$ref: '#/components/schemas/AlertRule'
/v1/provisioning/alert-rules/{uid}:
get:
tags: [Alerts]
operationId: getAlertRule
summary: Get alert rule by UID
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Alert rule
content:
application/json:
schema:
$ref: '#/components/schemas/AlertRule'
put:
tags: [Alerts]
operationId: updateAlertRule
summary: Update alert rule
parameters:
- name: uid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AlertRule'
responses:
'200':
description: Alert rule updated
delete:
tags: [Alerts]
operationId: deleteAlertRule
summary: Delete alert rule
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'204':
description: Alert rule deleted
/v1/provisioning/contact-points:
get:
tags: [Alerts]
operationId: getContactPoints
summary: List contact points
responses:
'200':
description: Contact points
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ContactPoint'
post:
tags: [Alerts]
operationId: createContactPoint
summary: Create a contact point
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactPoint'
responses:
'202':
description: Contact point created
# ── Users ───────────────────────────────────────────────────
/admin/users:
post:
tags: [Users]
operationId: adminCreateUser
summary: Create a new user (admin)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserCommand'
responses:
'200':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserResponse'
/users:
get:
tags: [Users]
operationId: searchUsers
summary: Search users
parameters:
- name: perpage
in: query
schema:
type: integer
default: 1000
- name: page
in: query
schema:
type: integer
default: 1
- name: query
in: query
schema:
type: string
responses:
'200':
description: Users found
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserSearchHit'
/users/{id}:
get:
tags: [Users]
operationId: getUserById
summary: Get user by ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: User found
content:
application/json:
schema:
$ref: '#/components/schemas/User'
put:
tags: [Users]
operationId: updateUser
summary: Update user
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserCommand'
responses:
'200':
description: User updated
/user:
get:
tags: [Users]
operationId: getCurrentUser
summary: Get current user
responses:
'200':
description: Current user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
# ── Organizations ───────────────────────────────────────────
/orgs:
get:
tags: [Organizations]
operationId: searchOrgs
summary: Search organizations
parameters:
- name: query
in: query
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: perpage
in: query
schema:
type: integer
responses:
'200':
description: Organizations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Organization'
post:
tags: [Organizations]
operationId: createOrg
summary: Create organization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrgCommand'
responses:
'200':
description: Organization created
/orgs/{orgId}:
get:
tags: [Organizations]
operationId: getOrgById
summary: Get organization by ID
parameters:
- name: orgId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Organization
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
put:
tags: [Organizations]
operationId: updateOrg
summary: Update organization
parameters:
- name: orgId
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateOrgCommand'
responses:
'200':
description: Organization updated
delete:
tags: [Organizations]
operationId: deleteOrg
summary: Delete organization
parameters:
- name: orgId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Organization deleted
/orgs/{orgId}/users:
get:
tags: [Organizations]
operationId: getOrgUsers
summary: Get users in organization
parameters:
- name: orgId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Organization users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OrgUser'
post:
tags: [Organizations]
operationId: addOrgUser
summary: Add user to organization
parameters:
- name: orgId
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddOrgUserCommand'
responses:
'200':
description: User added
# ── Folders ─────────────────────────────────────────────────
/folders:
get:
tags: [Folders]
operationId: getFolders
summary: List all folders
parameters:
- name: limit
in: query
schema:
type: integer
default: 1000
- name: page
in: query
schema:
type: integer
default: 1
responses:
'200':
description: Folders
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Folder'
post:
tags: [Folders]
operationId: createFolder
summary: Create a folder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFolderCommand'
responses:
'200':
description: Folder created
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
/folders/{uid}:
get:
tags: [Folders]
operationId: getFolderByUid
summary: Get folder by UID
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Folder
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
put:
tags: [Folders]
operationId: updateFolder
summary: Update folder
parameters:
- name: uid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFolderCommand'
responses:
'200':
description: Folder updated
delete:
tags: [Folders]
operationId: deleteFolder
summary: Delete folder
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Folder deleted
# ── Annotations ─────────────────────────────────────────────
/annotations:
get:
tags: [Annotations]
operationId: getAnnotations
summary: Find annotations
parameters:
- name: from
in: query
schema:
type: integer
description: Epoch timestamp in milliseconds
- name: to
in: query
schema:
type: integer
- name: dashboardId
in: query
schema:
type: integer
- name: panelId
in: query
schema:
type: integer
- name: tags
in: query
schema:
type: array
items:
type: string
- name: limit
in: query
schema:
type: integer
default: 100
responses:
'200':
description: Annotations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Annotation'
post:
tags: [Annotations]
operationId: createAnnotation
summary: Create annotation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationCommand'
responses:
'200':
description: Annotation created
/annotations/{id}:
delete:
tags: [Annotations]
operationId: deleteAnnotation
summary: Delete annotation
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Annotation deleted
# ── Teams ───────────────────────────────────────────────────
/teams/search:
get:
tags: [Teams]
operationId: searchTeams
summary: Search teams
parameters:
- name: query
in: query
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: perpage
in: query
schema:
type: integer
responses:
'200':
description: Teams
content:
application/json:
schema:
$ref: '#/components/schemas/TeamSearchResult'
/teams:
post:
tags: [Teams]
operationId: createTeam
summary: Create team
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTeamCommand'
responses:
'200':
description: Team created
/teams/{id}:
get:
tags: [Teams]
operationId: getTeamById
summary: Get team by ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Team
content:
application/json:
schema:
$ref: '#/components/schemas/Team'
put:
tags: [Teams]
operationId: updateTeam
summary: Update team
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTeamCommand'
responses:
'200':
description: Team updated
delete:
tags: [Teams]
operationId: deleteTeam
summary: Delete team
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Team deleted
/teams/{id}/members:
get:
tags: [Teams]
operationId: getTeamMembers
summary: Get team members
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Team members
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TeamMember'
post:
tags: [Teams]
operationId: addTeamMember
summary: Add team member
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddTeamMemberCommand'
responses:
'200':
description: Member added
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Service account token or API key
BasicAuth:
type: http
scheme: basic
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: 'Format: Bearer <api-key>'
responses:
Unauthorized:
description: Unauthorized - invalid or missing authentication
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Forbidden - insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ErrorResponse:
type: object
properties:
message:
type: string
status:
type: string
# ── Dashboard Schemas ───────────────────────────────────
SaveDashboardCommand:
type: object
required: [dashboard]
properties:
dashboard:
$ref: '#/components/schemas/Dashboard'
folderId:
type: integer
description: Deprecated - use folderUid
folderUid:
type: string
overwrite:
type: boolean
default: false
message:
type: string
description: Commit message for version history
SaveDashboardResponse:
type: object
properties:
id:
type: integer
uid:
type: string
url:
type: string
status:
type: string
version:
type: integer
slug:
type: string
DashboardFullWithMeta:
type: object
properties:
meta:
$ref: '#/components/schemas/DashboardMeta'
dashboard:
$ref: '#/components/schemas/Dashboard'
DashboardMeta:
type: object
properties:
isStarred:
type: boolean
slug:
type: string
url:
type: string
folderId:
type: integer
folderUid:
type: string
folderTitle:
type: string
folderUrl:
type: string
canSave:
type: boolean
canEdit:
type: boolean
canAdmin:
type: boolean
canStar:
type: boolean
canDelete:
type: boolean
created:
type: string
format: date-time
updated:
type: string
format: date-time
createdBy:
type: string
updatedBy:
type: string
version:
type: integer
provisioned:
type: boolean
provisionedExternalId:
type: string
Dashboard:
type: object
properties:
id:
type: integer
nullable: true
description: Null when creating a new dashboard
uid:
type: string
title:
type: string
tags:
type: array
items:
type: string
timezone:
type: string
default: browser
schemaVersion:
type: integer
version:
type: integer
refresh:
type: string
description: 'Auto-refresh interval, e.g. 5s, 1m, 1h'
time:
type: object
properties:
from:
type: string
to:
type: string
timepicker:
type: object
properties:
refresh_intervals:
type: array
items:
type: string
time_options:
type: array
items:
type: string
templating:
type: object
properties:
list:
type: array
items:
$ref: '#/components/schemas/TemplateVariable'
annotations:
type: object
properties:
list:
type: array
items:
type: object
panels:
type: array
items:
$ref: '#/components/schemas/Panel'
editable:
type: boolean
default: true
fiscalYearStartMonth:
type: integer
graphTooltip:
type: integer
enum: [0, 1, 2]
description: '0: default, 1: shared crosshair, 2: shared tooltip'
links:
type: array
items:
$ref: '#/components/schemas/DashboardLink'
liveNow:
type: boolean
Panel:
type: object
properties:
id:
type: integer
type:
type: string
description: 'Panel plugin type, e.g. timeseries, stat, gauge, table, barchart, etc.'
title:
type: string
description:
type: string
gridPos:
type: object
properties:
h:
type: integer
w:
type: integer
x:
type: integer
'y':
type: integer
datasource:
type: object
properties:
type:
type: string
uid:
type: string
targets:
type: array
items:
$ref: '#/components/schemas/Target'
fieldConfig:
type: object
properties:
defaults:
type: object
properties:
unit:
type: string
min:
type: number
max:
type: number
decimals:
type: integer
thresholds:
type: object
properties:
mode:
type: string
enum: [absolute, percentage]
steps:
type: array
items:
type: object
properties:
color:
type: string
value:
type: number
nullable: true
color:
type: object
properties:
mode:
type: string
mappings:
type: array
items:
type: object
overrides:
type: array
items:
type: object
options:
type: object
description: Panel-type-specific options
transformations:
type: array
items:
type: object
properties:
id:
type: string
options:
type: object
transparent:
type: boolean
links:
type: array
items:
type: object
repeat:
type: string
description: Variable name to repeat panel for
repeatDirection:
type: string
enum: [h, v]
maxPerRow:
type: integer
Target:
type: object
description: Query target - structure varies by data source type
properties:
refId:
type: string
datasource:
type: object
properties:
type:
type: string
uid:
type: string
expr:
type: string
description: Prometheus query expression
rawSql:
type: string
description: SQL query for SQL-based data sources
format:
type: string
legendFormat:
type: string
interval:
type: string
hide:
type: boolean
TemplateVariable:
type: object
properties:
name:
type: string
type:
type: string
enum: [query, custom, constant, datasource, interval, textbox, adhoc]
label:
type: string
datasource:
type: object
query:
type: string
current:
type: object
hide:
type: integer
enum: [0, 1, 2]
multi:
type: boolean
includeAll:
type: boolean
allValue:
type: string
refresh:
type: integer
enum: [0, 1, 2]
sort:
type: integer
DashboardLink:
type: object
properties:
title:
type: string
type:
type: string
enum: [dashboards, link]
url:
type: string
tags:
type: array
items:
type: string
targetBlank:
type: boolean
asDropdown:
type: boolean
icon:
type: string
includeVars:
type: boolean
keepTime:
type: boolean
DashboardSearchHit:
type: object
properties:
id:
type: integer
uid:
type: string
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-api.yml