Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation

Grafana documentation

Developers

HTTP API

Alerting Provisioning HTTP API

Enterprise Open source

Alerting provisioning API

Information

Version

1.1.0

Content negotiation

Consumes

application/json

Produces

application/json
text/yaml
application/yaml

All endpoints

Alert rules

Method	URI	Name	Summary
DELETE	/api/v1/provisioning/alert-rules/{UID}	route delete alert rule	Delete a specific alert rule by UID.
GET	/api/v1/provisioning/alert-rules/{UID}	route get alert rule	Get a specific alert rule by UID.
GET	/api/v1/provisioning/alert-rules/{UID}/export	route get alert rule export	Export an alert rule in provisioning file format.
GET	/api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}	route get alert rule group	Get a rule group.
GET	/api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}/export	route get alert rule group export	Export an alert rule group in provisioning file format.
GET	/api/v1/provisioning/alert-rules	route get alert rules	Get all the alert rules.
GET	/api/v1/provisioning/alert-rules/export	route get alert rules export	Export all alert rules in provisioning file format.
POST	/api/v1/provisioning/alert-rules	route post alert rule	Create a new alert rule.
PUT	/api/v1/provisioning/alert-rules/{UID}	route put alert rule	Update an existing alert rule.
PUT	/api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}	route put alert rule group	Update the interval of a rule group.

Contact points

Method	URI	Name	Summary
DELETE	/api/v1/provisioning/contact-points/{UID}	route delete contactpoints	Delete a contact point.
GET	/api/v1/provisioning/contact-points	route get contactpoints	Get all the contact points.
POST	/api/v1/provisioning/contact-points	route post contactpoints	Create a contact point.
PUT	/api/v1/provisioning/contact-points/{UID}	route put contactpoint	Update an existing contact point.

Notification policies

Method	URI	Name	Summary
DELETE	/api/v1/provisioning/policies	route reset policy tree	Clears the notification policy tree.
GET	/api/v1/provisioning/policies	route get policy tree	Get the notification policy tree.
PUT	/api/v1/provisioning/policies	route put policy tree	Sets the notification policy tree.

Mute timings

Method	URI	Name	Summary
DELETE	/api/v1/provisioning/mute-timings/{name}	route delete mute timing	Delete a mute timing.
GET	/api/v1/provisioning/mute-timings/{name}	route get mute timing	Get a mute timing.
GET	/api/v1/provisioning/mute-timings	route get mute timings	Get all the mute timings.
POST	/api/v1/provisioning/mute-timings	route post mute timing	Create a new mute timing.
PUT	/api/v1/provisioning/mute-timings/{name}	route put mute timing	Replace an existing mute timing.

Templates

Method	URI	Name	Summary
DELETE	/api/v1/provisioning/templates/{name}	route delete template	Delete a template.
GET	/api/v1/provisioning/templates/{name}	route get template	Get a notification template.
GET	/api/v1/provisioning/templates	route get templates	Get all notification templates.
PUT	/api/v1/provisioning/templates/{name}	route put template	Updates an existing notification template.

Paths

Delete a specific alert rule by UID. (RouteDeleteAlertRule)

DELETE /api/v1/provisioning/alert-rules/{UID}

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
UID	`path`	string	`string`		✓		Alert rule UID
X-Disable-Provenance	`header`	string	`string`

All responses

Code	Status	Description	Has headers	Schema
204	No Content	The alert rule was deleted successfully.		schema

Responses

204 - The alert rule was deleted successfully.

Status: No Content

Schema

Delete a contact point. (RouteDeleteContactpoints)

DELETE /api/v1/provisioning/contact-points/{UID}

Consumes

application/json

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
UID	`path`	string	`string`		✓		UID is the contact point unique identifier

All responses

Code	Status	Description	Has headers	Schema
204	No Content	The contact point was deleted successfully.		schema

Responses

204 - The contact point was deleted successfully.

Status: No Content

Schema

Delete a mute timing. (RouteDeleteMuteTiming)

DELETE /api/v1/provisioning/mute-timings/{name}

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
name	`path`	string	`string`		✓		Mute timing name

All responses

Code	Status	Description	Has headers	Schema
204	No Content	The mute timing was deleted successfully.		schema

Responses

204 - The mute timing was deleted successfully.

Status: No Content

Schema

Delete a template. (RouteDeleteTemplate)

DELETE /api/v1/provisioning/templates/{name}

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
name	`path`	string	`string`		✓		Template Name

All responses

Code	Status	Description	Has headers	Schema
204	No Content	The template was deleted successfully.		schema

Responses

204 - The template was deleted successfully.

Status: No Content

Schema

Get a specific alert rule by UID. (RouteGetAlertRule)

GET /api/v1/provisioning/alert-rules/{UID}

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
UID	`path`	string	`string`		✓		Alert rule UID

All responses

Code	Status	Description	Has headers	Schema
200	OK	ProvisionedAlertRule		schema
404	Not Found	Not found.		schema

Responses

200 - ProvisionedAlertRule

Status: OK

Schema

ProvisionedAlertRule

404 - Not found.

Status: Not Found

Schema

Export an alert rule in provisioning file format. (RouteGetAlertRuleExport)

GET /api/v1/provisioning/alert-rules/{UID}/export

Produces

application/json
application/yaml
text/yaml

Parameters

Name	Source	Type	Go type	Required	Default	Description
UID	`path`	string	`string`	✓		Alert rule UID
download	`query`	boolean	`bool`			Whether to initiate a download of the file or not.
format	`query`	`string`	string		`"yaml"`	Format of the downloaded file, either yaml or json. Accept header can also be used, but the query parameter will take precedence.

All responses

Code	Status	Description	Has headers	Schema
200	OK	AlertingFileExport		schema
404	Not Found	Not found.		schema

Responses

200 - AlertingFileExport

Status: OK

Schema

AlertingFileExport

404 - Not found.

Status: Not Found

Schema

Get a rule group. (RouteGetAlertRuleGroup)

GET /api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
FolderUID	`path`	string	`string`		✓
Group	`path`	string	`string`		✓

All responses

Code	Status	Description	Has headers	Schema
200	OK	AlertRuleGroup		schema
404	Not Found	Not found.		schema

Responses

200 - AlertRuleGroup

Status: OK

Schema

AlertRuleGroup

404 - Not found.

Status: Not Found

Schema

Export an alert rule group in provisioning file format. (RouteGetAlertRuleGroupExport)

GET /api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}/export

Produces

application/json
application/yaml
text/yaml

Parameters

Name	Source	Type	Go type	Required	Default	Description
FolderUID	`path`	string	`string`	✓
Group	`path`	string	`string`	✓
download	`query`	boolean	`bool`			Whether to initiate a download of the file or not.
format	`query`	`string`	string		`"yaml"`	Format of the downloaded file, either yaml or json. Accept header can also be used, but the query parameter will take precedence.

All responses

Code	Status	Description	Has headers	Schema
200	OK	AlertingFileExport		schema
404	Not Found	Not found.		schema

Responses

200 - AlertingFileExport

Status: OK

Schema

AlertingFileExport

404 - Not found.

Status: Not Found

Schema

Get all the alert rules. (RouteGetAlertRules)

GET /api/v1/provisioning/alert-rules

All responses

Code	Status	Description	Has headers	Schema
200	OK	ProvisionedAlertRules		schema

Responses

200 - ProvisionedAlertRules

Status: OK

Schema

ProvisionedAlertRules

Export all alert rules in provisioning file format. (RouteGetAlertRulesExport)

GET /api/v1/provisioning/alert-rules/export

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
download	`query`	boolean	`bool`				Whether to initiate a download of the file or not.
format	`query`	`string`	string			`"yaml"`	Format of the downloaded file, either yaml or json. Accept header can also be used, but the query parameter will take precedence.

All responses

Code	Status	Description	Has headers	Schema
200	OK	AlertingFileExport		schema
404	Not Found	Not found.		schema

Responses

200 - AlertingFileExport

Status: OK

Schema

AlertingFileExport

404 - Not found.

Status: Not Found

Schema

Get all the contact points. (RouteGetContactpoints)

GET /api/v1/provisioning/contact-points

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
name	`query`	string	`string`				Filter by name

All responses

Code	Status	Description	Has headers	Schema
200	OK	ContactPoints		schema

Responses

200 - ContactPoints

Status: OK

Schema

ContactPoints

Get a mute timing. (RouteGetMuteTiming)

GET /api/v1/provisioning/mute-timings/{name}

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
name	`path`	string	`string`		✓		Mute timing name

All responses

Code	Status	Description	Has headers	Schema
200	OK	MuteTimeInterval		schema
404	Not Found	Not found.		schema

Responses

200 - MuteTimeInterval

Status: OK

Schema

MuteTimeInterval

404 - Not found.

Status: Not Found

Schema

Get all the mute timings. (RouteGetMuteTimings)

GET /api/v1/provisioning/mute-timings

All responses

Code	Status	Description	Has headers	Schema
200	OK	MuteTimings		schema

Responses

200 - MuteTimings

Status: OK

Schema

MuteTimings

Get the notification policy tree. (RouteGetPolicyTree)

GET /api/v1/provisioning/policies

All responses

Code	Status	Description	Has headers	Schema
200	OK	Route		schema

Responses

200 - Route

Status: OK

Schema

Route

Get a notification template. (RouteGetTemplate)

GET /api/v1/provisioning/templates/{name}

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
name	`path`	string	`string`		✓		Template Name

All responses

Code	Status	Description	Has headers	Schema
200	OK	NotificationTemplate		schema
404	Not Found	Not found.		schema

Responses

200 - NotificationTemplate

Status: OK

Schema

NotificationTemplate

404 - Not found.

Status: Not Found

Schema

Get all notification templates. (RouteGetTemplates)

GET /api/v1/provisioning/templates

All responses

Code	Status	Description	Has headers	Schema
200	OK	NotificationTemplates		schema
404	Not Found	Not found.		schema

Responses

200 - NotificationTemplates

Status: OK

Schema

NotificationTemplates

404 - Not found.

Status: Not Found

Schema

Create a new alert rule. (RoutePostAlertRule)

POST /api/v1/provisioning/alert-rules

Consumes

application/json

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
X-Disable-Provenance	`header`	string	`string`
Body	`body`	ProvisionedAlertRule	`models.ProvisionedAlertRule`

All responses

Code	Status	Description	Has headers	Schema
201	Created	ProvisionedAlertRule		schema
400	Bad Request	ValidationError		schema

Responses

201 - ProvisionedAlertRule

Status: Created

Schema

ProvisionedAlertRule

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Create a contact point. (RoutePostContactpoints)

POST /api/v1/provisioning/contact-points

Consumes

application/json

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
X-Disable-Provenance	`header`	string	`string`
Body	`body`	EmbeddedContactPoint	`models.EmbeddedContactPoint`

All responses

Code	Status	Description	Has headers	Schema
202	Accepted	EmbeddedContactPoint		schema
400	Bad Request	ValidationError		schema

Responses

202 - EmbeddedContactPoint

Status: Accepted

Schema

EmbeddedContactPoint

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Create a new mute timing. (RoutePostMuteTiming)

POST /api/v1/provisioning/mute-timings

Consumes

application/json

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
X-Disable-Provenance	`header`	string	`string`
Body	`body`	MuteTimeInterval	`models.MuteTimeInterval`

All responses

Code	Status	Description	Has headers	Schema
201	Created	MuteTimeInterval		schema
400	Bad Request	ValidationError		schema

Responses

201 - MuteTimeInterval

Status: Created

Schema

MuteTimeInterval

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Update an existing alert rule. (RoutePutAlertRule)

PUT /api/v1/provisioning/alert-rules/{UID}

Consumes

application/json

Parameters

Name	Source	Type	Go type	Required	Description
UID	`path`	string	`string`	✓	Alert rule UID
X-Disable-Provenance	`header`	string	`string`
Body	`body`	ProvisionedAlertRule	`models.ProvisionedAlertRule`

All responses

Code	Status	Description	Has headers	Schema
200	OK	ProvisionedAlertRule		schema
400	Bad Request	ValidationError		schema

Responses

200 - ProvisionedAlertRule

Status: OK

Schema

ProvisionedAlertRule

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Update the interval of a rule group. (RoutePutAlertRuleGroup)

PUT /api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}

Consumes

application/json

Parameters

Name	Source	Type	Go type	Required
FolderUID	`path`	string	`string`	✓
Group	`path`	string	`string`	✓
X-Disable-Provenance	`header`	string	`string`
Body	`body`	AlertRuleGroup	`models.AlertRuleGroup`

All responses

Code	Status	Description	Has headers	Schema
200	OK	AlertRuleGroup		schema
400	Bad Request	ValidationError		schema

Responses

200 - AlertRuleGroup

Status: OK

Schema

AlertRuleGroup

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Update an existing contact point. (RoutePutContactpoint)

PUT /api/v1/provisioning/contact-points/{UID}

Consumes

application/json

Parameters

Name	Source	Type	Go type	Required	Description
UID	`path`	string	`string`	✓	UID is the contact point unique identifier
X-Disable-Provenance	`header`	string	`string`
Body	`body`	EmbeddedContactPoint	`models.EmbeddedContactPoint`

All responses

Code	Status	Description	Has headers	Schema
202	Accepted	Ack		schema
400	Bad Request	ValidationError		schema

Responses

202 - Ack

Status: Accepted

Schema

Ack

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Replace an existing mute timing. (RoutePutMuteTiming)

PUT /api/v1/provisioning/mute-timings/{name}

Consumes

application/json

Parameters

Name	Source	Type	Go type	Required	Description
name	`path`	string	`string`	✓	Mute timing name
X-Disable-Provenance	`header`	string	`string`
Body	`body`	MuteTimeInterval	`models.MuteTimeInterval`

All responses

Code	Status	Description	Has headers	Schema
200	OK	MuteTimeInterval		schema
400	Bad Request	ValidationError		schema

Responses

200 - MuteTimeInterval

Status: OK

Schema

MuteTimeInterval

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Sets the notification policy tree. (RoutePutPolicyTree)

PUT /api/v1/provisioning/policies

Consumes

application/json

Parameters

Name	Source	Type	Go type	Separator	Required	Default	Description
X-Disable-Provenance	`header`	string	`string`
Body	`body`	Route	`models.Route`				The new notification routing tree to use

All responses

Code	Status	Description	Has headers	Schema
202	Accepted	Ack		schema
400	Bad Request	ValidationError		schema

Responses

202 - Ack

Status: Accepted

Schema

Ack

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Updates an existing notification template. (RoutePutTemplate)

PUT /api/v1/provisioning/templates/{name}

Consumes

application/json

Parameters

Name	Source	Type	Go type	Required	Description
name	`path`	string	`string`	✓	Template Name
X-Disable-Provenance	`header`	string	`string`
Body	`body`	NotificationTemplateContent	`models.NotificationTemplateContent`

All responses

Code	Status	Description	Has headers	Schema
202	Accepted	NotificationTemplate		schema
400	Bad Request	ValidationError		schema

Responses

202 - NotificationTemplate

Status: Accepted

Schema

NotificationTemplate

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Clears the notification policy tree. (RouteResetPolicyTree)

DELETE /api/v1/provisioning/policies

Consumes

application/json

All responses

Code	Status	Description	Has headers	Schema
202	Accepted	Ack		schema

Responses

202 - Ack

Status: Accepted

Schema

Ack

Models

Ack

interface{}

AlertQuery

Properties

Name	Type	Go type	Description
datasourceUid	string	`string`	Grafana data source unique identifier; it should be ‘expr’ for a Server Side Expression operation.
model	interface{}	`interface{}`	JSON is the raw JSON query and includes the above properties as well as custom properties.
queryType	string	`string`	QueryType is an optional identifier for the type of query.
It can be used to distinguish different types of queries.
refId	string	`string`	RefID is the unique identifier of the query, set by the frontend call.
relativeTimeRange	RelativeTimeRange	`RelativeTimeRange`

AlertQueryExport

Properties

Name	Type	Go type
datasourceUid	string	`string`
model	interface{}	`interface{}`
queryType	string	`string`
refId	string	`string`
relativeTimeRange	RelativeTimeRange	`RelativeTimeRange`

AlertRuleExport

Properties

Name	Type	Go type
annotations	map of string	`map[string]string`
condition	string	`string`
dasboardUid	string	`string`
data	[]alertqueryexport	`[]*AlertQueryExport`
execErrState	string	`string`
for	Duration	`Duration`
labels	map of string	`map[string]string`
noDataState	string	`string`
panelId	int64 (formatted integer)	`int64`
title	string	`string`
uid	string	`string`

AlertRuleGroup

Properties

Name	Type	Go type
folderUid	string	`string`
interval	int64 (formatted integer)	`int64`
rules	[]provisionedalertrule	`[]*ProvisionedAlertRule`
title	string	`string`

AlertRuleGroupExport

Properties

Name	Type	Go type
folder	string	`string`
interval	Duration	`Duration`
name	string	`string`
orgId	int64 (formatted integer)	`int64`
rules	[]alertruleexport	`[]*AlertRuleExport`

AlertingFileExport

Properties

Name	Type	Go type	Required	Default	Description	Example
apiVersion	int64 (formatted integer)	`int64`
groups	[]alertrulegroupexport	`[]*AlertRuleGroupExport`

ContactPoints

[]embeddedcontactpoint

Duration

Name	Type	Go type	Default	Description	Example
Duration	int64 (formatted integer)	int64

EmbeddedContactPoint

EmbeddedContactPoint is the contact point type that is used by grafanas embedded alertmanager implementation.

Properties

Name	Type	Go type	Required	Description	Example
disableResolveMessage	boolean	`bool`			`false`
name	string	`string`		Name is used as grouping key in the UI. Contact points with the
same name will be grouped in the UI.	`webhook_1`
provenance	string	`string`
settings	JSON	`JSON`	✓
type	string	`string`	✓		`webhook`
uid	string	`string`		UID is the unique identifier of the contact point. The UID can be
set by the user.	`my_external_reference`

Json

interface{}

MatchRegexps

MatchType

Name	Type	Go type	Default	Description	Example
MatchType	int64 (formatted integer)	int64

Matcher

Properties

Name	Type	Go type
Name	string	`string`
Type	MatchType	`MatchType`
Value	string	`string`

Matchers

Matchers is a slice of Matchers that is sortable, implements Stringer, and provides a Matches method to match a LabelSet against all Matchers in the slice. Note that some users of Matchers might require it to be sorted.

[]matcher

MuteTimeInterval

Properties

Name	Type	Go type	Required	Default	Description	Example
name	string	`string`
time_intervals	[]timeinterval	`[]*TimeInterval`

MuteTimings

[]mutetimeinterval

NotificationTemplate

Properties

Name	Type	Go type
name	string	`string`
provenance	Provenance	`Provenance`
template	string	`string`

NotificationTemplateContent

Properties

Name	Type	Go type	Required	Default	Description	Example
template	string	`string`

NotificationTemplates

[]notificationtemplate

ObjectMatchers

Matchers

Inlined models

Provenance

Name	Type	Go type	Default	Description	Example
Provenance	string	string

ProvisionedAlertRule

Properties

Name	Type	Go type	Required	Example
annotations	map of string	`map[string]string`		`{"runbook_url":"https://supercoolrunbook.com/page/13"}`
condition	string	`string`	✓	`A`
data	[]alertquery	`[]*AlertQuery`	✓	`[{"datasourceUid":"__expr__","model":{"conditions":[{"evaluator":{"params":[0,0],"type":"gt"},"operator":{"type":"and"},"query":{"params":[]},"reducer":{"params":[],"type":"avg"},"type":"query"}],"datasource":{"type":"__expr__","uid":"__expr__"},"expression":"1 == 1","hide":false,"intervalMs":1000,"maxDataPoints":43200,"refId":"A","type":"math"},"queryType":"","refId":"A","relativeTimeRange":{"from":0,"to":0}}]`
execErrState	string	`string`	✓
folderUID	string	`string`	✓	`project_x`
for	Duration	`Duration`	✓
id	int64 (formatted integer)	`int64`
labels	map of string	`map[string]string`		`{"team":"sre-team-1"}`
noDataState	string	`string`	✓
orgID	int64 (formatted integer)	`int64`	✓
provenance	Provenance	`Provenance`
ruleGroup	string	`string`	✓	`eval_group_1`
title	string	`string`	✓	`Always firing`
uid	string	`string`
updated	date-time (formatted string)	`strfmt.DateTime`

ProvisionedAlertRules

[]provisionedalertrule

Regexp

A Regexp is safe for concurrent use by multiple goroutines, except for configuration methods, such as Longest.

interface{}

RelativeTimeRange

RelativeTimeRange is the per query start and end time for requests.

Properties

Name	Type	Go type	Required	Default	Description	Example
from	Duration	`Duration`
to	Duration	`Duration`

Route

A Route is a node that contains definitions of how to handle alerts. This is modified from the upstream alertmanager in that it adds the ObjectMatchers property.

Properties

Name	Type	Go type	Description
continue	boolean	`bool`
group_by	[]string	`[]string`
group_interval	string	`string`
group_wait	string	`string`
match	map of string	`map[string]string`	Deprecated. Remove before v1.0 release.
match_re	MatchRegexps	`MatchRegexps`
matchers	Matchers	`Matchers`
mute_time_intervals	[]string	`[]string`
object_matchers	ObjectMatchers	`ObjectMatchers`
provenance	Provenance	`Provenance`
receiver	string	`string`
repeat_interval	string	`string`
routes	[]route	`[]*Route`

TimeInterval

TimeInterval describes intervals of time. ContainsTime will tell you if a golang time is contained within the interval.

Properties

Name	Type	Go type
days_of_month	[]string	`[]string`
location	string	`string`
months	[]string	`[]string`
times	[]timerange	`[]*TimeRange`
weekdays	[]string	`[]string`
years	[]string	`[]string`