> ## 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

> What Grantex detects, when it runs, and how an account chooses alert-only or revocation.

## What runs today

`POST /v1/anomalies/detect` is an authenticated, **explicit** detection run. It is not an always-on background monitor. A caller must schedule or invoke it. It evaluates the requesting account's data for:

| Finding | Current threshold | Severity |
| - | - | - |
| `rate_spike` | More than 50 audit actions by one agent in the last hour | High |
| `high_failure_rate` | More than 20% failed or blocked among at least five audit entries in 24 hours | Medium |
| `new_principal` | A newly issued grant for an agent/principal pair with no earlier grant | Low |
| `off_hours_activity` | More than 10 audit entries by one agent between 22:00 and 06:00 UTC in 24 hours | Low |

The endpoint persists findings and replaces that account's unacknowledged findings from the previous run. Acknowledged findings remain. The separate `/v1/anomaly/rules` catalog lists additional built-in definitions, but those definitions are **not** all evaluated by this detector. Custom rules and `/v1/anomaly/channels` are configuration records; the legacy detector does not execute custom rule conditions or dispatch to channel records. Do not rely on either as an active security control.

## Account response policy

With `IRREGULARITY_RESPONSE_POLICY_ENABLED=true`, the account can choose one response for this detector:

| Mode | Effect when a high or critical finding identifies an agent |
| - | - |
| `revoke_agent_grants` (default) | Revoke that agent's active, unexpired grants in this account. This may affect many principals when they share an agent. |
| `alert_only` | Persist findings and emit `anomaly.detected` events, but do not revoke grants through this detector. |

The mode applies to the **whole account**, not an individual agent or grant. It does not turn off manual revocation, independent policy checks, or other security controls. A policy change is recorded in account history and emits an `irregularity.policy.updated` event on a best-effort basis. If the flag is off, the policy endpoints return 404 and the detector retains its previous automatic-revocation behavior. If the flag is on but policy state is unavailable, detection fails closed with 503.

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

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 the policy back before relying on alert-only mode. The portal's **Irregularities** page provides the same account-level control when the operator has enabled it.

## Running and reviewing detection

```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 '{}'
```

The response includes `responseMode`, `total`, `autoRevokedGrants`, and `anomalies`. Use `GET /v1/anomalies` to read persisted findings and `PATCH /v1/anomalies/{id}/acknowledge` to acknowledge one. The separate `/v1/anomaly/alerts` routes provide the alert lifecycle (`open`, `acknowledged`, `resolved`).

When the response-policy flag is enabled, each persisted finding from a detection run emits an `anomaly.detected` event. Subscribe through the existing event stream or a standard Grantex webhook subscription for that event type. Delivery is best-effort: query stored findings if delivery is critical to your workflow. Creating a record under `/v1/anomaly/channels` does **not** send Slack, email, or webhook notifications. PagerDuty and Datadog are not accepted channel types there.

`GET /v1/anomaly/metrics?window=24h` returns aggregate stored-alert counts. Supported windows are `1h`, `6h`, and `24h`; this endpoint is distinct from the Prometheus `/metrics` endpoint.

For rollout and a runnable example, see [Irregularity Detection Setup](/guides/anomaly-detection-setup). Response-policy helpers are published in TypeScript `@grantex/sdk@0.8.2`, Python `grantex==0.7.2`, and Go `v0.4.3`. See [Release Status](/release-status).

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


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