---
title: "Guards API | Grafana Cloud documentation"
description: "Evaluate requests against guards and manage guard rules."
---

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

# Guards API

Evaluate requests against guards and manage guard rules.

## Before you begin

- Enable Agent Observability on your Grafana Cloud stack. Refer to [Set up Agent Observability in Grafana Cloud](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/grafana-cloud).
- For configuration changes, use a Grafana identity with permission to manage the relevant resource. Refer to [Security and access controls](/docs/grafana-cloud/observe-and-act/agent-observability/privacy-and-access/security).

For credential requirements, refer to [Choose credentials](/docs/grafana-cloud/observe-and-act/agent-observability/reference/#choose-credentials).

## Manage guards

Use guard endpoints to evaluate requests synchronously and manage guard rules.

Expand table

| Method   | Path                           | Description                                |
|----------|--------------------------------|--------------------------------------------|
| `POST`   | `/api/v1/hooks:evaluate`       | Evaluate a request against enabled guards. |
| `GET`    | `/api/v1/eval/hook-rules`      | List all guard rules.                      |
| `POST`   | `/api/v1/eval/hook-rules`      | Create a guard rule.                       |
| `GET`    | `/api/v1/eval/hook-rules/{id}` | Get a guard rule by ID.                    |
| `PUT`    | `/api/v1/eval/hook-rules/{id}` | Update a guard rule.                       |
| `DELETE` | `/api/v1/eval/hook-rules/{id}` | Delete a guard rule.                       |

### Hook evaluation request

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

```json
{
  "phase": "preflight",
  "context": {
    "agent_name": "my-agent",
    "model": { "provider": "openai", "name": "gpt-4o" },
    "tags": { "env": "production" }
  },
  "input": {
    "messages": [
      { "role": "user", "parts": [{ "kind": "text", "text": "Hello" }] }
    ],
    "system_prompt": "You are a helpful assistant.",
    "tools": []
  }
}
```

### Hook evaluation response

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

```json
{
  "action": "allow",
  "rule_id": "redact_pii",
  "transformed_input": null,
  "evaluations": []
}
```

The `action` field is `allow` or `deny`. When any guard rule applied transforms, `transformed_input` contains the sanitized copy of the input, and `rule_id` contains the ID of the first rule that changed the input. `rule_id` is empty when no transform fired. Each entry in `evaluations` reports a per-rule outcome with `rule_id`, `evaluator_id`, `passed`, and `latency_ms`.

### Guard rule configuration

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

```json
{
  "rule_id": "block_tools",
  "enabled": true,
  "phase": "preflight",
  "priority": 5,
  "selector": "all",
  "match": {},
  "evaluator_ids": [],
  "action_on_fail": "deny",
  "tool_filter": { "blocked_names": ["shell_exec", "danger_*"] },
  "redact": {
    "patterns": [
      { "id": "ssn", "regex": "\\b\\d{3}-\\d{2}-\\d{4}\\b" }
    ]
  }
}
```

Each guard rule must include at least one of these fields: `evaluator_ids`, `redact.patterns`, or `tool_filter.blocked_names`. Redaction matches are always replaced with the fixed token `[REDACTED]`; free-form replacement text is not accepted.

## Next steps

- [Set up guards](/docs/grafana-cloud/observe-and-act/agent-observability/protect-agents/guards)
- [Configure evaluators](/docs/grafana-cloud/observe-and-act/agent-observability/reference/evaluation/#configure-evaluator-types)