> For the complete documentation index, see [llms.txt](https://docs.mozilla.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mozilla.ai/any-guardrail/api-reference/index/content-safety/watsonx-guardian.md).

# watsonx Guardian

Hosted text-detection moderation API running configurable Granite Guardian detectors.

This is the hosted, pay-per-use counterpart to the locally-run :class:`~any_guardrail.guardrails.granite_guardian.granite_guardian.GraniteGuardian` guardrail: the same Granite Guardian risk-detection family, served as a purpose-built detection endpoint instead of running the weights yourself.

The `Guardian` class (from the `ibm-watsonx-ai` SDK) screens text against a configurable set of detectors. The default `granite_guardian` detector covers the Granite Guardian risk catalogue (harm, social bias, violence, jailbreak, profanity, sexual content, plus RAG groundedness / relevance); `hap` (hate-abuse-profanity) and `pii` detectors are also available. Each detector returns zero or more *detections*, each locating a risky span with a score.

Auth is via an IBM Cloud IAM API key plus a region URL and a project (or space). Obtain a key and project from <https://dataplatform.cloud.ibm.com/> and set them via `WATSONX_APIKEY` / `WATSONX_URL` / `WATSONX_PROJECT_ID` (or `WATSONX_SPACE_ID`), or pass them directly. A free Lite plan is available.

`GuardrailOutput` mapping: - `valid = no detections were returned` (the detection API only returns detections at or above the configured threshold). - `score` is the highest detection score; `0.0` when nothing was detected. - `categories` lists one `CategoryResult` per detection (`name` = the detected risk, `triggered=True`, `score` = the detection score). - `spans` lists one `SpanResult` per detection that carries character offsets (watsonx detections locate the flagged substring). - `raw` is the full response dict from `Guardian.detect`.

Expected input: `validate` takes a single string, `content`, and screens it against the configured detectors. There is no separate prompt-vs-response argument; RAG groundedness / relevance are enabled by adding the corresponding detector to `detectors` rather than by passing extra arguments here.

Research backing: - Padhi et al., *Granite Guardian* (<https://arxiv.org/abs/2412.07724>, 2024). - IBM tutorial: <https://www.ibm.com/think/tutorials/llm-safeguards-granite-guardian-risk-detection> - SDK reference: <https://ibm.github.io/watsonx-ai-python-sdk/fm\\_text\\_detection.html>

For more information, see:

* [watsonx.ai platform (API key / project, free Lite plan)](https://dataplatform.cloud.ibm.com/)
* [IBM tutorial: LLM safeguards with Granite Guardian risk detection](https://www.ibm.com/think/tutorials/llm-safeguards-granite-guardian-risk-detection)
* [watsonx.ai Python SDK: foundation-model text detection](https://ibm.github.io/watsonx-ai-python-sdk/fm_text_detection.html)
* [Granite Guardian (arXiv:2412.07724)](https://arxiv.org/abs/2412.07724)

## Supported Models

* `granite_guardian`

## Constructor

| Parameter    | Type              | Required | Default | Description |
| ------------ | ----------------- | -------- | ------- | ----------- |
| `api_key`    | \`str             | None\`   | No      | `None`      |
| `url`        | \`str             | None\`   | No      | `None`      |
| `project_id` | \`str             | None\`   | No      | `None`      |
| `space_id`   | \`str             | None\`   | No      | `None`      |
| `detectors`  | \`dict\[str, Any] | None\`   | No      | `None`      |
| `api_client` | \`APIClient       | None\`   | No      | `None`      |

Initialize the guardrail and build the watsonx `Guardian` client.

Building the client performs IAM authentication, so unlike the pure-REST API guardrails this constructor does contact IBM Cloud (unless a pre-built `api_client` is supplied).

## validate

Screen `content` against the configured watsonx detectors.

**Parameters**

| Parameter | Type  | Required | Default | Description         |
| --------- | ----- | -------- | ------- | ------------------- |
| `content` | `str` | Yes      | —       | The text to screen. |

**Returns:** `GuardrailOutput`

## Benchmarks

No benchmark results recorded yet. See the [benchmark methodology](/any-guardrail/api-reference/benchmarks.md) for how numbers are harvested (published) or measured and added.

## License

* **Vendor:** IBM
* **Default license:** `proprietary` (of the default model/service)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mozilla.ai/any-guardrail/api-reference/index/content-safety/watsonx-guardian.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.