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

# Intent Events

> Evaluate an LLM tool call, page through history, and verify the resulting grant.

The Intent resource is the core of the Inviolet API. Every
`intent.evaluate` call extracts the intent class, matches against
published intentions, evaluates policy, and returns the access decision
plus (when allowed) a short-lived grant.

## Endpoints

| Method | Path                  | Description                      |
| ------ | --------------------- | -------------------------------- |
| `POST` | `/v1/intent/evaluate` | Evaluate one tool call           |
| `GET`  | `/v1/intent/history`  | Page through recent evaluations  |
| `POST` | `/v1/grants/verify`   | Verify a previously issued grant |

## Evaluate

Request:

```http theme={"dark"}
POST /v1/intent/evaluate
Authorization: Bearer <INVIOLET_API_KEY>
Content-Type: application/json

{
  "user_id": "user_2pX9...",
  "session_id": "sess_abc",
  "tool_call": {
    "name": "lookup_customer",
    "arguments": { "customer_id": "12345" }
  },
  "data_source_id": "salesforce_prod",
  "shadow_mode": false
}
```

Response (`200`):

```json theme={"dark"}
{
  "outcome": "allowed",
  "intent_event_id": "ie_2pX9...",
  "intent_label": "customer_support_lookup",
  "intent_class": "lookup",
  "confidence": 0.94,
  "data_elements": ["customer.name", "customer.email"],
  "shadow_mode": false,
  "processing_time_ms": 38
}
```

Possible `outcome` values: `allowed`, `denied`, `pending_approval`,
`approved`, `shadow_denied`. When `outcome = pending_approval`, the
response includes `approval_request_id` for polling.

## Node SDK example

```ts theme={"dark"}
import { Inviolet } from "@inviolet/sdk"

const inviolet = new Inviolet({ apiKey: process.env.INVIOLET_API_KEY! })

const decision = await inviolet.intent.evaluate({
  userId: "user_2pX9...",
  toolCall: { name: "lookup_customer", arguments: { customer_id: "12345" } },
  dataSourceId: "salesforce_prod",
})
```

<Note>
  `POST /v1/intent/evaluate` is the lightweight **legacy policy path**. For
  structural, credential-brokered enforcement, mint a
  [mandate](/concepts/mandates) via
  [`POST /v1/mandate/dispense`](/api-reference/dispense) and guard the call via
  [`POST /v1/mcp-proxy/call`](/api-reference/decide).
</Note>

## History

```ts theme={"dark"}
const history = await inviolet.intent.history({
  limit: 50,
  outcome: "denied",
  since: "2026-04-25T00:00:00Z",
})
```

Returns paginated events. Use `next_cursor` to walk forward.

## Verify a token

```ts theme={"dark"}
const result = await inviolet.tokens.verify({ token: grant })
// result.valid === true / false
// result.grant.data_elements is the approved column set
```

## Errors

`401` missing/invalid API key · `400` invalid request body · `429`
rate-limited · `5xx` retryable.

## Read next

* **[Intentions](/api-reference/intentions)**
* **[Webhooks](/api-reference/webhooks)**
* **[Mandates](/concepts/mandates)** — the JWT shape that carries intention
  downstream