> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Irregularity Detection Setup

> Run Grantex's explicit detector and choose an account-wide alert-only or revocation response.

## 1. Confirm the rollout

The server operator must set `IRREGULARITY_RESPONSE_POLICY_ENABLED=true` after deploying the schema migration. The switch is off by default. It enables the account response-policy API and `anomaly.detected` event emission for explicit detection runs; it does not start a scheduler.

With your account's developer API key, check the current mode:

```bash theme={null}
curl -H "Authorization: Bearer $GRANTEX_API_KEY" \
  https://api.grantex.dev/v1/irregularities/response-policy
```

A 404 means this deployment has not enabled the policy feature. A 503 means the policy cannot be read and detection fails closed while the feature is enabled. The default mode for an enabled account is `revoke_agent_grants`.

## 2. Choose the account response

If several principals' grants share one agent, a high-severity finding can revoke all that agent's active grants in the account. Choose `alert_only` when human review should precede a manual revocation:

```bash theme={null}
curl -X PATCH https://api.grantex.dev/v1/irregularities/response-policy \
  -H "Authorization: Bearer $GRANTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"alert_only"}'
```

Read it back with the GET request above. This setting is **account-wide** and affects only the legacy detector's automatic grant revocation. It does not bypass other policy enforcement. Use `revoke_agent_grants` to restore the original response. The portal's **Irregularities** page exposes the same setting. Policy changes are stored in account history.

## 3. Run and inspect the detector

Call the detector explicitly, or schedule this call from your own service:

```bash theme={null}
curl -X POST https://api.grantex.dev/v1/anomalies/detect \
  -H "Authorization: Bearer $GRANTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Check `responseMode` and `autoRevokedGrants` in the response. `alert_only` must return `autoRevokedGrants: 0`. Read stored findings separately:

```bash theme={null}
curl -H "Authorization: Bearer $GRANTEX_API_KEY" \
  'https://api.grantex.dev/v1/anomalies?unacknowledged=true'
```

This detector currently evaluates rate spikes, high failure rates, new principals, and off-hours activity. Listing ten built-in definitions at `/v1/anomaly/rules` is not evidence that all ten run. Custom-rule and channel APIs store configuration but do not execute or dispatch for this detector. See [Irregularity Detection](/features/anomaly-detection) for exact thresholds.

## 4. Deliver findings to a human

With the response-policy flag enabled, each persisted finding emits `anomaly.detected` through the existing event bus. Register a standard Grantex webhook subscription for that type, or consume the event stream. Filter by severity in your consumer and route the event to your own review queue. Event delivery is best-effort, so reconcile with `GET /v1/anomalies` after failures or outages. A record created under `/v1/anomaly/channels` alone does not send a notification.

Response-policy methods are published in TypeScript `@grantex/sdk@0.8.2`, Python `grantex==0.7.2`, and Go `v0.4.3`. The REST calls above work with a deployment that has enabled the flag. See [Release Status](/release-status).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.