Menu
Documentation
Grafana documentation
Alerting
Additional configuration
Provision Alerting resources
Use the HTTP API to manage alerting resources
Grafana documentation
Alerting
Additional configuration
Provision Alerting resources
Use the HTTP API to manage alerting resourcesUse the HTTP API to manage alerting resources
The Alerting Provisioning HTTP API can be used to create, modify, and delete resources relevant to Grafana-managed alerts. This API is the one used by our Grafana Terraform provider.
For more information on the differences between Grafana-managed and data source-managed alerts, refer to Introduction to alert rules.
If you are running Grafana Enterprise, you need to add specific permissions for some endpoints. For more information, refer to Role-based access control permissions.
Grafana-managed endpoints
Note that the JSON format from most of the following endpoints is not fully compatible with provisioning via configuration JSON files.
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. |
| 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. |
| 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. |
| PUT | /api/v1/provisioning/folder/:folderUid/rule-groups/:group | route put alert rule group | Update the interval of a rule group or modify the rules of the 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. |
Example request for new alert rule:
POST /api/v1/provisioning/alert-rules
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"title": "TEST-API_1",
"ruleGroup": "API",
"folderUID": "SET_FOLDER_UID",
"noDataState": "OK",
"execErrState": "OK",
"for": "5m",
"orgId": 1,
"uid": "",
"condition": "B",
"annotations": {
"summary": "test_api_1"
},
"labels": {
"API": "test1"
},
"data": [
{
"refId": "A",
"queryType": "",
"relativeTimeRange": {
"from": 600,
"to": 0
},
"datasourceUid": "XXXXXXXXX-XXXXXXXXX-XXXXXXXXXX",
"model": {
"expr": "up",
"hide": false,
"intervalMs": 1000,
"maxDataPoints": 43200,
"refId": "A"
}
},
{
"refId": "B",
"queryType": "",
"relativeTimeRange": {
"from": 0,
"to": 0
},
"datasourceUid": "-100",
"model": {
"conditions": [
{
"evaluator": {
"params": [6],
"type": "gt"
},
"operator": {
"type": "and"
},
"query": {
"params": ["A"]
},
"reducer": {
"params": [],
"type": "last"
},
"type": "query"
}
],
"datasource": {
"type": "__expr__",
"uid": "-100"
},
"hide": false,
"intervalMs": 1000,
"maxDataPoints": 43200,
"refId": "B",
"type": "classic_conditions"
}
}
]
}Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": 1,
"uid": "XXXXXXXXX",
"orgID": 1,
"folderUID": "SET_FOLDER_UID",
"ruleGroup": "API3",
"title": "TEST-API_1",
"condition": "B",
"data": [
{
"refId": "A",
"queryType": "",
"relativeTimeRange": {
"from": 600,
"to": 0
},
"datasourceUid": "XXXXXXXXX-XXXXXXXXX-XXXXXXXXXX",
"model": {
"expr": "up",
"hide": false,
"intervalMs": 1000,
"maxDataPoints": 43200,
"refId": "A"
}
},
{
"refId": "B",
"queryType": "",
"relativeTimeRange": {
"from": 0,
"to": 0
},
"datasourceUid": "-100",
"model": {
"conditions": [
{
"evaluator": {
"params": [
6
],
"type": "gt"
},
"operator": {
"type": "and"
},
"query": {
"params": [
"A"
]
},
"reducer": {
"params": [],
"type": "last"
},
"type": "query"
}
],
"datasource": {
"type": "__expr__",
"uid": "-100"
},
"hide": false,
"intervalMs": 1000,
"maxDataPoints": 43200,
"refId": "B",
"type": "classic_conditions"
}
}
],
"updated": "2024-08-02T13:19:32.609640048Z",
"noDataState": "OK",
"execErrState": "OK",
"for": "5m",
"annotations": {
"summary": "test_api_1"
},
"labels": {
"API": "test1"
},
"provenance": "api",
"isPaused": false,
"notification_settings": null,
"record": null
}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. |
| GET | /api/v1/provisioning/contact-points/export | route get contactpoints export | Export all contact points in provisioning file format. |
Example Request for all the contact points:
GET /api/v1/provisioning/contact-points
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbkExample Response:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"uid": "",
"name": "email receiver",
"type": "email",
"settings": {
"addresses": "<example@email.com>"
},
"disableResolveMessage": false
}
]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. |
| GET | /api/v1/provisioning/policies/export | route get policy tree export | Export the notification policy tree in provisioning file format. |
Example Request for exporting the notification policy tree in YAML format:
GET /api/v1/provisioning/policies/export?format=yaml
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbkExample Response:
HTTP/1.1 200 OK
Content-Type: text/yaml
apiVersion: 1
policies:
- orgId: 1
receiver: My Contact Email Point
group_by:
- grafana_folder
- alertname
routes:
- receiver: My Contact Email Point
object_matchers:
- - monitor
- =
- testdata
mute_time_intervals:
- weekendsMute 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. |
| GET | /api/v1/provisioning/mute-timings/export | route get mute timings export | Export all mute timings in provisioning file format. |
| GET | /api/v1/provisioning/mute-timings/:name/export | route get mute timing export | Export a mute timing in provisioning file format. |
Example Request for all mute timings:
GET /api/v1/provisioning/mute-timings
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbkExample Response:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"name": "weekends",
"time_intervals": [
{
"weekdays": [
"saturday",
"sunday"
]
}
],
"version": "",
"provenance": "file"
}
]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 | Create or update a notification template. |
Example Request for all notification templates:
GET /api/v1/provisioning/templates
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbkExample Response:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"name": "custom_email.message",
"template": "{{ define \"custom_email.message\" }}\n Custom alert!\n{{ end }}",
"provenance": "file"
},
{
"name": "custom_email.subject",
"template": "{{ define \"custom_email.subject\" }}\n{{ len .Alerts.Firing }} firing alert(s), {{ len .Alerts.Resolved }} resolved alert(s)\n{{ end }}",
"provenance": "file"
}
]Edit resources in the Grafana UI
By default, you cannot edit API-provisioned alerting resources in Grafana. To enable editing these resources in the Grafana UI, add the X-Disable-Provenance header to the following requests in the API:
POST /api/v1/provisioning/alert-rulesPUT /api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}(calling this endpoint will change provenance for all alert rules within the alert group)POST /api/v1/provisioning/contact-pointsPOST /api/v1/provisioning/mute-timingsPUT /api/v1/provisioning/policiesPUT /api/v1/provisioning/templates/{name}
To reset the notification policy tree to the default and unlock it for editing in the Grafana UI, use the DELETE /api/v1/provisioning/policies endpoint.
Data source-managed resources
The Alerting Provisioning HTTP API can only be used to manage Grafana-managed alert resources. To manage resources related to data source-managed alerts, consider the following tools:
- mimirtool: to interact with the Mimir alertmanager and ruler configuration.
- cortex-tools: to interact with the Cortex alertmanager and ruler configuration.
- lokitool: to configure the Loki Ruler.
Alternatively, the Grafana Alerting API can be used to access data from data source-managed alerts. This API is primarily intended for internal usage, with the exception of the /api/v1/provisioning/ endpoints. It’s important to note that internal APIs may undergo changes without prior notice and are not officially supported for user consumption.
For Prometheus, amtool can also be used to interact with the AlertManager API.
Paths
Delete a specific alert rule by UID. (RouteDeleteAlertRule)
DELETE /api/v1/provisioning/alert-rules/:uidParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| UID | path | string | string | ✓ | Alert rule UID | ||
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI |
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/:uidParameters
| 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/:nameParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| name | path | string | string | ✓ | Mute timing name | ||
| version | query | string | string | Current version of the resource. Used for optimistic concurrency validation. Keep empty to bypass validation. |
All responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 204 | No Content | The mute timing was deleted successfully. | schema | |
| 409 | Conflict | GenericPublicError | schema |
Responses
204 - The mute timing was deleted successfully.
Status: No Content
Schema
409 - Conflict
Status: Conflict
Schema
Delete a template. (RouteDeleteTemplate)
DELETE /api/v1/provisioning/templates/:nameParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| name | path | string | string | ✓ | Template Name | ||
| version | query | string | string | Current version of the resource. Used for optimistic concurrency validation. Keep empty to bypass validation. |
All responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 204 | No Content | The template was deleted successfully. | schema | |
| 409 | Conflict | GenericPublicError | schema |
Responses
204 - The template was deleted successfully.
Status: No Content
Schema
409 - Conflict
Status: Conflict
Schema
Get a specific alert rule by UID. (RouteGetAlertRule)
GET /api/v1/provisioning/alert-rules/:uidParameters
| 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
404 - Not found.
Status: Not Found
Schema
Export an alert rule in provisioning file format. (RouteGetAlertRuleExport)
GET /api/v1/provisioning/alert-rules/:uid/exportProduces
- application/json
- application/yaml
- application/terraform+hcl
- text/yaml
- text/hcl
Parameters
| Name | Source | Type | Go type | Separator | 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, json or hcl. 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
404 - Not found.
Status: Not Found
Schema
Get a rule group. (RouteGetAlertRuleGroup)
GET /api/v1/provisioning/folder/:folderUid/rule-groups/:groupParameters
| 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
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/exportProduces
- application/json
- application/yaml
- application/terraform+hcl
- text/yaml
- text/hcl
Parameters
| Name | Source | Type | Go type | Separator | 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, json or hcl. 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
404 - Not found.
Status: Not Found
Schema
Get all the alert rules. (RouteGetAlertRules)
GET /api/v1/provisioning/alert-rulesAll responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | ProvisionedAlertRules | schema |
Responses
200 - ProvisionedAlertRules
Status: OK
Schema
Export all alert rules in provisioning file format. (RouteGetAlertRulesExport)
GET /api/v1/provisioning/alert-rules/exportProduces
- application/json
- application/yaml
- application/terraform+hcl
- text/yaml
- text/hcl
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, json or hcl. 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
404 - Not found.
Status: Not Found
Schema
Get all the contact points. (RouteGetContactpoints)
GET /api/v1/provisioning/contact-pointsParameters
| 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
Export all contact points in provisioning file format. (RouteGetContactpointsExport)
GET /api/v1/provisioning/contact-points/exportProduces
- application/json
- application/yaml
- application/terraform+hcl
- text/yaml
- text/hcl
Parameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| decrypt | query | boolean | bool | Whether any contained secure settings should be decrypted or left redacted. Redacted settings will contain RedactedValue instead. Currently, only org admin can view decrypted secure settings. | |||
| 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, json or hcl. Accept header can also be used, but the query parameter will take precedence. | ||
| name | query | string | string | Filter by name |
All responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | AlertingFileExport | schema | |
| 403 | Forbidden | PermissionDenied | schema |
Responses
200 - AlertingFileExport
Status: OK
Schema
403 - PermissionDenied
Status: Forbidden
Schema
Get a mute timing. (RouteGetMuteTiming)
GET /api/v1/provisioning/mute-timings/:nameParameters
| 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
404 - Not found.
Status: Not Found
Schema
Get all the mute timings. (RouteGetMuteTimings)
GET /api/v1/provisioning/mute-timingsAll responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | MuteTimings | schema |
Responses
200 - MuteTimings
Status: OK
Schema
Export all mute timings in provisioning file format. (RouteGetMuteTimingsExport)
GET /api/v1/provisioning/mute-timings/exportProduces
- application/json
- application/yaml
- application/terraform+hcl
- text/yaml
- text/hcl
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, json or hcl. Accept header can also be used, but the query parameter will take precedence. |
All responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | MuteTimingsExport | schema | |
| 403 | Forbidden | PermissionDenied | schema |
Responses
200 - MuteTimingsExport
Status: OK
Schema
403 - PermissionDenied
Status: Forbidden
Schema
Export a mute timing in provisioning file format. (RouteGetMuteTimingExport)
GET /api/v1/provisioning/mute-timings/:name/exportProduces
- application/json
- application/yaml
- application/terraform+hcl
- text/yaml
- text/hcl
Parameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| name | path | string | string | ✓ | Mute timing name. | ||
| 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, json or hcl. Accept header can also be used, but the query parameter will take precedence. |
All responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | MuteTimingExport | schema | |
| 403 | Forbidden | PermissionDenied | schema |
Responses
200 - MuteTimingExport
Status: OK
Schema
403 - PermissionDenied
Status: Forbidden
Schema
Get the notification policy tree. (RouteGetPolicyTree)
GET /api/v1/provisioning/policiesAll responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | Route | schema |
Responses
200 - Route
Status: OK
Schema
Export the notification policy tree in provisioning file format. (RouteGetPolicyTreeExport)
GET /api/v1/provisioning/policies/exportProduces
- application/json
- application/yaml
- application/terraform+hcl
- text/yaml
- text/hcl
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, json or hcl. 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 | NotFound | schema |
Responses
200 - AlertingFileExport
Status: OK
Schema
404 - NotFound
Status: Not Found
Schema
Get a notification template. (RouteGetTemplate)
GET /api/v1/provisioning/templates/:nameParameters
| 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 | GenericPublicError | schema |
Responses
200 - NotificationTemplate
Status: OK
Schema
404 - Not found.
Schema
Get all notification templates. (RouteGetTemplates)
GET /api/v1/provisioning/templatesAll responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | NotificationTemplates | schema |
Responses
200 - NotificationTemplates
Status: OK
Schema
Create a new alert rule. (RoutePostAlertRule)
POST /api/v1/provisioning/alert-rulesParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| 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
400 - ValidationError
Status: Bad Request
Schema
Create a contact point. (RoutePostContactpoints)
POST /api/v1/provisioning/contact-pointsWhen creating a contact point, the EmbeddedContactPoint.name property determines if the new contact point is added to an existing one. In the UI, contact points with the same name are grouped together under a single contact point.
Parameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| 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
400 - ValidationError
Status: Bad Request
Schema
Create a new mute timing. (RoutePostMuteTiming)
POST /api/v1/provisioning/mute-timingsParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| 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
400 - ValidationError
Status: Bad Request
Schema
Update an existing alert rule. (RoutePutAlertRule)
PUT /api/v1/provisioning/alert-rules/:uidParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| UID | path | string | string | ✓ | Alert rule UID | ||
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| 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
400 - ValidationError
Status: Bad Request
Schema
Update the interval or alert rules of a rule group. (RoutePutAlertRuleGroup)
PUT /api/v1/provisioning/folder/:folderUid/rule-groups/:groupParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| FolderUID | path | string | string | ✓ | |||
| Group | path | string | string | ✓ | |||
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| Body | body | AlertRuleGroup | models.AlertRuleGroup | This action is idempotent and rules included in this body will overwrite configured rules for the group |
All responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | AlertRuleGroup | schema | |
| 400 | Bad Request | ValidationError | schema |
Responses
200 - AlertRuleGroup
Status: OK
Schema
400 - ValidationError
Status: Bad Request
Schema
Update an existing contact point. (RoutePutContactpoint)
PUT /api/v1/provisioning/contact-points/:uidParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| UID | path | string | string | ✓ | UID is the contact point unique identifier | ||
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| 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
400 - ValidationError
Status: Bad Request
Schema
Replace an existing mute timing. (RoutePutMuteTiming)
PUT /api/v1/provisioning/mute-timings/:nameParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| name | path | string | string | ✓ | Mute timing name | ||
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| Body | body | MuteTimeInterval | models.MuteTimeInterval |
All responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 200 | OK | MuteTimeInterval | schema | |
| 400 | Bad Request | ValidationError | schema | |
| 409 | Conflict | GenericPublicError | schema |
Responses
200 - MuteTimeInterval
Status: OK
Schema
400 - ValidationError
Status: Bad Request
Schema
409 - Conflict
Status: Conflict
Schema
Sets the notification policy tree. (RoutePutPolicyTree)
PUT /api/v1/provisioning/policiesParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| 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
400 - ValidationError
Status: Bad Request
Schema
Create or update a notification template. (RoutePutTemplate)
PUT /api/v1/provisioning/templates/:nameParameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|---|---|---|---|---|---|---|---|
| name | path | string | string | ✓ | Template Name | ||
| X-Disable-Provenance: true | header | string | string | Allows editing of provisioned resources in the Grafana UI | |||
| Body | body | NotificationTemplateContent | models.NotificationTemplateContent |
All responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 202 | Accepted | NotificationTemplate | schema | |
| 400 | Bad Request | GenericPublicError | schema | |
| 409 | Conflict | GenericPublicError | schema |
Responses
202 - NotificationTemplate
Status: Accepted
Schema
400 - ValidationError
Status: Bad Request
Schema
409 - Conflict
Status: Conflict
Schema
Clears the notification policy tree. (RouteResetPolicyTree)
DELETE /api/v1/provisioning/policiesAll responses
| Code | Status | Description | Has headers | Schema |
|---|---|---|---|---|
| 202 | Accepted | Ack | schema |
Responses
202 - Ack
Status: Accepted
Schema
Models
Ack
AlertQuery
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| 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 | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| datasourceUid | string | string | ||||
| model | interface{} | interface{} | ||||
| queryType | string | string | ||||
| refId | string | string | ||||
| relativeTimeRange | RelativeTimeRange | RelativeTimeRange |
AlertRuleExport
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| annotations | map of string | map[string]string | ||||
| condition | string | string | ||||
| dashboardUid | string | string | ||||
| data | []AlertQueryExport | []*AlertQueryExport | ||||
| execErrState | string | string | ||||
| for | Duration | Duration | ||||
| isPaused | boolean | bool | ||||
| 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 | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| folderUid | string | string | ||||
| interval | int64 (formatted integer) | int64 | ||||
| rules | []ProvisionedAlertRule | []*ProvisionedAlertRule | ||||
| title | string | string |
AlertRuleGroupExport
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| 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 | ||||
| contactPoints | []ContactPointExport | []*ContactPointExport | ||||
| groups | []AlertRuleGroupExport | []*AlertRuleGroupExport | ||||
| policies | []NotificationPolicyExport | []*NotificationPolicyExport |
ContactPointExport
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| name | string | string | ||||
| orgId | int64 (formatted integer) | int64 | ||||
| receivers | []ReceiverExport | []*ReceiverExport |
ContactPoints
Duration
| Name | Type | Go type | Default | Description | Example |
|---|---|---|---|---|---|
| Duration | string | int64 |
EmbeddedContactPoint
EmbeddedContactPoint is the contact point type used by Grafana-managed alerts.
When creating a contact point, the EmbeddedContactPoint.name property determines if the new contact point is added to an existing one. In the UI, contact points with the same name are grouped together under a single contact point.
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| disableResolveMessage | boolean | bool | false | |||
| name | string | string | name groups multiple contact points with the same name 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
MatchRegexps
MatchType
| Name | Type | Go type | Default | Description | Example |
|---|---|---|---|---|---|
| MatchType | int64 (formatted integer) | int64 |
Matcher
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| 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 | ||||
| version | string | string | Version of resource |
MuteTimingExport
Properties
MuteTimingsExport
Properties
MuteTimings
NotFound
NotificationPolicyExport
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| Policy | RouteExport | RouteExport | inline | |||
| orgId | int64 (formatted integer) | int64 |
NotificationTemplate
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| name | string | string | ||||
| provenance | Provenance | Provenance | ||||
| template | string | string | ||||
| version | string | string | Version of resource |
NotificationTemplateContent
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| template | string | string | ||||
| version | string | string | Version of resource. Should be empty for new templates. |
NotificationTemplates
ObjectMatchers
Inlined models
PermissionDenied
Provenance
| Name | Type | Go type | Default | Description | Example |
|---|---|---|---|---|---|
| Provenance | string | string |
ProvisionedAlertRule
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| annotations | map of string | map[string]string | Optional key-value pairs. dashboardUId and panelId must be set together; one cannot be set without the other. | {"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 | ||||
| isPaused | boolean | bool | false | |||
| 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
RawMessage
ReceiverExport
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| disableResolveMessage | boolean | bool | ||||
| settings | RawMessage | RawMessage | ||||
| type | string | string | ||||
| uid | string | string |
Regexp
A Regexp is safe for concurrent use by multiple goroutines, except for configuration methods, such as Longest.
RelativeTimeRange
RelativeTimeRange is the per query start and end time for requests.
Properties
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 | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| 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 |
RouteExport
RouteExport is the provisioned file export of definitions.Route. This is needed to hide fields that aren’t usable in provisioning file format. An alternative would be to define a custom MarshalJSON and MarshalYAML that excludes them.
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| 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 | ||||
| receiver | string | string | ||||
| repeat_interval | string | string | ||||
| routes | []RouteExport | []*RouteExport |
TimeInterval
TimeInterval describes intervals of time. ContainsTime will tell you if a golang time is contained within the interval.
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| days_of_month | []string | []string | ||||
| location | string | string | ||||
| 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
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| end_time | string | string | "end_time": "24:00" | |||
| start_time | string | string | "start_time": "18:00" |
ValidationError
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| msg | string | string | error message |
GenericPublicError
Properties
| Name | Type | Go type | Required | Default | Description | Example |
|---|---|---|---|---|---|---|
| statusCode | string | string | ✓ | HTTP Status Code | ||
| messageId | string | string | ✓ | Unique code of the error | ||
| message | string | string | Error message | |||
| extra | map of any | map[string]any | Extra information about the error. Format is specific to the error code. |
Was this page helpful?
Related resources from Grafana Labs
60 min
Getting started with managing your metrics, logs, and traces using Grafana
In this webinar, we’ll demo how to get started using the LGTM Stack: Loki for logs, Grafana for visualization, Tempo for traces, and Mimir for metrics.
15 Jan
Getting started with Grafana dashboard design
In this webinar, you'll learn how to design stylish and easily accessible Grafana dashboards that tell a story.
60 min
Building advanced Grafana dashboards
In this webinar, we’ll demo how to build and format Grafana dashboards.