Alerting Provisioning HTTP API

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.

Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Developersbreadcrumb arrow HTTP APIbreadcrumb arrow Alerting Provisioning HTTP API
Grafana Cloud Enterprise Open source

Alerting provisioning HTTP API

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

In the Alerting provisioning HTTP API, the endpoints use a JSON format that differs from the format returned by the export endpoints.

The export endpoints allow you to export alerting resources in a JSON format suitable for provisioning via files. However, this format cannot be used to update resources via the HTTP API.

Alert rules

MethodURINameSummary
DELETE/api/v1/provisioning/alert-rules/:uidroute delete alert ruleDelete a specific alert rule by UID.
GET/api/v1/provisioning/alert-rules/:uidroute 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/:uidroute put alert ruleUpdate an existing alert rule.
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/:grouproute get alert rule groupGet a rule group.
PUT/api/v1/provisioning/folder/:folderUid/rule-groups/:grouproute put alert rule groupUpdate the interval of a rule group or modify the rules of the 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.

Example request for new alert rule:

http 
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 
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

MethodURINameSummary
DELETE/api/v1/provisioning/contact-points/:uidroute 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/:uidroute put contactpointUpdate an existing contact point.
GET/api/v1/provisioning/contact-points/exportroute get contactpoints exportExport all contact points in provisioning file format.

Example Request for all the contact points:

http 
GET /api/v1/provisioning/contact-points
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

http 
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uid": "",
    "name": "email receiver",
    "type": "email",
    "settings": {
      "addresses": "<example@email.com>"
    },
    "disableResolveMessage": false
  }
]

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.
GET/api/v1/provisioning/policies/exportroute get policy tree exportExport the notification policy tree in provisioning file format.

Example Request for exporting the notification policy tree in YAML format:

http 
GET /api/v1/provisioning/policies/export?format=yaml
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

http 
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:
            - weekends

Notification template groups

Template groups enable you to define multiple notification templates ({{ define "" }}) within a single group. They can be managed from the Grafana Alerting UI.

MethodURINameSummary
DELETE/api/v1/provisioning/templates/:nameroute delete templateDelete a notification template group.
GET/api/v1/provisioning/templates/:nameroute get templateGet a notification template group.
GET/api/v1/provisioning/templatesroute get templateGet all notification template groups.
PUT/api/v1/provisioning/templates/:nameroute put templateCreate or update a notification template group.

Example Request for all notification template groups:

http 
GET /api/v1/provisioning/templates
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

http 
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"
  }
]

Mute timings

MethodURINameSummary
DELETE/api/v1/provisioning/mute-timings/:nameroute delete mute timingDelete a mute timing.
GET/api/v1/provisioning/mute-timings/:nameroute 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/:nameroute put mute timingReplace an existing mute timing.
GET/api/v1/provisioning/mute-timings/exportroute get mute timings exportExport all mute timings in provisioning file format.
GET/api/v1/provisioning/mute-timings/:name/exportroute get mute timing exportExport a mute timing in provisioning file format.

Example Request for all mute timings:

http 
GET /api/v1/provisioning/mute-timings
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

http 
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "name": "weekends",
    "time_intervals": [
      {
        "weekdays": [
          "saturday",
          "sunday"
        ]
      }
    ],
    "version": "",
    "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: true header to the following API requests:

To reset the notification policy tree to the default and unlock it for editing in the Grafana UI, use:

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/:uid

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
UIDpathstringstring✓Alert rule UID
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI

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

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
UIDpathstringstring✓UID 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 typeRequiredDefaultDescription
namepathstringstring✓Mute timing name
versionquerystringstringCurrent version of the resource. Used for optimistic concurrency validation. Keep empty to bypass validation.

All responses

CodeStatusDescriptionHas headersSchema
204No ContentThe mute timing was deleted successfully.schema
409ConflictGenericPublicErrorschema

Responses

204 - The mute timing was deleted successfully.

Status: No Content

Schema
409 - Conflict

Status: Conflict

Schema

GenericPublicError

Delete a notification template group. (RouteDeleteTemplate) 

DELETE /api/v1/provisioning/templates/:name

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
namepathstringstring✓Name of the template group
versionquerystringstringCurrent version of the resource. Used for optimistic concurrency validation. Keep empty to bypass validation.

All responses

CodeStatusDescriptionHas headersSchema
204No ContentThe template was deleted successfully.schema
409ConflictGenericPublicErrorschema

Responses

204 - The template was deleted successfully.

Status: No Content

Schema
409 - Conflict

Status: Conflict

Schema

GenericPublicError

Get a specific alert rule by UID. (RouteGetAlertRule) 

GET /api/v1/provisioning/alert-rules/:uid

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
UIDpathstringstring✓Alert 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
  • application/terraform+hcl
  • text/yaml
  • text/hcl

These outputs are for file provisioning or Terraform provisioning, and they-including the JSON output—cannot be used to update resources via the HTTP API.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
UIDpathstringstring✓Alert rule UID
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstringyamlFormat of the downloaded file, either yaml, json or hcl. 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 typeRequiredDefaultDescription
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
  • application/terraform+hcl
  • text/yaml
  • text/hcl

These outputs are for file provisioning or Terraform provisioning, and they-including the JSON output—cannot be used to update resources via the HTTP API.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
FolderUIDpathstringstring✓
Grouppathstringstring✓
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstringyamlFormat of the downloaded file, either yaml, json or hcl. 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

Produces

  • application/json
  • application/yaml
  • application/terraform+hcl
  • text/yaml
  • text/hcl

These outputs are for file provisioning or Terraform provisioning, and they-including the JSON output—cannot be used to update resources via the HTTP API.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstringyamlFormat of the downloaded file, either yaml, json or hcl. 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 typeRequiredDefaultDescription
namequerystringstringFilter by name

All responses

CodeStatusDescriptionHas headersSchema
200OKContactPointsschema

Responses

200 - ContactPoints

Status: OK

Schema

ContactPoints

Export all contact points in provisioning file format. (RouteGetContactpointsExport) 

GET /api/v1/provisioning/contact-points/export

Produces

  • application/json
  • application/yaml
  • application/terraform+hcl
  • text/yaml
  • text/hcl

These outputs are for file provisioning or Terraform provisioning, and they-including the JSON output—cannot be used to update resources via the HTTP API.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
decryptquerybooleanboolWhether 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.
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstringyamlFormat of the downloaded file, either yaml, json or hcl. Accept header can also be used, but the query parameter will take precedence.
namequerystringstringFilter by name

All responses

CodeStatusDescriptionHas headersSchema
200OKAlertingFileExportschema
403ForbiddenPermissionDeniedschema

Responses

200 - AlertingFileExport

Status: OK

Schema

AlertingFileExport

403 - PermissionDenied

Status: Forbidden

Schema

PermissionDenied

Get a mute timing. (RouteGetMuteTiming) 

GET /api/v1/provisioning/mute-timings/:name

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
namepathstringstring✓Mute 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

Export all mute timings in provisioning file format. (RouteGetMuteTimingsExport) 

GET /api/v1/provisioning/mute-timings/export

Produces

  • application/json
  • application/yaml
  • application/terraform+hcl
  • text/yaml
  • text/hcl

These outputs are for file provisioning or Terraform provisioning, and they-including the JSON output—cannot be used to update resources via the HTTP API.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstringyamlFormat of the downloaded file, either yaml, json or hcl. Accept header can also be used, but the query parameter will take precedence.

All responses

CodeStatusDescriptionHas headersSchema
200OKMuteTimingsExportschema
403ForbiddenPermissionDeniedschema

Responses

200 - MuteTimingsExport

Status: OK

Schema

AlertingFileExport

403 - PermissionDenied

Status: Forbidden

Schema

PermissionDenied

Export a mute timing in provisioning file format. (RouteGetMuteTimingExport) 

GET /api/v1/provisioning/mute-timings/:name/export

Produces

  • application/json
  • application/yaml
  • application/terraform+hcl
  • text/yaml
  • text/hcl

These outputs are for file provisioning or Terraform provisioning, and they-including the JSON output—cannot be used to update resources via the HTTP API.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
namepathstringstring✓Mute timing name.
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstringyamlFormat of the downloaded file, either yaml, json or hcl. Accept header can also be used, but the query parameter will take precedence.

All responses

CodeStatusDescriptionHas headersSchema
200OKMuteTimingExportschema
403ForbiddenPermissionDeniedschema

Responses

200 - MuteTimingExport

Status: OK

Schema

AlertingFileExport

403 - PermissionDenied

Status: Forbidden

Schema

PermissionDenied

Get the notification policy tree. (RouteGetPolicyTree) 

GET /api/v1/provisioning/policies

All responses

CodeStatusDescriptionHas headersSchema
200OKRouteschema

Responses

200 - Route

Status: OK

Schema

Route

Export the notification policy tree in provisioning file format. (RouteGetPolicyTreeExport) 

GET /api/v1/provisioning/policies/export

Produces

  • application/json
  • application/yaml
  • application/terraform+hcl
  • text/yaml
  • text/hcl

These outputs are for file provisioning or Terraform provisioning, and they-including the JSON output—cannot be used to update resources via the HTTP API.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
downloadquerybooleanboolWhether to initiate a download of the file or not.
formatquerystringstringyamlFormat of the downloaded file, either yaml, json or hcl. Accept header can also be used, but the query parameter will take precedence.

All responses

CodeStatusDescriptionHas headersSchema
200OKAlertingFileExportschema
404Not FoundNotFoundschema

Responses

200 - AlertingFileExport

Status: OK

Schema

AlertingFileExport

404 - NotFound

Status: Not Found

Schema

NotFound

Get a notification template group. (RouteGetTemplate) 

GET /api/v1/provisioning/templates/:name

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
namepathstringstring✓Name of the template group

All responses

CodeStatusDescriptionHas headersSchema
200OKNotificationTemplateschema
404Not FoundGenericPublicErrorschema

Responses

200 - NotificationTemplate

Status: OK

Schema

NotificationTemplate

404 - Not found.

GenericPublicError

Schema

Get all notification template groups. (RouteGetTemplates) 

GET /api/v1/provisioning/templates

All responses

CodeStatusDescriptionHas headersSchema
200OKNotificationTemplatesschema

Responses

200 - NotificationTemplates

Status: OK

Schema

NotificationTemplates

Create a new alert rule. (RoutePostAlertRule) 

POST /api/v1/provisioning/alert-rules

This action creates a new alert rule.

The provenance (X-Disable-Provenance) of the new rule must match the provenance configured for its rule group. Mixing provisioned and unprovisioned alert rules within the same rule group is not allowed.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI
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

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.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI
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

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI
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

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
UIDpathstringstring✓Alert rule UID
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI
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 or alert rules of a rule group. (RoutePutAlertRuleGroup) 

PUT /api/v1/provisioning/folder/:folderUid/rule-groups/:group

This action also changes the provenance setting (X-Disable-Provenance) for all alert rules in the alert group.

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
FolderUIDpathstringstring✓
Grouppathstringstring✓
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI. This also applies to all alert rules within the alert group.
BodybodyAlertRuleGroupmodels.AlertRuleGroupThis action is idempotent and rules included in this body will overwrite configured rules for the group

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

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
UIDpathstringstring✓UID is the contact point unique identifier
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI
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

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
namepathstringstring✓Mute timing name
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI
BodybodyMuteTimeIntervalmodels.MuteTimeInterval

All responses

CodeStatusDescriptionHas headersSchema
200OKMuteTimeIntervalschema
400Bad RequestValidationErrorschema
409ConflictGenericPublicErrorschema

Responses

200 - MuteTimeInterval

Status: OK

Schema

MuteTimeInterval

400 - ValidationError

Status: Bad Request

Schema

ValidationError

409 - Conflict

Status: Conflict

Schema

GenericPublicError

Sets the notification policy tree. (RoutePutPolicyTree)

Warning

Since the policy tree is a single resource, provisioning it will overwrite all policies in the notification policy tree. However, it does not affect internal policies created when alert rules directly select a contact point.

PUT /api/v1/provisioning/policies

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI
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

Create or update a notification template group. (RoutePutTemplate) 

PUT /api/v1/provisioning/templates/:name

Parameters

NameSourceTypeGo typeRequiredDefaultDescription
namepathstringstring✓Name of the template group
X-Disable-Provenance: trueheaderstringstringAllows editing of provisioned resources in the Grafana UI
BodybodyNotificationTemplateContentmodels.NotificationTemplateContent

All responses

CodeStatusDescriptionHas headersSchema
202AcceptedNotificationTemplateschema
400Bad RequestGenericPublicErrorschema
409ConflictGenericPublicErrorschema

Responses

202 - NotificationTemplate

Status: Accepted

Schema

NotificationTemplate

400 - ValidationError

Status: Bad Request

Schema

GenericPublicError

409 - Conflict

Status: Conflict

Schema

GenericPublicError

Clears the notification policy tree. (RouteResetPolicyTree) 

DELETE /api/v1/provisioning/policies

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
dashboardUidstringstring
data[] AlertQueryExport[]*AlertQueryExport
execErrStatestringstring
forDurationDuration
isPausedbooleanbool
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
contactPoints[] ContactPointExport[]*ContactPointExport
groups[] AlertRuleGroupExport[]*AlertRuleGroupExport
policies[] NotificationPolicyExport[]*NotificationPolicyExport

ContactPointExport

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
namestringstring
orgIdint64 (formatted integer)int64
receivers[] ReceiverExport[]*ReceiverExport

ContactPoints

[] EmbeddedContactPoint

Duration

NameTypeGo typeDefaultDescriptionExample
Durationstringint64

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

NameTypeGo typeRequiredDefaultDescriptionExample
disableResolveMessagebooleanboolfalse
namestringstringname groups multiple contact points with the same name in the UI.webhook_1
provenancestringstring
settingsJSONJSON✓
typestringstring✓webhook
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
versionstringstringVersion of resource

MuteTimingExport

Properties

MuteTimingsExport

Properties

MuteTimings

[] MuteTimeInterval

NotFound

interface{}

NotificationPolicyExport

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
PolicyRouteExportRouteExportinline
orgIdint64 (formatted integer)int64

NotificationTemplate

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
namestringstring
provenanceProvenanceProvenance
templatestringstring
versionstringstringVersion of resource

NotificationTemplateContent

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
templatestringstring
versionstringstringVersion of resource. Should be empty for new templates.

NotificationTemplates

[] NotificationTemplate

ObjectMatchers

Matchers

Inlined models

PermissionDenied

interface{}

Provenance

NameTypeGo typeDefaultDescriptionExample
Provenancestringstring

ProvisionedAlertRule

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
annotationsmap of stringmap[string]stringOptional key-value pairs. __dashboardUid__ and __panelId__ must be set together; one cannot be set without the other.{"runbook_url":"https://supercoolrunbook.com/page/13"}
conditionstringstring✓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}}]
execErrStatestringstring✓
folderUIDstringstring✓project_x
forDurationDuration✓
idint64 (formatted integer)int64
isPausedbooleanboolfalse
labelsmap of stringmap[string]string{"team":"sre-team-1"}
noDataStatestringstring✓
orgIDint64 (formatted integer)`int64✓
provenanceProvenanceProvenance
ruleGroupstringstring✓eval_group_1
titlestringstring✓Always firing
uidstringstring
updateddate-time (formatted string)strfmt.DateTime

ProvisionedAlertRules

[] ProvisionedAlertRule

RawMessage

interface{}

ReceiverExport

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
disableResolveMessagebooleanbool
settingsRawMessageRawMessage
typestringstring
uidstringstring

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

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

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
receiverstringstring
repeat_intervalstringstring
routes[] RouteExport[]*RouteExport

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
end_timestringstring"end_time": "24:00"
start_timestringstring"start_time": "18:00"

ValidationError

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
msgstringstringerror message

GenericPublicError

Properties

NameTypeGo typeRequiredDefaultDescriptionExample
statusCodestringstring✓HTTP Status Code
messageIdstringstring✓Unique code of the error
messagestringstringError message
extramap of anymap[string]anyExtra information about the error. Format is specific to the error code.