> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/manage-intents.md).

# Manage Intents

{% hint style="info" %}
**Private preview**: This feature is available to select accounts. Contact your Immuta representative for details.
{% endhint %}

The `intent` API allows users to create and manage intents.

## Permissions

`GOVERNANCE` Immuta permission

## Endpoints and methods

| Method        | Endpoint                                                                 | Description                               |
| ------------- | ------------------------------------------------------------------------ | ----------------------------------------- |
| **POST**      | [`/intent`](#post-intent)                                                | Creates a new intent                      |
| **DELETE**    | [`/intent/{id}`](#delete-intent-id)                                      | Deletes an intent                         |
| **GET**       | [`/intent/{id}`](#get-intent-id)                                         | Retrieves an intent                       |
| **PUT**       | [`/intent/{id}`](#put-intent-id)                                         | Updates an intent name or description     |
| **PUT, POST** | [`/intent/{id}/attributes`](#put-intent-id-attributes)                   | Updates attributes assigned to the intent |
| **PATCH**     | [`/intent/{id}/attributes/{action}`](#patch-intent-id-attributes-action) | Adds or removes attributes from an intent |
| **DELETE**    | [`/intent/{id}/groupAssignment`](#delete-intent-id-groupassignment)      | Removes groups from the intent            |
| **POST**      | [`/intent/{id}/groupAssignment`](#post-intent-id-groupassignment)        | Assigns groups to the intent              |
| **POST**      | [`/intents/search`](#post-intents-search)                                | Retrieves a list of intents               |

## <mark style="color:green;">`POST`</mark> `/intent`

Create a new intent. You can also [add a description](#put-intent-id), [assign](#post-intent-id-groupassignment) or [remove groups](#delete-intent-id-groupassignment), and [assign or remove attributes](#patch-intent-id-attributes-action) after creating the intent.

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/intent' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "name": "Fraud detection",
    "description": "While acting under this intent, users can see internal data.",
    "groups": [ {"name": "Analysts", "iamid": "bim"} ],
    "authorizations": { "Exception": ["Internal"] }
    }'
```

### Body parameters

| Parameter                   | Description                                                                                                                                                                                                                                                                                                                                                            | Required or optional | Accepted values |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | --------------- |
| **name** `string`           | The name of the intent.                                                                                                                                                                                                                                                                                                                                                | Required             | -               |
| **description** `string`    | The description of the intent that will be displayed for users.                                                                                                                                                                                                                                                                                                        | Optional             | -               |
| **authorizations** `object` | The attribute key-value pairs assigned to the intent.                                                                                                                                                                                                                                                                                                                  | Required             | -               |
| **groups.name** `string`    | The group names assigned to the intent.                                                                                                                                                                                                                                                                                                                                | Required             | -               |
| **groups.iamid** `string`   | The unique identifier of the identity provider that contains the groups. You can find this ID in the identity provider's configuration section on the app settings page or [through the Immuta API](/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-iams). If you created the group in Immuta, this value is `bim`. | Required             | -               |

### Response

Returns the [intent object](#intent-object-attributes).

{% code overflow="wrap" %}

```json
{
  "id": 1,
  "name": "Fraud detection",
  "description": "While acting under this intent, users can see internal data.",
  "authorizations": {
    "Exception": [
      "Internal"
    ]
  },
  "deleted": false,
  "createdAt": "2026-05-04T18:48:40.602Z",
  "updatedAt": "2026-05-04T19:38:52.438Z",
  "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}
```

{% endcode %}

## <mark style="color:green;">`DELETE`</mark> `/intent/{id}`

Delete an intent.

{% code overflow="wrap" %}

```bash
curl -X 'DELETE' \
    'https://www.organization.immuta.com/intent/{id}' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json'
```

{% endcode %}

### Path parameter

| Parameter        | Description                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **id** `integer` | The unique identifier of the intent. You can retrieve a list of intent IDs using the [`/intents/search` endpoint](#post-intents-search). |

### Response

Returns a **200** code when the intent is successfully deleted.

## <mark style="color:green;">`GET`</mark> `/intent/{id}`

Retrieve a specific intent.

{% code overflow="wrap" %}

```
curl -X 'GET' \
    'https://www.organization.immuta.com/intent/{id}' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json'
```

{% endcode %}

### Path parameter

| Parameter        | Description                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **id** `integer` | The unique identifier of the intent. You can retrieve a list of intent IDs using the [`/intents/search` endpoint](#post-intents-search). |

### Response

Returns the [intent object](#intent-object-attributes).

{% code overflow="wrap" %}

```json
{
  "id": 1,
  "name": "Fraud detection",
  "description": "While acting under this intent, users can see internal data.",
  "authorizations": {
    "Exception": [
      "Internal"
    ]
  },
  "deleted": false,
  "createdAt": "2026-05-04T18:48:40.602Z",
  "updatedAt": "2026-05-04T19:38:52.438Z",
  "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}
```

{% endcode %}

## <mark style="color:green;">`PUT`</mark> `/intent/{id}`

Update the intent name or description.

{% code overflow="wrap" %}

```bash
curl -X 'PUT' \
    'https://www.organization.immuta.com/intent/{id}' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "name": "Fraud detection",
    "description": "This intent allows users in the Analysts group to see internal data."
    }'
```

{% endcode %}

### Path parameter

| Parameter        | Description                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **id** `integer` | The unique identifier of the intent. You can retrieve a list of intent IDs using the [`/intents/search` endpoint](#post-intents-search). |

### Body parameters

| Parameter                | Description                    |
| ------------------------ | ------------------------------ |
| **name** `string`        | The name of the intent.        |
| **description** `string` | The description of the intent. |

### Response

Returns the [intent object](#intent-object-attributes).

{% code overflow="wrap" %}

```json
{
  "id": 1,
  "name": "Fraud detection",
  "description": "This intent allows users in the Analysts group to see internal data.",
  "authorizations": {
    "Exception": [
      "Internal"
    ]
  },
  "deleted": false,
  "createdAt": "2026-05-04T18:48:40.602Z",
  "updatedAt": "2026-05-04T19:38:52.438Z",
  "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}
```

{% endcode %}

## <mark style="color:green;">`PUT`</mark>, <mark style="color:green;">`POST`</mark> `/intent/{id}/attributes`

Update the attributes assigned to the intent. The attributes included in the payload will replace existing attributes assigned to the intent.

{% code overflow="wrap" %}

```bash
curl -X 'PUT' \
    'https://www.organization.immuta.com/intent/{id}/attributes' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "authorizations": { "ClearanceLevel" :["High"] }
    }'
```

{% endcode %}

### Path parameter

| Parameter        | Description                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **id** `integer` | The unique identifier of the intent. You can retrieve a list of intent IDs using the [`/intents/search` endpoint](#post-intents-search). |

### Body parameter

| Parameter                   | Description                                                               |
| --------------------------- | ------------------------------------------------------------------------- |
| **authorizations** `object` | Includes attribute keys that each pair with an array of attribute values. |

### Response

Returns the [intent object](#intent-object-attributes).

{% code overflow="wrap" %}

```json
{
  "id": 1,
  "name": "Fraud detection",
  "description": "This intent allows users in the Analysts group to see internal data.",
  "authorizations": {
    "ClearanceLevel": [
      "High"
    ]
  },
  "deleted": false,
  "createdAt": "2026-05-04T18:48:40.602Z",
  "updatedAt": "2026-05-04T19:38:52.438Z",
  "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}
```

{% endcode %}

## <mark style="color:green;">`PATCH`</mark> `/intent/{id}/attributes/{action}`

Add or remove specific attributes from an intent.

{% code overflow="wrap" %}

```bash
curl -X 'PATCH' \
    'https://www.organization.immuta.com/intent/{id}/attributes/remove' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "authorizations": { "ClearanceLevel" :["High"] }
    }'
```

{% endcode %}

### Path parameters

| Parameter           | Description                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **id** `integer`    | The unique identifier of the intent. You can retrieve a list of intent IDs using the [`/intents/search` endpoint](#post-intents-search). |
| **action** `string` | Specifies whether to `add` or `remove` the provided attribute.                                                                           |

### Body parameter

| Parameter                   | Description                                                               |
| --------------------------- | ------------------------------------------------------------------------- |
| **authorizations** `object` | Includes attribute keys that each pair with an array of attribute values. |

### Response

Returns the [intent object](#intent-object-attributes).

{% code overflow="wrap" %}

```json
{
    "id": 1,
    "name": "Fraud detection",
    "description": "This intent allows users in the Analysts group to see internal data.",
    "authorizations": {},
    "deleted": false,
    "createdAt": "2026-05-04T18:48:40.602Z",
    "updatedAt": "2026-05-07T14:43:17.414Z",
    "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}
```

{% endcode %}

## <mark style="color:green;">`DELETE`</mark> `/intent/{id}/groupAssignment`

Remove groups from the intent.

{% code overflow="wrap" %}

```bash
curl -X 'DELETE' \
    'https://www.organization.immuta.com/intent/{id}/groupAssignment' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "groups": [ {"name": "Analysts", "iamid": "bim"} ]
    }'
```

{% endcode %}

### Path parameter

| Parameter        | Description                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **id** `integer` | The unique identifier of the intent. You can retrieve a list of intent IDs using the [`/intents/search` endpoint](#post-intents-search). |

### Body parameters

| Parameter                    | Description                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **groups**.**name** `string` | The group names assigned to the intent.                                                                                                                                                                                                                                                                                                                                |
| **groups.iamid** `string`    | The unique identifier of the identity provider that contains the groups. You can find this ID in the identity provider's configuration section on the app settings page or [through the Immuta API](/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-iams). If you created the group in Immuta, this value is `bim`. |

### Response

Returns group objects that were removed from the intent.

{% code overflow="wrap" %}

```json
{
    "unassignedGroups": [
        {
            "name": "Analysts",
            "iamid": "bim",
            "id": 7
        }
    ],
    "errors": []
}
```

{% endcode %}

#### Response schema

| Attribute                    | Description                                                                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **unassignedGroups** `array` | An array of group objects that were removed from the intent.                                                                          |
| **name** `string`            | The name of the group removed from the intent.                                                                                        |
| **iamid** `string`           | The unique identifier of the identity provider that contains the group that was removed from the intent.                              |
| **id** `integer`             | The unique identifier of the group in Immuta.                                                                                         |
| **errors** `array`           | An array of errors resulting from attempted group assignments. For example, `Group with name Engineers and iamid bim does not exist`. |

## <mark style="color:green;">`POST`</mark> `/intent/{id}/groupAssignment`

Assign groups to an intent.

{% code overflow="wrap" %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/intent/{id}/groupAssignment' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "groups": [ {"name": "Research", "iamid": "bim"} ]
    }'
```

{% endcode %}

### Path parameter

| Parameter        | Description                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **id** `integer` | The unique identifier of the intent. You can retrieve a list of intent IDs using the [`/intents/search` endpoint](#post-intents-search). |

### Body parameters

| Parameter                    | Description                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **groups**.**name** `string` | The group names to assign to the intent.                                                                                                                                                                                                                                                                                                                               |
| **groups.iamid** `string`    | The unique identifier of the identity provider that contains the groups. You can find this ID in the identity provider's configuration section on the app settings page or [through the Immuta API](/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-iams). If you created the group in Immuta, this value is `bim`. |

### Response

Returns a list of groups assigned to the intent.

{% code overflow="wrap" %}

```json
{
    "groups": [
        {
            "name": "Research",
            "iamid": "bim",
            "id": 7
        }
    ],
    "errors": []
}
```

{% endcode %}

#### Response schema

| Attribute          | Description                                                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **groups** `array` | An array of group objects that were assigned to the intent.                                                                           |
| **name** `string`  | The name of the group assigned to the intent.                                                                                         |
| **iamid** `string` | The unique identifier of the identity provider that contains the group that was assigned to the intent.                               |
| **id** `integer`   | The unique identifier of the group in Immuta.                                                                                         |
| **errors** `array` | An array of errors resulting from attempted group assignments. For example, `Group with name Engineers and iamid bim does not exist`. |

## <mark style="color:green;">`POST`</mark> `/intents/search`

Search for intents.

{% code overflow="wrap" %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/intents/search' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "searchText": "Fraud",
    "limit": 2
    }'
```

{% endcode %}

### Body parameters

| Parameter               | Description                                                                                                                                                                                                                                                             | Required or optional | Accepted values                                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **attributes** `object` | Returns intents that contain this attribute.                                                                                                                                                                                                                            | Optional             | -                                                                                                                         |
| **groups** `string`     | Returns intents that contain this group.                                                                                                                                                                                                                                | Optional             | -                                                                                                                         |
| **limit** `integer`     | The number of intents to return.                                                                                                                                                                                                                                        | Optional             | Minimum value is `1`. Maximum value is `100`.                                                                             |
| **offset** `integer`    | The number of items from the beginning of the response to exclude. You can combine the `offset` and `limit` parameters to return a specific set of intents. For example, to return the second and third intent in the response, you would set `offset=1` and `limit=2`. | Optional             | Minimum value is `0`. Maximum value is the total number of intents minus `limit`.                                         |
| **searchText** `string` | The text to search for in intent names. This will return intents with a name that contains this search text.                                                                                                                                                            | Optional             | -                                                                                                                         |
| **sortField** `string`  | Specifies the field to sort the results by.                                                                                                                                                                                                                             | Optional             | <ul><li><code>createdAt</code></li><li><code>id</code></li><li><code>name</code></li><li><code>updatedAt</code></li></ul> |
| **sortOrder** `string`  | Specifies how to sort the results of the request.                                                                                                                                                                                                                       | Optional             | <ul><li><code>asc</code></li><li><code>desc</code></li></ul>                                                              |

### Response

Returns a list of intent objects that match the search criteria.

{% code overflow="wrap" %}

```json
{
  "intents": [
    {
      "id": 1,
      "name": "Fraud detection",
      "createdAt": "2026-05-04T18:48:40.602Z",
      "updatedAt": "2026-05-07T14:18:01.026Z",
      "groupCount": 1,
      "attributeCount": 1
    }
  ],
  "total": 1
}
```

{% endcode %}

#### Response schema

| Attribute                            | Description                                                           |
| ------------------------------------ | --------------------------------------------------------------------- |
| intents.**id** `integer`             | The unique identifier of the intent.                                  |
| intents.**name** `string`            | The name of the intent.                                               |
| intents.**attributeCount** `integer` | The total number of attribute key-value pairs assigned to the intent. |
| intents.**groupCount** `integer`     | The total number of groups assigned to the intent.                    |
| intents.**createdAt** `timestamp`    | The date and time the intent was created.                             |
| intents.**updatedAt** `timestamp`    | The date and time the intent was updated.                             |
| **total** `integer`                  | The total number of intents that match the search criteria.           |

## Intent object attributes

| Attribute                   | Description                                                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **id** `integer`            | The unique identifier of the intent.                                                                                                  |
| **name** `string`           | The name of the intent.                                                                                                               |
| **description** `string`    | The description of the intent that will be displayed for users.                                                                       |
| **authorizations** `object` | The attribute key-value pairs assigned to the intent.                                                                                 |
| **groups.name** `string`    | The group names assigned to the intent.                                                                                               |
| **groups.iamid** `string`   | The unique identifier of the identity provider that contains the groups.                                                              |
| **createdAt** `timestamp`   | The date and time the intent was created.                                                                                             |
| **updatedAt** `timestamp`   | The date and time the intent was updated.                                                                                             |
| **deleted** `boolean`       | Indicates whether the intent has been deleted.                                                                                        |
| **errors** `array`          | An array of errors resulting from attempted group assignments. For example, `Group with name Engineers and iamid bim does not exist`. |


---

# 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://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/manage-intents.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.