# Create a Purpose

## <mark style="color:green;">POST</mark> `/api/v2/purpose`

**Required Immuta permission**: `GOVERNANCE`

{% tabs %}
{% tab title="Basic purpose" %}

```yaml
name: A basic purpose
```

{% endtab %}

{% tab title="Purpose with subpurposes" %}

```yaml
name: Purpose Hierarchy
acknowledgement: The root acknowledgement
subpurposes:
  - name: Purpose Hierarchy.Child 1
    acknowledgement: Override the root acknowledgement
    subpurposes:
      - name: Purpose Hierarchy.Child 1.Grandchild 1
      - name: Purpose Hierarchy.Child 1.Grandchild 2
  - name: Purpose Hierarchy.Child 2
    subpurposes:
      - name: Purpose Hierarchy.Child 2.Grandchild 1
      - name: Purpose Hierarchy.Child 2.Grandchild 2
```

{% endtab %}
{% endtabs %}

## Path parameters

| Parameter                           | Description                                                                                                                    | Default value |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| **dryRun** `boolean`                | If `true`, no updates will actually be made.                                                                                   | `false`       |
| **reAcknowledgeRequired** `boolean` | If `true`, will require all users of any projects using this purpose to re-acknowledge any updated acknowledgement statements. | `false`       |

## Body parameters

The body of the request contains the purpose details. The following attributes are available:

| Attribute                                     | Description                                                                                                                              | Required or optional |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **name** `string`                             | The name of the purpose.                                                                                                                 | Required             |
| **description** `string`                      | A short description for the purpose.                                                                                                     | Optional             |
| **acknowledgement** `string`                  | The acknowledgement that users must agree to when joining a project with this purpose. If not provided, the system default will be used. | Optional             |
| [**subpurposes**](#subpurposes-array) `array` | The subpurposes of the purpose.                                                                                                          | Optional             |

### `subpurposes` array

The `subpurposes` array allows you to define a hierarchy of purposes, where each subpurpose can have its own acknowledgement and can be used to further categorize data usage. Each subpurpose can itself have a `subpurposes` array, allowing for nested hierarchies.

| Attribute                    | Description                                                                                                                                 | Required or optional |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **name** `string`            | The name of the subpurpose.                                                                                                                 | Required             |
| **acknowledgement** `string` | The acknowledgement that users must agree to when joining a project with this subpurpose. If not provided, the system default will be used. | Optional             |
| **subpurposes** `array`      | Nested subpurposes.                                                                                                                         | Optional             |


---

# Agent Instructions: 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:

```
GET https://documentation.immuta.com/latest/developer-guides/api-intro/immuta-v2-api/purposes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.