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

{{< admonition type="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.

{{< /admonition >}}

Alert rules

The following endpoints can be used to manage both alert rules and recording rules. To create a recording rule, include a record block in your request instead of a condition field.

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",
  "keepFiringFor": "2m",
  "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",
  "keepFiringFor": "2m",
  "annotations": {
    "summary": "test_api_1"
  },
  "labels": {
    "API": "test1"
  },
  "provenance": "api",
  "isPaused": false,
  "notification_settings": null,
  "record": null
}

Recording rules

Recording rules allow you to pre-compute frequently used or computationally expensive queries and save the results as a new time series metric. The same alert rule provisioning endpoints support creating recording rules by including the record field instead of alert-specific fields like condition, noDataState, or execErrState.

Example request for new recording rule:

POST /api/v1/provisioning/alert-rules
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "title": "my_recording_rule",
  "ruleGroup": "recording_rules_group",
  "folderUID": "SET_FOLDER_UID",
  "for": "0s",
  "orgId": 1,
  "uid": "",
  "labels": {
    "team": "backend"
  },
  "data": [
    {
      "refId": "A",
      "queryType": "",
      "relativeTimeRange": {
        "from": 600,
        "to": 0
      },
      "datasourceUid": "PROMETHEUS_DATASOURCE_UID",
      "model": {
        "expr": "sum(rate(http_requests_total[5m]))",
        "intervalMs": 1000,
        "maxDataPoints": 43200,
        "refId": "A"
      }
    }
  ],
  "record": {
    "metric": "http_requests:rate5m:sum",
    "from": "A",
    "target_datasource_uid": "TARGET_PROMETHEUS_UID"
  }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 2,
  "uid": "YYYYYYYYY",
  "orgID": 1,
  "folderUID": "SET_FOLDER_UID",
  "ruleGroup": "recording_rules_group",
  "title": "my_recording_rule",
  "for": "0s",
  "data": [
    {
      "refId": "A",
      "queryType": "",
      "relativeTimeRange": {
        "from": 600,
        "to": 0
      },
      "datasourceUid": "PROMETHEUS_DATASOURCE_UID",
      "model": {
        "expr": "sum(rate(http_requests_total[5m]))",
        "intervalMs": 1000,
        "maxDataPoints": 43200,
        "refId": "A"
      }
    }
  ],
  "updated": "2024-08-02T14:30:15.123456789Z",
  "labels": {
    "team": "backend"
  },
  "provenance": "api",
  "isPaused": false,
  "record": {
    "metric": "http_requests:rate5m:sum",
    "from": "A",
    "target_datasource_uid": "TARGET_PROMETHEUS_UID"
  }
}

Important notes for recording rules:

• The metric field must be a valid Prometheus metric name and contain no whitespace.
• The from field specifies which query reference (refId) to use as the source for the recorded metric.
• The target_datasource_uid specifies which Prometheus-compatible data source to write the results to. If not specified, the default data source configured in [recording_rules].default_datasource_uid is used.
• Recording rules do not support condition, noDataState, execErrState, or notification_settings fields.
• Set for to 0s for recording rules as they do not have a pending state.

Contact points

Example Request for all the contact points:

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

Example Response:

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

[
  {
    "uid": "",
    "name": "email receiver",
    "type": "email",
    "settings": {
      "addresses": "<[email protected]>"
    },
    "disableResolveMessage": false
  }
]

Receiver permissions

The receiver permissions endpoints manage access control for contact point receivers. These endpoints allow you to assign permissions to users, teams, or built-in roles for specific receivers.

Example Request to assign permissions to a user:

POST /api/access-control/receivers/abc123/users/5
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "permission": "Edit"
}

Example Response:

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

{
  "message": "Permission updated"
}

Example Request to remove permissions from a team:

POST /api/access-control/receivers/abc123/teams/3
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "permission": ""
}

Example Response:

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

{
  "message": "Permission removed"
}

Example Request to assign permissions to a built-in role:

POST /api/access-control/receivers/abc123/builtInRoles/Viewer
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "permission": "View"
}

Example Response:

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

{
  "message": "Permission updated"
}

Available Permissions sets:

• View - Read-only access to the receiver.
  • Grants alert.notifications.receivers:read.
• Edit - Ability to update and test the receiver.
  • Grants View actions plus:
    • alert.notifications.receivers:write
    • alert.notifications.receivers:delete
    • alert.notifications.receivers.test:create
• Admin - Full access including managing permissions and reading secrets.
  • Grants Edit actions plus:
    • alert.notifications.receivers.secrets:read
    • receivers.permissions:read
    • receivers.permissions:write
    • alert.notifications.receivers.protected:write
• Empty string ("") - Removes the permission.

Notification policies

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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example 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:
            - 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.

Example Request for all notification template groups:

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

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

Mute timings

Example Request for all mute timings:

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

Example Response:

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:

• PUT /api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}: This action also sets the provenance for the rule group and all its alert rules.
• POST /api/v1/provisioning/alert-rules: The provenance of the new alert rule must match the provenance value configured for its rule group.
• POST /api/v1/provisioning/contact-points
• POST /api/v1/provisioning/mute-timings
• PUT /api/v1/provisioning/templates/{name}
• PUT /api/v1/provisioning/policies

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

• DELETE /api/v1/provisioning/policies

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

<span id="route-delete-alert-rule"></span> Delete a specific alert rule by UID. (RouteDeleteAlertRule)

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

{{< admonition type="warning" >}} This API is deprecated and will be removed in a future release. Use the Grafana App Platform alerting APIs instead: /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/alertrules/{name} for alert rules and /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/recordingrules/{name} for recording rules. {{< /admonition >}}

Parameters

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-delete-alert-rule-204"></span> 204 - The alert rule was deleted successfully.

Status: No Content

<span id="route-delete-alert-rule-204-schema"></span> Schema

<span id="route-delete-alert-rule-group"></span> Delete a rule group. (RouteDeleteAlertRuleGroup)

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

{{< admonition type="warning" >}} This API is deprecated and will be removed in a future release. Use the Grafana App Platform alerting APIs instead: /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/alertrules for alert rules and /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/recordingrules for recording rules. {{< /admonition >}}

Parameters

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-delete-alert-rule-group-204"></span> 204 - The alert rule group was deleted successfully.

Status: No Content

<span id="route-delete-alert-rule-group-204-schema"></span> Schema

<span id="route-delete-alert-rule-group-403"></span> 403 - ForbiddenError

Status: Forbidden

<span id="route-delete-alert-rule-group-403-schema"></span> Schema

ForbiddenError

<span id="route-delete-alert-rule-group-404"></span> 404 - NotFound

Status: Not Found

<span id="route-delete-alert-rule-group-404-schema"></span> Schema

NotFound

<span id="route-delete-contactpoints"></span> Delete a contact point. (RouteDeleteContactpoints)

DELETE /api/v1/provisioning/contact-points/:uid

Parameters

All responses

Responses

<span id="route-delete-contactpoints-204"></span> 204 - The contact point was deleted successfully.

Status: No Content

<span id="route-delete-contactpoints-204-schema"></span> Schema

<span id="route-delete-mute-timing"></span> Delete a mute timing. (RouteDeleteMuteTiming)

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

Parameters

All responses

Responses

<span id="route-delete-mute-timing-204"></span> 204 - The mute timing was deleted successfully.

Status: No Content

<span id="route-delete-mute-timing-204-schema"></span> Schema

<span id="route-delete-mute-timing-409"></span> 409 - Conflict

Status: Conflict

<span id="route-delete-mute-timing-409-schema"></span> Schema

GenericPublicError

<span id="route-delete-template"></span> Delete a notification template group. (RouteDeleteTemplate)

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

Parameters

All responses

Responses

<span id="route-delete-template-204"></span> 204 - The template was deleted successfully.

Status: No Content

<span id="route-delete-template-204-schema"></span> Schema

<span id="route-delete-template-409"></span> 409 - Conflict

Status: Conflict

<span id="route-delete-template-409-schema"></span> Schema

GenericPublicError

<span id="route-get-alert-rule"></span> Get a specific alert rule by UID. (RouteGetAlertRule)

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

{{< admonition type="warning" >}} This API is deprecated and will be removed in a future release. Use the Grafana App Platform alerting APIs instead: /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/alertrules/{name} for alert rules and /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/recordingrules/{name} for recording rules. {{< /admonition >}}

Parameters

All responses

Responses

<span id="route-get-alert-rule-200"></span> 200 - ProvisionedAlertRule

Status: OK

<span id="route-get-alert-rule-200-schema"></span> Schema

ProvisionedAlertRule

<span id="route-get-alert-rule-404"></span> 404 - Not found.

Status: Not Found

<span id="route-get-alert-rule-404-schema"></span> Schema

<span id="route-get-alert-rule-export"></span> Export an alert rule in provisioning file format. (RouteGetAlertRuleExport)

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

{{< docs/shared lookup="alerts/alerting-provisioning-export-produces.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Parameters

All responses

Responses

<span id="route-get-alert-rule-export-200"></span> 200 - AlertingFileExport

Status: OK

<span id="route-get-alert-rule-export-200-schema"></span> Schema

AlertingFileExport

<span id="route-get-alert-rule-export-404"></span> 404 - Not found.

Status: Not Found

<span id="route-get-alert-rule-export-404-schema"></span> Schema

<span id="route-get-alert-rule-group"></span> Get a rule group. (RouteGetAlertRuleGroup)

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

{{< admonition type="warning" >}} This API is deprecated and will be removed in a future release. Use the Grafana App Platform alerting APIs instead: /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/alertrules for alert rules and /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/recordingrules for recording rules. {{< /admonition >}}

Parameters

All responses

Responses

<span id="route-get-alert-rule-group-200"></span> 200 - AlertRuleGroup

Status: OK

<span id="route-get-alert-rule-group-200-schema"></span> Schema

AlertRuleGroup

<span id="route-get-alert-rule-group-404"></span> 404 - Not found.

Status: Not Found

<span id="route-get-alert-rule-group-404-schema"></span> Schema

<span id="route-get-alert-rule-group-export"></span> Export an alert rule group in provisioning file format. (RouteGetAlertRuleGroupExport)

GET /api/v1/provisioning/folder/:folderUid/rule-groups/:group/export

{{< docs/shared lookup="alerts/alerting-provisioning-export-produces.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Parameters

All responses

Responses

<span id="route-get-alert-rule-group-export-200"></span> 200 - AlertingFileExport

Status: OK

<span id="route-get-alert-rule-group-export-200-schema"></span> Schema

AlertingFileExport

<span id="route-get-alert-rule-group-export-404"></span> 404 - Not found.

Status: Not Found

<span id="route-get-alert-rule-group-export-404-schema"></span> Schema

<span id="route-get-alert-rules"></span> Get all the alert rules. (RouteGetAlertRules)

GET /api/v1/provisioning/alert-rules

{{< admonition type="warning" >}} This API is deprecated and will be removed in a future release. Use the Grafana App Platform alerting APIs instead: /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/alertrules for alert rules and /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/recordingrules for recording rules. {{< /admonition >}}

All responses

Responses

<span id="route-get-alert-rules-200"></span> 200 - ProvisionedAlertRules

Status: OK

<span id="route-get-alert-rules-200-schema"></span> Schema

ProvisionedAlertRules

<span id="route-get-alert-rules-export"></span> Export all alert rules in provisioning file format. (RouteGetAlertRulesExport)

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

{{< docs/shared lookup="alerts/alerting-provisioning-export-produces.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Parameters

All responses

Responses

<span id="route-get-alert-rules-export-200"></span> 200 - AlertingFileExport

Status: OK

<span id="route-get-alert-rules-export-200-schema"></span> Schema

AlertingFileExport

<span id="route-get-alert-rules-export-404"></span> 404 - Not found.

Status: Not Found

<span id="route-get-alert-rules-export-404-schema"></span> Schema

<span id="route-get-contactpoints"></span> Get all the contact points. (RouteGetContactpoints)

GET /api/v1/provisioning/contact-points

Parameters

All responses

Responses

<span id="route-get-contactpoints-200"></span> 200 - ContactPoints

Status: OK

<span id="route-get-contactpoints-200-schema"></span> Schema

ContactPoints

<span id="route-get-contactpoints-export"></span> Export all contact points in provisioning file format. (RouteGetContactpointsExport)

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

{{< docs/shared lookup="alerts/alerting-provisioning-export-produces.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Parameters

All responses

Responses

<span id="route-get-contactpoints-export-200"></span> 200 - AlertingFileExport

Status: OK

<span id="route-get-contactpoints-export-200-schema"></span> Schema

AlertingFileExport

<span id="route-get-contactpoints-export-403"></span> 403 - PermissionDenied

Status: Forbidden

<span id="route-get-contactpoints-export-403-schema"></span> Schema

PermissionDenied

<span id="route-set-user-receiver-permission"></span> Set permissions for a user on a specific receiver. (RouteSetUserReceiverPermission)

POST /api/access-control/receivers/:uid/users/:userID

This endpoint sets or removes permissions for a specific user on a receiver. To remove a permission, send an empty string as the permission value.

{{< admonition type="note" >}} This endpoint requires Grafana Enterprise and the user must have the receivers.permissions:write permission for the specified receiver. {{< /admonition >}}

Parameters

All responses

Responses

<span id="route-set-user-receiver-permission-200"></span> 200 - Permission updated

Status: OK

<span id="route-set-user-receiver-permission-200-schema"></span> Schema

{
  "message": "Permission updated"
}

<span id="route-set-user-receiver-permission-400"></span> 400 - Invalid request

Status: Bad Request

<span id="route-set-user-receiver-permission-400-schema"></span> Schema

<span id="route-set-user-receiver-permission-403"></span> 403 - Permission denied

Status: Forbidden

<span id="route-set-user-receiver-permission-403-schema"></span> Schema

PermissionDenied

<span id="route-set-team-receiver-permission"></span> Set permissions for a team on a specific receiver. (RouteSetTeamReceiverPermission)

POST /api/access-control/receivers/:uid/teams/:teamID

This endpoint sets or removes permissions for a specific team on a receiver. To remove a permission, send an empty string as the permission value.

{{< admonition type="note" >}} This endpoint requires Grafana Enterprise and the user must have the receivers.permissions:write permission for the specified receiver. {{< /admonition >}}

Parameters

All responses

Responses

<span id="route-set-team-receiver-permission-200"></span> 200 - Permission updated

Status: OK

<span id="route-set-team-receiver-permission-200-schema"></span> Schema

{
  "message": "Permission updated"
}

<span id="route-set-team-receiver-permission-400"></span> 400 - Invalid request

Status: Bad Request

<span id="route-set-team-receiver-permission-400-schema"></span> Schema

<span id="route-set-team-receiver-permission-403"></span> 403 - Permission denied

Status: Forbidden

<span id="route-set-team-receiver-permission-403-schema"></span> Schema

PermissionDenied

<span id="route-set-builtin-receiver-permission"></span> Set permissions for a built-in role on a specific receiver. (RouteSetBuiltinReceiverPermission)

POST /api/access-control/receivers/:uid/builtInRoles/:builtInRole

This endpoint sets or removes permissions for a built-in role on a receiver. To remove a permission, send an empty string as the permission value.

{{< admonition type="note" >}} This endpoint requires Grafana Enterprise and the user must have the receivers.permissions:write permission for the specified receiver. {{< /admonition >}}

Parameters

All responses

Responses

<span id="route-set-builtin-receiver-permission-200"></span> 200 - Permission updated

Status: OK

<span id="route-set-builtin-receiver-permission-200-schema"></span> Schema

{
  "message": "Permission updated"
}

<span id="route-set-builtin-receiver-permission-400"></span> 400 - Invalid request

Status: Bad Request

<span id="route-set-builtin-receiver-permission-400-schema"></span> Schema

<span id="route-set-builtin-receiver-permission-403"></span> 403 - Permission denied

Status: Forbidden

<span id="route-set-builtin-receiver-permission-403-schema"></span> Schema

PermissionDenied

<span id="route-get-mute-timing"></span> Get a mute timing. (RouteGetMuteTiming)

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

Parameters

All responses

Responses

<span id="route-get-mute-timing-200"></span> 200 - MuteTimeInterval

Status: OK

<span id="route-get-mute-timing-200-schema"></span> Schema

MuteTimeInterval

<span id="route-get-mute-timing-404"></span> 404 - Not found.

Status: Not Found

<span id="route-get-mute-timing-404-schema"></span> Schema

<span id="route-get-mute-timings"></span> Get all the mute timings. (RouteGetMuteTimings)

GET /api/v1/provisioning/mute-timings

All responses

Responses

<span id="route-get-mute-timings-200"></span> 200 - MuteTimings

Status: OK

<span id="route-get-mute-timings-200-schema"></span> Schema

MuteTimings

<span id="route-get-mute-timings-export"></span> Export all mute timings in provisioning file format. (RouteGetMuteTimingsExport)

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

{{< docs/shared lookup="alerts/alerting-provisioning-export-produces.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Parameters

All responses

Responses

<span id="route-get-mute-timings-export-200"></span> 200 - MuteTimingsExport

Status: OK

<span id="route-get-mute-timings-export-200-schema"></span> Schema

AlertingFileExport

<span id="route-get-mute-timings-export-403"></span> 403 - PermissionDenied

Status: Forbidden

<span id="route-get-mute-timings-export-403-schema"></span> Schema

PermissionDenied

<span id="route-get-mute-timing-export"></span> Export a mute timing in provisioning file format. (RouteGetMuteTimingExport)

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

{{< docs/shared lookup="alerts/alerting-provisioning-export-produces.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Parameters

All responses

Responses

<span id="route-get-mute-timing-export-200"></span> 200 - MuteTimingExport

Status: OK

<span id="route-get-mute-timing-export-200-schema"></span> Schema

AlertingFileExport

<span id="route-get-mute-timing-export-403"></span> 403 - PermissionDenied

Status: Forbidden

<span id="route-get-mute-timing-export-403-schema"></span> Schema

PermissionDenied

<span id="route-get-policy-tree"></span> Get the notification policy tree. (RouteGetPolicyTree)

GET /api/v1/provisioning/policies

All responses

Responses

<span id="route-get-policy-tree-200"></span> 200 - Route

Status: OK

<span id="route-get-policy-tree-200-schema"></span> Schema

Route

<span id="route-get-policy-tree-export"></span> Export the notification policy tree in provisioning file format. (RouteGetPolicyTreeExport)

GET /api/v1/provisioning/policies/export

{{< docs/shared lookup="alerts/alerting-provisioning-export-produces.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Parameters

All responses

Responses

<span id="route-get-policy-tree-export-200"></span> 200 - AlertingFileExport

Status: OK

<span id="route-get-policy-tree-export-200-schema"></span> Schema

AlertingFileExport

<span id="route-get-policy-tree-export-404"></span> 404 - NotFound

Status: Not Found

<span id="route-get-policy-tree-export-404-schema"></span> Schema

NotFound

<span id="route-get-template"></span> Get a notification template group. (RouteGetTemplate)

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

Parameters

All responses

Responses

<span id="route-get-template-200"></span> 200 - NotificationTemplate

Status: OK

<span id="route-get-template-200-schema"></span> Schema

NotificationTemplate

<span id="route-get-template-404"></span> 404 - Not found.

GenericPublicError

<span id="route-get-template-404-schema"></span> Schema

<span id="route-get-templates"></span> Get all notification template groups. (RouteGetTemplates)

GET /api/v1/provisioning/templates

All responses

Responses

<span id="route-get-templates-200"></span> 200 - NotificationTemplates

Status: OK

<span id="route-get-templates-200-schema"></span> Schema

NotificationTemplates

<span id="route-post-alert-rule"></span> Create a new alert rule. (RoutePostAlertRule)

POST /api/v1/provisioning/alert-rules

{{< admonition type="warning" >}} This API is deprecated and will be removed in a future release. Use the Grafana App Platform alerting APIs instead: /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/alertrules for alert rules and /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/recordingrules for recording rules. {{< /admonition >}}

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

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-post-alert-rule-201"></span> 201 - ProvisionedAlertRule

Status: Created

<span id="route-post-alert-rule-201-schema"></span> Schema

ProvisionedAlertRule

<span id="route-post-alert-rule-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-post-alert-rule-400-schema"></span> Schema

ValidationError

<span id="route-post-contactpoints"></span> 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

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-post-contactpoints-202"></span> 202 - EmbeddedContactPoint

Status: Accepted

<span id="route-post-contactpoints-202-schema"></span> Schema

EmbeddedContactPoint

<span id="route-post-contactpoints-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-post-contactpoints-400-schema"></span> Schema

ValidationError

<span id="route-post-mute-timing"></span> Create a new mute timing. (RoutePostMuteTiming)

POST /api/v1/provisioning/mute-timings

Parameters

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-post-mute-timing-201"></span> 201 - MuteTimeInterval

Status: Created

<span id="route-post-mute-timing-201-schema"></span> Schema

MuteTimeInterval

<span id="route-post-mute-timing-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-post-mute-timing-400-schema"></span> Schema

ValidationError

<span id="route-put-alert-rule"></span> Update an existing alert rule. (RoutePutAlertRule)

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

{{< admonition type="warning" >}} This API is deprecated and will be removed in a future release. Use the Grafana App Platform alerting APIs instead: /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/alertrules/{name} for alert rules and /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/recordingrules/{name} for recording rules. {{< /admonition >}}

Parameters

{{% responsive-table %}}

| Name | Source | Type | Go type | 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 | | | | |

{{% /responsive-table %}}

All responses

Responses

<span id="route-put-alert-rule-200"></span> 200 - ProvisionedAlertRule

Status: OK

<span id="route-put-alert-rule-200-schema"></span> Schema

ProvisionedAlertRule

<span id="route-put-alert-rule-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-put-alert-rule-400-schema"></span> Schema

ValidationError

<span id="route-put-alert-rule-group"></span> Create or update a rule group. (RoutePutAlertRuleGroup)

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

{{< admonition type="warning" >}} This API is deprecated and will be removed in a future release. Use the Grafana App Platform alerting APIs instead: /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/alertrules for alert rules and /apis/rules.alerting.grafana.app/v0alpha1/namespaces/{namespace}/recordingrules for recording rules. {{< /admonition >}}

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

Parameters

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-put-alert-rule-group-200"></span> 200 - AlertRuleGroup

Status: OK

<span id="route-put-alert-rule-group-200-schema"></span> Schema

AlertRuleGroup

<span id="route-put-alert-rule-group-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-put-alert-rule-group-400-schema"></span> Schema

ValidationError

<span id="route-put-contactpoint"></span> Update an existing contact point. (RoutePutContactpoint)

PUT /api/v1/provisioning/contact-points/:uid

Parameters

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-put-contactpoint-202"></span> 202 - Ack

Status: Accepted

<span id="route-put-contactpoint-202-schema"></span> Schema

Ack

<span id="route-put-contactpoint-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-put-contactpoint-400-schema"></span> Schema

ValidationError

<span id="route-put-mute-timing"></span> Replace an existing mute timing. (RoutePutMuteTiming)

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

Parameters

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-put-mute-timing-200"></span> 200 - MuteTimeInterval

Status: OK

<span id="route-put-mute-timing-200-schema"></span> Schema

MuteTimeInterval

<span id="route-put-mute-timing-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-put-mute-timing-400-schema"></span> Schema

ValidationError

<span id="route-put-mute-timing-409"></span> 409 - Conflict

Status: Conflict

<span id="route-put-mute-timing-409-schema"></span> Schema

GenericPublicError

<span id="route-put-policy-tree"></span> Sets the notification policy tree. (RoutePutPolicyTree)

{{< docs/shared lookup="alerts/warning-provisioning-tree.md" source="grafana" version="<GRAFANA_VERSION>" >}}

PUT /api/v1/provisioning/policies

Parameters

{{% responsive-table %}}

{{% /responsive-table %}}

All responses

Responses

<span id="route-put-policy-tree-202"></span> 202 - Ack

Status: Accepted

<span id="route-put-policy-tree-202-schema"></span> Schema

Ack

<span id="route-put-policy-tree-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-put-policy-tree-400-schema"></span> Schema

ValidationError

<span id="route-put-template"></span> Create or update a notification template group. (RoutePutTemplate)

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

{{% responsive-table %}}

Parameters

| Name | Source | Type | Go type | Required | Default | Description | | ---------------------------- | ------ | ------------------------------------------------------------- | ------------------------------------ | -------- | :-----: | --------------------------------------------------------- | --- | | name | path | string | string | ✓ | | Name of the template group | | X-Disable-Provenance: true | header | string | string | | | Allows editing of provisioned resources in the Grafana UI | | Body | body | NotificationTemplateContent | models.NotificationTemplateContent | | | | |

{{% /responsive-table %}}

All responses

Responses

<span id="route-put-template-202"></span> 202 - NotificationTemplate

Status: Accepted

<span id="route-put-template-202-schema"></span> Schema

NotificationTemplate

<span id="route-put-template-400"></span> 400 - ValidationError

Status: Bad Request

<span id="route-put-template-400-schema"></span> Schema

GenericPublicError

<span id="route-put-template-409"></span> 409 - Conflict

Status: Conflict

<span id="route-put-template-409-schema"></span> Schema

GenericPublicError

<span id="route-reset-policy-tree"></span> Clears the notification policy tree. (RouteResetPolicyTree)

DELETE /api/v1/provisioning/policies

All responses

Responses

<span id="route-reset-policy-tree-202"></span> 202 - Ack

Status: Accepted

<span id="route-reset-policy-tree-202-schema"></span> Schema

Ack

Models

<span id="ack"></span> Ack

interface{}

<span id="alert-query"></span> AlertQuery

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="alert-query-export"></span> AlertQueryExport

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="alert-rule-export"></span> AlertRuleExport

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="alert-rule-group"></span> AlertRuleGroup

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="alert-rule-group-export"></span> AlertRuleGroupExport

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="alerting-file-export"></span> AlertingFileExport

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="contact-point-export"></span> ContactPointExport

Properties

<span id="contact-points"></span> ContactPoints

[]EmbeddedContactPoint

<span id="duration"></span> Duration

<span id="embedded-contact-point"></span> 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

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="json"></span> Json

interface{}

<span id="match-regexps"></span> MatchRegexps

MatchRegexps

<span id="match-type"></span> MatchType

<span id="matcher"></span> Matcher

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="matchers"></span> 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

<span id="mute-time-interval"></span> MuteTimeInterval

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="mute-timing-export"></span> MuteTimingExport

Properties

<span id="mute-timings-export"></span> MuteTimingsExport

Properties

<span id="mute-timings"></span> MuteTimings

[]MuteTimeInterval

<span id="not-found"></span> NotFound

interface{}

<span id="notification-policy-export"></span> NotificationPolicyExport

Properties

<span id="notification-template"></span> NotificationTemplate

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="notification-template-content"></span> NotificationTemplateContent

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="notification-templates"></span> NotificationTemplates

[]NotificationTemplate

<span id="object-matchers"></span> ObjectMatchers

Matchers

Inlined models

<span id="permission-denied"></span> PermissionDenied

interface{}

<span id="provenance"></span> Provenance

<span id="provisioned-alert-rule"></span> ProvisionedAlertRule

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="provisioned-alert-rules"></span> ProvisionedAlertRules

[]ProvisionedAlertRule

<span id="raw-message"></span> RawMessage

interface{}

<span id="record"></span> Record

Record defines the configuration for a recording rule, which pre-computes query results and saves them as a new time series metric.

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="receiver-export"></span> ReceiverExport

Properties

<span id="regexp"></span> Regexp

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

interface{}

<span id="relative-time-range"></span> RelativeTimeRange

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

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="route"></span> 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

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="route-export"></span> 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

<span id="time-interval"></span> TimeInterval

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

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="time-range"></span> TimeRange

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

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="validation-error"></span> ValidationError

Properties

{{% responsive-table %}}

{{% /responsive-table %}}

<span id="generic-public-error"></span> GenericPublicError

Properties

{{% responsive-table %}}

{{% /responsive-table %}}