This is documentation for the next version of Grafana. For the latest stable release, go to the latest version.

DevelopersHTTP APIAlerting Provisioning HTTP API

Alerting provisioning API

Information

Version

1.0.0

Content negotiation

Consumes

  • application/json

Produces

  • application/json

All endpoints

Alert rules

MethodURINameSummary
GET/api/v1/provisioning/alert-rules/{UID}route get alert ruleGet a specific alert rule by UID.
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.
DELETE/api/v1/provisioning/alert-rules/{UID}route delete alert ruleDelete a specific alert rule by UID.

Contact points

MethodURINameSummary
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.
DELETE/api/v1/provisioning/contact-points/{UID}route delete contactpointsDelete a contact point.

Notification policies

MethodURINameSummary
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
GET/api/v1/provisioning/mute-timingsroute get mute timingsGet all the mute timings.
GET/api/v1/provisioning/mute-timings/{name}route get mute timingGet a mute timing.
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.
DELETE/api/v1/provisioning/mute-timings/{name}route delete mute timingDelete a mute timing.

Templates

MethodURINameSummary
GET/api/v1/provisioning/templatesroute get templatesGet all message templates.
GET/api/v1/provisioning/templates/{name}route get templateGet a message template.
PUT/api/v1/provisioning/templates/{name}route put templateCreates or updates a template.
DELETE/api/v1/provisioning/templates/{name}route delete templateDelete a template.

Paths

Delete a specific alert rule by UID. (RouteDeleteAlertRule)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstring

All responses

CodeStatusDescriptionHas headersSchema
204No ContentThe alert rule was deleted successfully.schema
400Bad RequestValidationErrorschema

Responses

204 - The alert rule was deleted successfully.

Status: No Content

Schema
400 - ValidationError

Status: Bad Request

Schema

ValidationError

Delete a contact point. (RouteDeleteContactpoints)

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

Consumes

  • application/json

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstringUID should be the contact point unique identifier

All responses

CodeStatusDescriptionHas headersSchema
202AcceptedAckschema
400Bad RequestValidationErrorschema

Responses

202 - Ack

Status: Accepted

Schema

Ack

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Delete a mute timing. (RouteDeleteMuteTiming)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringTemplate Name

All responses

CodeStatusDescriptionHas headersSchema
204No ContentAckschema

Responses

204 - Ack

Status: No Content

Schema

Ack

Delete a template. (RouteDeleteTemplate)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringTemplate Name

All responses

CodeStatusDescriptionHas headersSchema
204No ContentAckschema

Responses

204 - Ack

Status: No Content

Schema

Ack

Get a specific alert rule by UID. (RouteGetAlertRule)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
UIDpathstringstring

All responses

CodeStatusDescriptionHas headersSchema
200OKAlertRuleschema
400Bad RequestValidationErrorschema

Responses

200 - AlertRule

Status: OK

Schema

AlertRule

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Get all the contact points. (RouteGetContactpoints)

GET /api/v1/provisioning/contact-points

All responses

CodeStatusDescriptionHas headersSchema
200OKRouteschema
400Bad RequestValidationErrorschema

Responses

200 - Route

Status: OK

Schema

Route

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Get a mute timing. (RouteGetMuteTiming)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringTemplate Name

All responses

CodeStatusDescriptionHas headersSchema
200OKMuteTimeIntervalschema
400Bad RequestValidationErrorschema

Responses

200 - MuteTimeInterval

Status: OK

Schema

MuteTimeInterval

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Get all the mute timings. (RouteGetMuteTimings)

GET /api/v1/provisioning/mute-timings

All responses

CodeStatusDescriptionHas headersSchema
200OKMuteTimingsschema
400Bad RequestValidationErrorschema

Responses

200 - MuteTimings

Status: OK

Schema

MuteTimings

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Get the notification policy tree. (RouteGetPolicyTree)

GET /api/v1/provisioning/policies

All responses

CodeStatusDescriptionHas headersSchema
200OKRouteschema
400Bad RequestValidationErrorschema

Responses

200 - Route

Status: OK

Schema

Route

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Get a message template. (RouteGetTemplate)

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

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringTemplate Name

All responses

CodeStatusDescriptionHas headersSchema
200OKMessageTemplateschema
404Not FoundNotFoundschema

Responses

200 - MessageTemplate

Status: OK

Schema

MessageTemplate

404 - NotFound

Status: Not Found

Schema

NotFound

Get all message templates. (RouteGetTemplates)

GET /api/v1/provisioning/templates

All responses

CodeStatusDescriptionHas headersSchema
200OKMessageTemplateschema
400Bad RequestValidationErrorschema

Responses

200 - MessageTemplate

Status: OK

Schema

MessageTemplate

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Create a new alert rule. (RoutePostAlertRule)

POST /api/v1/provisioning/alert-rules

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
BodybodyAlertRulemodels.AlertRule

All responses

CodeStatusDescriptionHas headersSchema
201CreatedAlertRuleschema
400Bad RequestValidationErrorschema

Responses

201 - AlertRule

Status: Created

Schema

AlertRule

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
202AcceptedAckschema
400Bad RequestValidationErrorschema

Responses

202 - Ack

Status: Accepted

Schema

Ack

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
UIDpathstringstring
BodybodyAlertRulemodels.AlertRule

All responses

CodeStatusDescriptionHas headersSchema
200OKAlertRuleschema
400Bad RequestValidationErrorschema

Responses

200 - AlertRule

Status: OK

Schema

AlertRule

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 should be 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
namepathstringstringTemplate 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.Route

All responses

CodeStatusDescriptionHas headersSchema
202AcceptedAckschema
400Bad RequestValidationErrorschema

Responses

202 - Ack

Status: Accepted

Schema

Ack

400 - ValidationError

Status: Bad Request

Schema

ValidationError

Updates an existing template. (RoutePutTemplate)

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

Consumes

  • application/json

Parameters

NameSourceTypeGo typeSeparatorRequiredDefaultDescription
namepathstringstringTemplate Name
BodybodyMessageTemplateContentmodels.MessageTemplateContent

All responses

CodeStatusDescriptionHas headersSchema
202AcceptedAckschema
400Bad RequestValidationErrorschema

Responses

202 - Ack

Status: Accepted

Schema

Ack

400 - ValidationError

Status: Bad Request

Schema

ValidationError

AlertQuery

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
DatasourceUIDstringstringGrafana data source unique identifier; it should be ‘-100’ for a Server Side Expression operation.
Modelobjectinterface{}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

AlertRule

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Annotationsmap of stringmap[string]string{"runbook_url":"https://supercoolrunbook.com/page/13"}
ConditionstringstringA
Data[]alertquery[]*AlertQuery[{"datasourceUid":"-100","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}}]
ExecErrStatestringstringAllowed values: “OK”, “Alerting”, “Error”
FolderUIDstringstringproject_x
IDint64 (formatted integer)int64
Labelsmap of stringmap[string]string{"team":"sre-team-1"}
NoDataStatestringstringAllowed values: “OK”, “NoData”, “Error”
OrgIDint64 (formatted integer)int64
RuleGroupstringstringeval_group_1
TitlestringstringAlways firing
UIDstringstring
Updateddate-time (formatted string)strfmt.DateTime
forDurationDuration
provenancestringProvenance

AlertRuleGroup

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Intervalint64 (formatted integer)int64

DayOfMonthRange

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Beginint64 (formatted integer)int64
Endint64 (formatted integer)int64

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
Typestringstringwebhook
UIDstringstringUID is the unique identifier of the contact point. The UID can be set by the user.my_external_reference
settingsobjectJSON

MatchType

NameTypeGo typeDefaultDescriptionExample
MatchTypeint64 (formatted integer)int640 = MatchEqual, 1 = MatchNotEqual, 2 = MatchRegexp, 3 = MatchNotRegexp

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

MessageTemplate

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Namestringstring
Templatestringstring
provenancestringProvenance

MessageTemplateContent

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Templatestringstring

MonthRange

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Beginint64 (formatted integer)int64
Endint64 (formatted integer)int64

MuteTimeInterval

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Namestringstring
TimeIntervals[]timeinterval[]*TimeInterval

MuteTimings

[]mutetimeinterval

NotFound

interface{}

ObjectMatchers

Matchers

Inlined models

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.

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Continuebooleanbool
GroupByStr[]string[]string
MuteTimeIntervals[]string[]string
Receiverstringstring
Routes[]route[]*Route
group_intervalDurationDuration
group_waitDurationDuration
object_matchersObjectMatchersObjectMatchers
provenancestringProvenance
repeat_intervalDurationDuration

TimeInterval

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

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
DaysOfMonth[]dayofmonthrange[]*DayOfMonthRange
Months[]monthrange[]*MonthRange
Times[]timerange[]*TimeRange
Weekdays[]weekdayrange[]*WeekdayRange
Years[]yearrange[]*YearRange

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
Msgstringstring

WeekdayRange

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Beginint64 (formatted integer)int64
Endint64 (formatted integer)int64

YearRange

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
Beginint64 (formatted integer)int64
Endint64 (formatted integer)int64