From 8ec74206db0cbdfd2033e7b38b5593f0ee2fe4c9 Mon Sep 17 00:00:00 2001
From: "Johnny K." <johnny.kartheiser@grafana.com>
Date: Mon, 12 Jan 2026 14:13:27 -0600
Subject: [PATCH] add recording rule provisioning content

---
 .../shared/alerts/alerting_provisioning.md    | 101 +++++++++++++++++-
 1 file changed, 100 insertions(+), 1 deletion(-)

diff --git a/docs/sources/shared/alerts/alerting_provisioning.md b/docs/sources/shared/alerts/alerting_provisioning.md
index 05885168fdf..62957d9633a 100644
--- a/docs/sources/shared/alerts/alerting_provisioning.md
+++ b/docs/sources/shared/alerts/alerting_provisioning.md
@@ -6,7 +6,7 @@ labels:
 title: '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](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
+The Alerting Provisioning HTTP API can be used to create, modify, and delete resources relevant to Grafana-managed alerts and recording rules. This API is the one used by our [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
 
 For more information on the differences between Grafana-managed and data source-managed alerts, refer to [Introduction to alert rules](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/fundamentals/alert-rules/).
 
@@ -23,6 +23,8 @@ The `export` endpoints allow you to export alerting resources in a JSON format s
 
 ### 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.
+
 | Method | URI                                                              | Name                                                                    | Summary                                                 |
 | ------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
 | DELETE | /api/v1/provisioning/alert-rules/:uid                            | [route delete alert rule](#route-delete-alert-rule)                     | Delete a specific alert rule by UID.                    |
@@ -215,6 +217,103 @@ Content-Type: application/json
 }
 ```
 
+**Example request for new recording rule:**
+
+Recording rules allow you to pre-compute frequently used or computationally expensive expressions and save the results as new time series data. To create a recording rule instead of an alert rule, include a `record` block in your request.
+
+The `record` block contains the following fields:
+
+- `metric`: The name of the new metric to create
+- `from`: The `refId` of the query whose value will be used for the recording
+- `target_datasource_uid`: The UID of the data source where the metric will be written
+
+```http
+POST /api/v1/provisioning/alert-rules
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+{
+  "folderUID": "IpGEy0u7k",
+  "ruleGroup": "Testing",
+  "title": "test-grafana-recording-rule-2",
+  "condition": "",
+  "data": [
+    {
+      "refId": "A",
+      "queryType": "",
+      "relativeTimeRange": {
+        "from": 600,
+        "to": 0
+      },
+      "datasourceUid": "grafanacloud-prom",
+      "model": {
+        "expr": "up{job=\"integrations/macos-node\",instance=\"Bojans-MacBook-Pro.local\"}",
+        "instant": true,
+        "intervalMs": 1000,
+        "legendFormat": "__auto",
+        "maxDataPoints": 43200,
+        "range": false,
+        "refId": "A"
+      }
+    },
+    {
+      "refId": "B",
+      "queryType": "",
+      "relativeTimeRange": {
+        "from": 0,
+        "to": 0
+      },
+      "datasourceUid": "__expr__",
+      "model": {
+        "conditions": [
+          {
+            "evaluator": {
+              "params": [],
+              "type": "gt"
+            },
+            "operator": {
+              "type": "and"
+            },
+            "query": {
+              "params": [
+                "B"
+              ]
+            },
+            "reducer": {
+              "params": [],
+              "type": "last"
+            },
+            "type": "query"
+          }
+        ],
+        "datasource": {
+          "type": "__expr__",
+          "uid": "__expr__"
+        },
+        "expression": "A",
+        "intervalMs": 1000,
+        "maxDataPoints": 43200,
+        "reducer": "last",
+        "refId": "B",
+        "type": "reduce"
+      }
+    }
+  ],
+  "noDataState": "",
+  "execErrState": "",
+  "for": "0s",
+  "keep_firing_for": "0s",
+  "isPaused": false,
+  "notification_settings": null,
+  "record": {
+    "metric": "grafana_recording_rule_test_2",
+    "from": "B",
+    "target_datasource_uid": "grafanacloud-prom"
+  }
+}
+```
+
 ### Contact points
 
 | Method | URI                                        | Name                                                              | Summary                                                |