Platform

Assistant

SDK

HTTP API

Rules

Grafana Cloud

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.

Create a rule

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

Endpoint

POST /rules

Permissions

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

Request

Send a JSON request body.

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.

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

{
  "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

{
  "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

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

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

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

Request

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

{
  "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

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

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

Request

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

Response

{
  "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

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

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

Parameter	Required	Description
`id`	Yes	The rule ID.

Send a JSON request body with the fields to update.

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.

{
  "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:

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

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

Request

Parameter	Required	Description
`id`	Yes	The rule ID.

Response

A successful deletion returns HTTP 204 with no response body.

Examples

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

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