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

# Intentions

> List, create, and publish the declarative intent patterns Inviolet matches against every tool call.

An intention is a named pattern — "Customer Support Lookup", "Pipeline
Review" — with an intent class, optional approval requirement, an
allowed data-element list, and a token TTL. Every intent evaluation
either matches an active intention or falls into the ambient cluster.

## Endpoints

| Method | Path                          | Description                             |
| ------ | ----------------------------- | --------------------------------------- |
| `GET`  | `/v1/intentions`              | List all intentions for the org         |
| `POST` | `/v1/intentions`              | Create a new intention (status `draft`) |
| `POST` | `/v1/intentions/{id}/publish` | Promote a draft to `active`             |

Creating or publishing an intention requires the `policy_write` or
`admin` scope on the API key.

## Intention object

```json theme={"dark"}
{
  "id": "intention_2pX9...",
  "label": "customer_support_lookup",
  "display_name": "Customer Support Lookup",
  "description": "Look up a customer's name + email when answering a support ticket.",
  "intent_class": "lookup",
  "status": "active",
  "approval_required": false,
  "ttl_minutes": 5,
  "data_elements": [
    { "data_source_id": "salesforce_prod", "path": "Account.Name" },
    { "data_source_id": "salesforce_prod", "path": "Contact.Email" }
  ],
  "created_at": "2026-04-20T10:00:00Z",
  "updated_at": "2026-04-21T14:30:00Z"
}
```

`intent_class` is one of `reporting`, `export`, `admin`, `lookup`,
`analysis`, `write`, `other`. `status` is `draft`, `active`, or
`archived` — only `active` intentions match traffic.

## List intentions

```http theme={"dark"}
GET /v1/intentions
Authorization: Bearer <INVIOLET_API_KEY>
```

Response:

```json theme={"dark"}
{
  "data": [
    { "id": "intention_2pX9...", "label": "customer_support_lookup", "...": "..." }
  ]
}
```

## Create an intention

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

{
  "label": "customer_support_lookup",
  "display_name": "Customer Support Lookup",
  "intent_class": "lookup",
  "approval_required": false,
  "ttl_minutes": 5,
  "data_elements": [
    { "data_source_id": "salesforce_prod", "path": "Account.Name" },
    { "data_source_id": "salesforce_prod", "path": "Contact.Email" }
  ]
}
```

Returns `201 Created` with the new intention object. Status defaults to
`draft`.

## Publish

```http theme={"dark"}
POST /v1/intentions/{id}/publish
Authorization: Bearer <INVIOLET_API_KEY>
```

Promotes a draft to `active`. The next matching tool call is decided
against the intention immediately.

## Errors

`403` if the API key lacks `policy_write`. `409` if a label collides
with an existing intention.

## Read next

* **[Intent Events](/api-reference/intent-events)** — what evaluates
  against the intentions you publish
* **[Define your intention policies](/guides/define-your-intention-policies)**