Menu

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.

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

MethodURINameSummary
DELETE/api/v1/provisioning/alert-rules/{UID}route delete alert ruleDelete a specific alert rule by UID.
GET/api/v1/provisioning/alert-rules/{UID}route get alert ruleGet a specific alert rule by UID.
GET/api/v1/provisioning/alert-rules/{UID}/exportroute get alert rule exportExport an alert rule in provisioning file format.
GET/api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}route get alert rule groupGet a rule group.
GET/api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}/exportroute get alert rule group exportExport an alert rule group in provisioning file format.
GET/api/v1/provisioning/alert-rulesroute get alert rulesGet all the alert rules.
GET/api/v1/provisioning/alert-rules/exportroute get alert rules exportExport all alert rules in provisioning file format.
POST/api/v1/provisioning/alert-rulesroute post alert ruleCreate a new alert rule.
PUT/api/v1/provisioning/alert-rules/{UID}route put alert ruleUpdate an existing alert rule.
PUT/api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}route put alert rule groupUpdate the interval of a rule group.

Contact points

MethodURINameSummary
DELETE/api/v1/provisioning/contact-points/{UID}route delete contactpointsDelete a contact point.
GET/api/v1/provisioning/contact-pointsroute get contactpointsGet all the contact points.
POST/api/v1/provisioning/contact-pointsroute post contactpointsCreate a contact point.
PUT/api/v1/provisioning/contact-points/{UID}route put contactpointUpdate an existing contact point.

Notification policies

MethodURINameSummary
DELETE/api/v1/provisioning/policiesroute reset policy treeClears the notification policy tree.
GET/api/v1/provisioning/policiesroute get policy treeGet the notification policy tree.
PUT/api/v1/provisioning/policiesroute put policy treeSets the notification policy tree.

Mute timings

MethodURINameSummary
DELETE/api/v1/provisioning/mute-timings/{name}route delete mute timingDelete a mute timing.
GET/api/v1/provisioning/mute-timings/{name}route get mute timingGet a mute timing.
GET/api/v1/provisioning/mute-timingsroute get mute timingsGet all the mute timings.
POST/api/v1/provisioning/mute-timingsroute post mute timingCreate a new mute timing.
PUT/api/v1/provisioning/mute-timings/{name}route put mute timingReplace an existing mute timing.

Templates

MethodURINameSummary
DELETE/api/v1/provisioning/templates/{name}route delete templateDelete a template.
GET/api/v1/provisioning/templates/{name}route get templateGet a notification template.
GET/api/v1/provisioning/templatesroute get templatesGet all notification templates.
PUT/api/v1/provisioning/templates/{name}route put templateUpdates an existing notification template.

Paths

Delete a specific alert rule by UID. (RouteDeleteAlertRule)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstringAlert rule UID

All responses

CodeStatusDescriptionHas headersSchema
204No ContentThe 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstringUID is the contact point unique identifier

All responses

CodeStatusDescriptionHas headersSchema
204No ContentThe 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringMute timing name

All responses

CodeStatusDescriptionHas headersSchema
204No ContentThe 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringTemplate Name

All responses

CodeStatusDescriptionHas headersSchema
204No ContentThe 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstringAlert rule UID

All responses

CodeStatusDescriptionHas headersSchema
200OKProvisionedAlertRuleschema
404Not FoundNot 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstringAlert rule UID
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstring"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

CodeStatusDescriptionHas headersSchema
200OKAlertingFileExportschema
404Not FoundNot 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
FolderUIDpathstringstring
Grouppathstringstring

All responses

CodeStatusDescriptionHas headersSchema
200OKAlertRuleGroupschema
404Not FoundNot 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
FolderUIDpathstringstring
Grouppathstringstring
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstring"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

CodeStatusDescriptionHas headersSchema
200OKAlertingFileExportschema
404Not FoundNot 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

CodeStatusDescriptionHas headersSchema
200OKProvisionedAlertRulesschema

Responses

200 - ProvisionedAlertRules

Status: OK

Schema

ProvisionedAlertRules

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

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstring"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

CodeStatusDescriptionHas headersSchema
200OKAlertingFileExportschema
404Not FoundNot 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namequerystringstringFilter by name

All responses

CodeStatusDescriptionHas headersSchema
200OKContactPointsschema

Responses

200 - ContactPoints

Status: OK

Schema

ContactPoints

Get a mute timing. (RouteGetMuteTiming)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringMute timing name

All responses

CodeStatusDescriptionHas headersSchema
200OKMuteTimeIntervalschema
404Not FoundNot 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

CodeStatusDescriptionHas headersSchema
200OKMuteTimingsschema

Responses

200 - MuteTimings

Status: OK

Schema

MuteTimings

Get the notification policy tree. (RouteGetPolicyTree)

GET /api/v1/provisioning/policies

All responses

CodeStatusDescriptionHas headersSchema
200OKRouteschema

Responses

200 - Route

Status: OK

Schema

Route

Get a notification template. (RouteGetTemplate)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringTemplate Name

All responses

CodeStatusDescriptionHas headersSchema
200OKNotificationTemplateschema
404Not FoundNot 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

CodeStatusDescriptionHas headersSchema
200OKNotificationTemplatesschema
404Not FoundNot 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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
X-Disable-Provenanceheaderstringstring
BodybodyProvisionedAlertRulemodels.ProvisionedAlertRule

All responses

CodeStatusDescriptionHas headersSchema
201CreatedProvisionedAlertRuleschema
400Bad RequestValidationErrorschema

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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
BodybodyEmbeddedContactPointmodels.EmbeddedContactPoint

All responses

CodeStatusDescriptionHas headersSchema
202AcceptedEmbeddedContactPointschema
400Bad RequestValidationErrorschema

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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
BodybodyMuteTimeIntervalmodels.MuteTimeInterval

All responses

CodeStatusDescriptionHas headersSchema
201CreatedMuteTimeIntervalschema
400Bad RequestValidationErrorschema

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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstringAlert rule UID
X-Disable-Provenanceheaderstringstring
BodybodyProvisionedAlertRulemodels.ProvisionedAlertRule

All responses

CodeStatusDescriptionHas headersSchema
200OKProvisionedAlertRuleschema
400Bad RequestValidationErrorschema

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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
FolderUIDpathstringstring
Grouppathstringstring
BodybodyAlertRuleGroupmodels.AlertRuleGroup

All responses

CodeStatusDescriptionHas headersSchema
200OKAlertRuleGroupschema
400Bad RequestValidationErrorschema

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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstringUID is the contact point unique identifier
BodybodyEmbeddedContactPointmodels.EmbeddedContactPoint

All responses

CodeStatusDescriptionHas headersSchema
202AcceptedAckschema
400Bad RequestValidationErrorschema

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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringMute timing name
BodybodyMuteTimeIntervalmodels.MuteTimeInterval

All responses

CodeStatusDescriptionHas headersSchema
200OKMuteTimeIntervalschema
400Bad RequestValidationErrorschema

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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
BodybodyRoutemodels.RouteThe new notification routing tree to use

All responses

CodeStatusDescriptionHas headersSchema
202AcceptedAckschema
400Bad RequestValidationErrorschema

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

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringTemplate Name
BodybodyNotificationTemplateContentmodels.NotificationTemplateContent

All responses

CodeStatusDescriptionHas headersSchema
202AcceptedNotificationTemplateschema
400Bad RequestValidationErrorschema

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

CodeStatusDescriptionHas headersSchema
202AcceptedAckschema

Responses

202 - Ack

Status: Accepted

Schema

Ack

Models

Ack

interface{}

AlertQuery

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
datasourceUidstringstringGrafana data source unique identifier; it should be ‘expr’ for a Server Side Expression operation.
modelinterface{}interface{}JSON is the raw JSON query and includes the above properties as well as custom properties.
queryTypestringstringQueryType is an optional identifier for the type of query.
It can be used to distinguish different types of queries.
refIdstringstringRefID is the unique identifier of the query, set by the frontend call.
relativeTimeRangeRelativeTimeRangeRelativeTimeRange

AlertQueryExport

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
datasourceUidstringstring
modelinterface{}interface{}
queryTypestringstring
refIdstringstring
relativeTimeRangeRelativeTimeRangeRelativeTimeRange

AlertRuleExport

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
annotationsmap of stringmap[string]string
conditionstringstring
dasboardUidstringstring
data[]alertqueryexport[]*AlertQueryExport
execErrStatestringstring
forDurationDuration
labelsmap of stringmap[string]string
noDataStatestringstring
panelIdint64 (formatted integer)int64
titlestringstring
uidstringstring

AlertRuleGroup

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
folderUidstringstring
intervalint64 (formatted integer)int64
rules[]provisionedalertrule[]*ProvisionedAlertRule
titlestringstring

AlertRuleGroupExport

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
folderstringstring
intervalDurationDuration
namestringstring
orgIdint64 (formatted integer)int64
rules[]alertruleexport[]*AlertRuleExport

AlertingFileExport

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
apiVersionint64 (formatted integer)int64
groups[]alertrulegroupexport[]*AlertRuleGroupExport

ContactPoints

[]embeddedcontactpoint

Duration

NameTypeGo typeDefaultDescriptionExample
Durationint64 (formatted integer)int64

EmbeddedContactPoint

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

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
disableResolveMessagebooleanboolfalse
namestringstringName is used as grouping key in the UI. Contact points with the
same name will be grouped in the UI.webhook_1
provenancestringstring
settingsJSONJSON
typestringstringwebhook
uidstringstringUID is the unique identifier of the contact point. The UID can be
set by the user.my_external_reference

Json

interface{}

MatchRegexps

MatchRegexps

MatchType

NameTypeGo typeDefaultDescriptionExample
MatchTypeint64 (formatted integer)int64

Matcher

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Namestringstring
TypeMatchTypeMatchType
Valuestringstring

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

NameTypeGo typeRequiredDefaultDescriptionExample
namestringstring
time_intervals[]timeinterval[]*TimeInterval

MuteTimings

[]mutetimeinterval

NotificationTemplate

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
namestringstring
provenanceProvenanceProvenance
templatestringstring

NotificationTemplateContent

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
templatestringstring

NotificationTemplates

[]notificationtemplate

ObjectMatchers

Matchers

Inlined models

Provenance

NameTypeGo typeDefaultDescriptionExample
Provenancestringstring

ProvisionedAlertRule

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
annotationsmap of stringmap[string]string{"runbook_url":"https://supercoolrunbook.com/page/13"}
conditionstringstringA
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}}]
execErrStatestringstring
folderUIDstringstringproject_x
forDurationDuration
idint64 (formatted integer)int64
labelsmap of stringmap[string]string{"team":"sre-team-1"}
noDataStatestringstring
orgIDint64 (formatted integer)int64
provenanceProvenanceProvenance
ruleGroupstringstringeval_group_1
titlestringstringAlways firing
uidstringstring
updateddate-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

NameTypeGo typeRequiredDefaultDescriptionExample
fromDurationDuration
toDurationDuration

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

NameTypeGo typeRequiredDefaultDescriptionExample
continuebooleanbool
group_by[]string[]string
group_intervalstringstring
group_waitstringstring
matchmap of stringmap[string]stringDeprecated. Remove before v1.0 release.
match_reMatchRegexpsMatchRegexps
matchersMatchersMatchers
mute_time_intervals[]string[]string
object_matchersObjectMatchersObjectMatchers
provenanceProvenanceProvenance
receiverstringstring
repeat_intervalstringstring
routes[]route[]*Route

TimeInterval

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

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
days_of_month[]string[]string
locationstringstring
months[]string[]string
times[]timerange[]*TimeRange
weekdays[]string[]string
years[]string[]string

TimeRange

For example, 4:00PM to End of the day would Begin at 1020 and End at 1440.

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
EndMinuteint64 (formatted integer)int64
StartMinuteint64 (formatted integer)int64

ValidationError

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
msgstringstringerror message