# Create a Project

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

**Required Immuta permission**: `CREATE_PROJECT`

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

```yaml
name: A Bare Bones Project
projectKey: simplest possible project
```

{% endtab %}

{% tab title="Anyone project" %}
This project will be created with an **Anyone** subscription policy, where anyone can request and will automatically be granted access.

```yaml
name: Anyone Project
projectKey: Anyone project
documentation: "# Anyone Can See This"
description: "Anyone can join this project"
allowMaskedJoins: false
subscriptionPolicy:
    type: anyone
    automaticSubscription: true
    description: "Auto-subscribe everyone"
tags:
  - Discovered.Person Name
purposes:
  - Use Purposes
  - Purpose Hierarchy.Child 2.Grandchild 2
```

{% endtab %}

{% tab title="Approval required project" %}
This project will be created with an **Anyone who asks (and is approved)** subscription policy, where anyone can request access and they will get access when their request is approved.

```yaml
name: Approval Project
projectKey: Approval project
description: "Need approval to join this project"
allowMaskedJoins: true
subscriptionPolicy:
    type: approval
    approvals:
      - requiredPermission: GOVERNANCE
        specificApproverRequired: true
      - requiredPermission: ADMIN
        specificApproverRequired: false
```

{% endtab %}

{% tab title="Attribute-based access project" %}
This project will be created with an **Users with specific groups or attributes** subscription policy, where users with a specific attribute or in a specific group will automatically be granted access.

```yaml
name: Entitlement Project
projectKey: entitlement project
description: "Need specific entitlements to join this project"
subscriptionPolicy:
    type: entitlements
    automaticSubscription: false
    allowDiscovery: true
    entitlements:
      operator: any
      groups:
        - Engineers
        - Founders
      attributes:
        - name: Auth1
          value: super secret
```

{% endtab %}
{% endtabs %}

<details>

<summary>Projects with workspaces examples</summary>

**Project with Databricks Spark workspace**

```yaml
name: Databricks Spark Project
projectKey: databricks spark project
datasources:
  - Crime Data
  - Databricks Credit Card Transactions
  - Databricks Hipaa Data
purposes:
  - Use Purposes
workspace:
  type: databricks
  config:
    database: native
    directory: native
    workspaceConfigurationName: S3
```

**Project with Snowflake workspace**

```yaml
name: Snowflake Project
projectKey: snowflake project
datasources:
  - Snowflake Case
  - Snowflake Customer
  - Snowflake Web Sales
workspace:
  type: snowflake
  config:
    schema:
      SNOWFLAKE_NATIVE
    warehouses:
      - DEMO_WH
tags:
  - Discovered.Passport
```

</details>

## Path parameters

| Parameter                                        | Description                                                                                                             | Default value |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------- |
| **dryRun** `boolean`                             | If `true`, no updates will actually be made.                                                                            | `false`       |
| **deleteDataSourcesOnWorkspaceDelete** `boolean` | If `true`, will delete all data and the data sources associated with a project workspace when the workspace is deleted. | `false`       |

## Body parameters

| Attribute                                                     | Description                                                                                                                    | Required or optional | Default values                                           | Accepted values                                                |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
| **projectKey** `string`                                       | A key to uniquely identify this project for future API calls.                                                                  | Required             | -                                                        | -                                                              |
| **name** `string`                                             | The name of the project.                                                                                                       | Required             | -                                                        | -                                                              |
| **description** `string`                                      | A short description for the project.                                                                                           | Optional             | -                                                        | -                                                              |
| **documentation** `string`                                    | Markdown-supported documentation for this project.                                                                             | Optional             | -                                                        | -                                                              |
| **allowedMaskedJoins** `boolean`                              | If `true`, will allow joining on masked columns between data sources in this project. Only certain policies allow masked join. | Optional             | `false`                                                  | <ul><li><code>true</code></li><li><code>false</code></li></ul> |
| **purposes** `string[]`                                       | The list of purposes to add to this project.                                                                                   | Optional             | -                                                        | -                                                              |
| **datasources** `string[]`                                    | The list of data sources to add to this project.                                                                               | Optional             | -                                                        | -                                                              |
| [**subscriptionPolicy**](#subscriptionpolicy-object) `object` | The policy that determines which users can subscribe to the project.                                                           | Optional             | Defaults to manual subscription if the object is omitted | -                                                              |
| [**workspace**](#workspace-object) `object`                   | If this is a workspace project, this is the workspace configuration. The project will automatically be equalized.              | Optional             | -                                                        | -                                                              |
| **equalization** `boolean`                                    | If `true`, will normalize all users to the same entitlements so that everyone sees the same data.                              | Optional             | `false`                                                  | <ul><li><code>true</code></li><li><code>false</code></li></ul> |
| **tags** `array[]`                                            | Tags to add to the project.                                                                                                    | Optional             | -                                                        | -                                                              |

### `subscriptionPolicy` object

The `subscriptionPolicy` object allows you to define the policy for how users can subscribe to the project.

| Attribute                                         | Description                                                                                                             | Required or optional                   | Default values | Accepted values                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type** `string`                                 | The type of subscription policy the project will have.                                                                  | Required                               | -              | <ul><li><code>anyone</code>: Anyone can subscribe</li><li><code>approval</code>: Anyone can request approval and will be subscribed when it is approved</li><li><code>entitlements</code>: Users with the listed attributes or groups will be subscribed</li><li><code>manual</code>: Users must be manually added to be subscribed</li></ul> |
| **automaticSubscription** `boolean`               | If `true`, users will be automatically subscribed if they meet the policy requirements without any manual intervention. | Optional                               | `false`        | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                                                                                                                                                                                                                                                                |
| **description** `string`                          | A description of the policy.                                                                                            | Optional                               | -              | -                                                                                                                                                                                                                                                                                                                                             |
| [**approvals**](#approvals-array) `array[object]` | Details about the user that will approve subscription requests.                                                         | Required if **type** is `approval`     | -              | -                                                                                                                                                                                                                                                                                                                                             |
| [**entitlements**](#entitlements-object) `object` | Details about the entitlements required for users to subscribe to the project.                                          | Required if **type** is `entitlements` | -              | -                                                                                                                                                                                                                                                                                                                                             |

#### `approvals` array

This array is required if the policy **type** is `approval` in the [**subscriptionPolicy** object](#subscriptionpolicy-object). It allows you to define the users who can approve subscription requests.

| Attribute                              | Description                                                                                                                                                           | Required or optional               | Default values | Accepted values                                                                                       |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| **specificApproverRequired** `boolean` | If `true`, the user to approve the request will be selected by the user requesting access. If `false`, any user with the required permission can approve the request. | Required if **type** is `approval` | -              | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                        |
| **requiredPermission** `string`        | The required permissions for the user approving the subscription request.                                                                                             | Required if **type** is `approval` | -              | <ul><li><code>USER\_ADMIN</code></li><li><code>GOVERNANCE</code></li><li><code>AUDIT</code></li></ul> |

#### `entitlements` object

This object is required if the policy **type** is `entitlements` in the [**subscriptionPolicy** object](#subscriptionpolicy-object). It allows you to define the groups or attributes that users must have to subscribe to the project.

| Attribute                     | Description                                                                                                             | Required or optional                         | Default values | Accepted values                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------- | ----------------------------------------------------------- |
| **operator** `string`         | Specify whether `all` of the circumstances must be met for the user to be subscribed (AND), or just `any` of them (OR). | Required if **type** is `entitlements`       | -              | <ul><li><code>all</code></li><li><code>any</code></li></ul> |
| **groups** `string`           | The name of the group the user must be a member of to subscribe to the project.                                         | Requires either **groups** or **attributes** | -              | -                                                           |
| **attributes** `object`       | Details about attributes the user must have to subscribe to the project.                                                | Requires either **groups** or **attributes** | -              | -                                                           |
| attributes.**name** `string`  | The name of the attribute the user must have to subscribe to the project. This is commonly referred to as a key.        | Required if using **attributes**             | -              | -                                                           |
| attributes.**value** `string` | The value of the attribute the user must have to subscribe to the project.                                              | Required if using **attributes**             | -              | -                                                           |

### `workspace` object

| Attribute                                      | Description                                                                                                                    | Required or optional                   | Default values | Accepted values                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | -------------- | ------------------------------------------------------------------------ |
| **type** `string`                              | The technology the workspace is in.                                                                                            | Required                               | -              | <ul><li><code>snowflake</code></li><li><code>databricks</code></li></ul> |
| **config** `object`                            | Details about the workspace configuration.                                                                                     | Required                               | -              | -                                                                        |
| config.**schema** `string`                     | Your project workspace will exist within this schema in Snowflake under the database configured by the application admin.      | Required when **type** is `snowflake`  | -              |                                                                          |
| config.**warehouses** `array`                  | These are the Snowflake warehouses that will be available to project members when they are working in the Snowflake workspace. | Required when **type** is `snowflake`  | -              |                                                                          |
| config.**database** `string`                   | The Databricks database the workspace will be in.                                                                              | Required when **type** is `databricks` | -              |                                                                          |
| config.**directory** `string`                  | The Databricks directory the workspace will be in.                                                                             | Required when **type** is `databricks` | -              |                                                                          |
| config.**workspaceConfigurationName** `string` | The Databricks workspace configuration name.                                                                                   | Required when **type** is `databricks` | -              |                                                                          |


---

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