---
title: "Rules API | Grafana Cloud documentation"
description: "Create, list, update, and delete Grafana Assistant rules with the HTTP API."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Rules API

Use rules to provide persistent instructions that guide Assistant behavior across conversations. Rules let you customize how Assistant responds, enforce standards, and apply organization-wide context.

Rules have two scopes:

- **Tenant rules** apply to all users in the organization. Use tenant rules when you manage rules through the HTTP API, because they affect all Assistant conversations across the organization.
- **User rules** apply only to the identity that created them. When a service account creates a user rule, that rule applies only to conversations started by the same service account. You can’t create user rules on behalf of other users.

Each identity can create up to 100 rules.

Examples use the base URL and service account token described in [Grafana Assistant HTTP API reference](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis).

## Create a rule

Create a new user-scoped or tenant-scoped rule.

**Endpoint**

`POST /rules`

**Permissions**

Expand table

| Rule scope | Required permission                         |
|------------|---------------------------------------------|
| `user`     | `grafana-assistant-app.rules.user:create`   |
| `tenant`   | `grafana-assistant-app.rules.tenant:create` |

**Request**

Send a JSON request body.

Expand table

| Field          | Required | Description                                                         |
|----------------|----------|---------------------------------------------------------------------|
| `scope`        | Yes      | Rule scope: `user` or `tenant`.                                     |
| `name`         | Yes      | Display name for the rule.                                          |
| `ruleContent`  | Yes      | The instruction text included in Assistant conversations.           |
| `enabled`      | Yes      | Whether the rule is active.                                         |
| `priority`     | Yes      | Priority order. Lower values have higher priority.                  |
| `applications` | Yes      | Applications the rule applies to. Defaults to `["all"]` when empty. |
| `description`  | No       | A short description of the rule.                                    |

**Application values**

The `applications` field controls which Assistant products use the rule.

Expand table

| Value                   | Product                 |
|-------------------------|-------------------------|
| `assistant`             | Assistant               |
| `loop`                  | Investigations          |
| `infrastructure_memory` | Infrastructure memories |
| `all`                   | All applications        |

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "scope": "tenant",
  "name": "Use metric naming conventions",
  "ruleContent": "When suggesting PromQL queries, always use the naming convention <namespace>_<subsystem>_<name>_<unit> for metric names.",
  "enabled": true,
  "priority": 0,
  "applications": ["assistant"]
}
```

**Response**

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "status": "success",
  "data": {
    "id": "a3b1c2d4-5678-9012-abcd-ef3456789012",
    "created": "2025-11-15T08:30:00Z",
    "modified": "2025-11-15T08:30:00Z",
    "createdBy": "sa-5594@serviceaccount.grafana",
    "updatedBy": "sa-5594@serviceaccount.grafana",
    "name": "Use metric naming conventions",
    "ruleContent": "When suggesting PromQL queries, always use the naming convention <namespace>_<subsystem>_<name>_<unit> for metric names.",
    "enabled": true,
    "priority": 0,
    "scope": "tenant",
    "applications": ["assistant"]
  }
}
```

**Examples**

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
curl -X POST "${ASSISTANT_API_URL}/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -d '{
    "scope": "tenant",
    "name": "Use metric naming conventions",
    "ruleContent": "When suggesting PromQL queries, always use the naming convention <namespace>_<subsystem>_<name>_<unit> for metric names.",
    "enabled": true,
    "priority": 0,
    "applications": ["assistant"]
  }'
```

**Errors**

Expand table

| Status code       | Condition                                                                                                       |
|-------------------|-----------------------------------------------------------------------------------------------------------------|
| `400 Bad Request` | Rule limit exceeded. Each user can create a maximum of 100 rules. Delete unused rules before creating new ones. |

## List rules

Retrieve rules with optional filtering and pagination.

**Endpoint**

`GET /rules`

**Permissions**

Expand table

| Rule scope | Required permission                       |
|------------|-------------------------------------------|
| `user`     | `grafana-assistant-app.rules.user:read`   |
| `tenant`   | `grafana-assistant-app.rules.tenant:read` |

**Request**

Expand table

| Parameter      | Required | Description                                                     |
|----------------|----------|-----------------------------------------------------------------|
| `scope`        | No       | Filter by scope: `user` or `tenant`.                            |
| `enabled_only` | No       | When `true`, return only enabled rules.                         |
| `limit`        | No       | Maximum number of rules to return. Range: 1-100. Default: `20`. |
| `offset`       | No       | Pagination offset. Default: `0`.                                |

**Response**

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "status": "success",
  "data": {
    "rules": [
      {
        "id": "a3b1c2d4-5678-9012-abcd-ef3456789012",
        "created": "2025-11-15T08:30:00Z",
        "modified": "2025-11-15T08:30:00Z",
        "createdBy": "sa-5594@serviceaccount.grafana",
        "updatedBy": "sa-5594@serviceaccount.grafana",
        "name": "Use metric naming conventions",
        "ruleContent": "When suggesting PromQL queries, always use the naming convention <namespace>_<subsystem>_<name>_<unit> for metric names.",
        "enabled": true,
        "priority": 0,
        "scope": "tenant",
        "applications": ["assistant"]
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
}
```

**Examples**

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
curl -X GET "${ASSISTANT_API_URL}/rules?scope=tenant&enabled_only=true&limit=10" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"
```

## Get a rule

Retrieve a single rule by ID.

**Endpoint**

`GET /rules/{id}`

**Permissions**

Expand table

| Rule scope | Required permission                       |
|------------|-------------------------------------------|
| `user`     | `grafana-assistant-app.rules.user:read`   |
| `tenant`   | `grafana-assistant-app.rules.tenant:read` |

**Request**

Expand table

| Parameter | Required | Description                                  |
|-----------|----------|----------------------------------------------|
| `id`      | Yes      | The rule ID returned when you create a rule. |

**Response**

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "status": "success",
  "data": {
    "id": "a3b1c2d4-5678-9012-abcd-ef3456789012",
    "created": "2025-11-15T08:30:00Z",
    "modified": "2025-11-15T08:30:00Z",
    "createdBy": "sa-5594@serviceaccount.grafana",
    "updatedBy": "sa-5594@serviceaccount.grafana",
    "name": "Use metric naming conventions",
    "ruleContent": "When suggesting PromQL queries, always use the naming convention <namespace>_<subsystem>_<name>_<unit> for metric names.",
    "enabled": true,
    "priority": 0,
    "scope": "tenant",
    "applications": ["assistant"]
  }
}
```

**Examples**

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
RULE_ID="a3b1c2d4-5678-9012-abcd-ef3456789012"

curl -X GET "${ASSISTANT_API_URL}/rules/${RULE_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"
```

## Update a rule

Update an existing rule. Only the fields you include in the request body are changed, except `scope` which is always required.

**Endpoint**

`PUT /rules/{id}`

**Permissions**

Expand table

| Rule scope | Required permission                        |
|------------|--------------------------------------------|
| `user`     | `grafana-assistant-app.rules.user:write`   |
| `tenant`   | `grafana-assistant-app.rules.tenant:write` |

To change a rule’s scope, the service account needs write permissions for both scopes.

**Request**

Expand table

| Parameter | Required | Description  |
|-----------|----------|--------------|
| `id`      | Yes      | The rule ID. |

Send a JSON request body with the fields to update.

Expand table

| Field          | Required | Description                                                                                                                                  |
|----------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------|
| `scope`        | Yes      | The desired scope. Set to the current value to keep the scope unchanged, or set a different value to transition between `user` and `tenant`. |
| `name`         | No       | Updated display name.                                                                                                                        |
| `ruleContent`  | No       | Updated instruction text.                                                                                                                    |
| `description`  | No       | Updated description.                                                                                                                         |
| `enabled`      | No       | Whether the rule is active.                                                                                                                  |
| `priority`     | No       | Updated priority order.                                                                                                                      |
| `applications` | No       | Updated application list.                                                                                                                    |

**Response**

The response contains the full updated rule.

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "status": "success",
  "data": {
    "id": "a3b1c2d4-5678-9012-abcd-ef3456789012",
    "created": "2025-11-15T08:30:00Z",
    "modified": "2025-11-20T14:15:00Z",
    "createdBy": "sa-5594@serviceaccount.grafana",
    "updatedBy": "sa-5594@serviceaccount.grafana",
    "name": "Use metric naming conventions",
    "ruleContent": "When suggesting PromQL queries, always use the naming convention <namespace>_<subsystem>_<name>_<unit> for metric names.",
    "enabled": false,
    "priority": 0,
    "scope": "tenant",
    "applications": ["assistant"]
  }
}
```

**Examples**

Disable a rule:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
RULE_ID="a3b1c2d4-5678-9012-abcd-ef3456789012"

curl -X PUT "${ASSISTANT_API_URL}/rules/${RULE_ID}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -d '{
    "scope": "tenant",
    "enabled": false
  }'
```

## Delete a rule

Permanently delete a rule.

**Endpoint**

`DELETE /rules/{id}`

**Permissions**

Expand table

| Rule scope | Required permission                         |
|------------|---------------------------------------------|
| `user`     | `grafana-assistant-app.rules.user:delete`   |
| `tenant`   | `grafana-assistant-app.rules.tenant:delete` |

**Request**

Expand table

| Parameter | Required | Description  |
|-----------|----------|--------------|
| `id`      | Yes      | The rule ID. |

**Response**

A successful deletion returns HTTP 204 with no response body.

**Examples**

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
RULE_ID="a3b1c2d4-5678-9012-abcd-ef3456789012"

curl -X DELETE "${ASSISTANT_API_URL}/rules/${RULE_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"
```