Manage Projects

This page details how to use the projects API to query projects and the data sources associated with them in Immuta.

Projects workflow

1. Create a project.

2. Search for Immuta projects.

3. Manage your Immuta projects.

4. Manage project members.

5. Manage project data sources.

6. Manage project comments

7. Use projects.

8. Delete projects.

Create a project

POST /project

Create the project.

Payload parameters

Attribute	Description	Required
id	integer Project ID.	Yes
projectKey	string Name of the project.	Yes
name	string Name of the project.	Yes
status	string (Accepted statuses are open or closed.)	Yes
description	string Project description.	No
documentation	string Project documentation.	No
tags	array Project tags.	No
purposes	array Project purposes.	No
stagedPurposes	array Project purposes staged for approval.	No
deleted	boolean If true, the project will be deleted.	No
snowflake	array This enables a Snowflake workspace for the project and details the schema, hostname, and warehouse.	No
allowMaskedJoins	boolean If true, masked joins will be allowed.	No
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription. If this is not set, it will be the default manual.	No
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).	No
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.	No
workspace	array Information on native workspaces in the project.	No
type	string The type of Immuta project, either user created project (user) or system generated project (schema).	No
createdAt	timestamp Date of the project creation.	No
updatedAt	timestamp Date of the most recent update.	No

Response parameters

Attribute	Description
id	integer Project ID.
projectKey	string Name of the project.
name	string Name of the project.
status	string (Statuses are open or closed.)
description	string Project description.
documentation	string Project documentation.
tags	array Project tags.
purposes	array Project purposes.
stagedPurposes	array Project purposes staged for approval.
deleted	boolean If true, the project has been deleted.
snowflake	array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.
allowMaskedJoins	boolean If true, masked joins are allowed.
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.
workspace	array Information on native workspaces in the project.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
createdAt	timestamp Date of the project creation.
updatedAt	timestamp Date of the most recent update.
workspaceWarnings	string This message describes issues with the created workspace.

Example request

This example request with the payload below will create a new project.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/project

Example request payload

This example payload will create a new project named API Project.

{
  "id": 4,
  "projectKey": "api project",
  "name": "API Project",
  "status": "open",
  "description": "project created with api",
  "deleted": false,
  "allowMaskedJoins": false,
  "createdAt": "2021-09-10",
  "updatedAt": "2021-09-10"
}

Example response

{
  "id": 4,
  "projectKey": "api project",
  "name": "API Project",
  "status": "open",
  "description": "project created with api",
  "documentation": "# API Project",
  "deleted": false,
  "allowMaskedJoins": false,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "workspace": null,
  "snowflake": null,
  "type": null,
  "schema": null,
  "createdBy": 2,
  "updatedBy": 2,
  "createdAt": "2021-09-10T00:00:00.000Z",
  "updatedAt": "2021-09-10T00:00:00.000Z",
  "schemaEvolutionId": null,
  "purposes": [],
  "stagedPurposes": []
}

Search projects

Method	Path	Purpose
GET	/project
GET	/project/{projectId}

Search all projects

GET /project

Search for projects.

Query parameters

Attribute	Description	Required
offset	integer Used in combination with size to fetch pages. The default is 0.	No
size	integer The number of results to return per page.	No
sortField	string Used to sort results by field.	No
sortOrder	string Sorts results by order, which must be asc or desc. The default is asc.	No
subscription	array[string] Filters projects by subscription types, which must be automatic, approval, or policy.	No
status	array[string] Filters projects based on their status: open or closed.	No
searchText	string Searches text. By default this will filter projects by name, description, documentation, category, and organization.	No
tag	array[string] Filters projects by tags associated with the projects.	No
nameOnly	boolean If true, searchText will only filter by project name, allowing you to retrieve specific projects. The default is false.	No
isEqualized	boolean If true, only equalized projects will be included.	No
snowflake	boolean If true, only projects with a Snowflake workspace will be included.	No
dataSourceId	integer Filters projects by whether they have the data source associated with the data source ID.	No
mode	integer Specifies the query mode, which must be 0 (FULL), 1 (COUNT), 4 (TAG), 5 (MIN_MAX), or 6 (STATUS).	No

Response parameters

Attribute	Description
count	integer Number of projects found.
hits	array Details about each project listed.
id	integer The project ID.
projectKey	string Name of the project.
name	string Name of the project.
status	string Statuses are open or closed.
description	string Project description.
documentation	string Project documentation.
tags	array Project tags.
purposes	array Project purposes.
stagedPurposes	array Project purposes staged for approval.
deleted	boolean If true, the project has been deleted.
snowflake	array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.
allowMaskedJoins	boolean If true, masked joins are allowed.
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.
workspace	array Information on native workspaces in the project.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
createdAt	timestamp Date of the project creation.
updatedAt	timestamp Date of the most recent update.
acknowledgeRequired	boolean When true, the requesting user has not yet agreed to the project acknowledgement.
subscriptionId	integer The project member's subscription ID.
subscribedAsUser	boolean If true, the user running the request is currently subscribed.
subscriptionStatus	string Subscription status of the user running the request.
filterId	integer Corresponds with the ID of the project.
facets	array Facets (categories) relevant to the search.

Request example

This example request gets a list of all of the projects.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/project

Response example

{
  "hits": [
    {
      "id": 8,
      "name": "Improving Employee Onboarding and Retention",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-14T23:14:46.210Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-07-14T23:13:53.752Z",
      "filterId": 8,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "not_subscribed",
      "purposeCount": 1,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 4,
      "name": "Medical Records",
      "status": "open",
      "description": "This project contains all data sources under the schema, medical_records, from [e-mail]:1433/example.",
      "deleted": false,
      "updatedAt": "2021-06-22T23:24:58.766Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-06-22T23:24:58.766Z",
      "filterId": 4,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 0,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": "Schema",
      "allowMaskedJoins": false
    },
    {
      "id": 6,
      "name": "sample123",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-12T21:32:37.020Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-07-12T21:32:37.012Z",
      "filterId": 6,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "not_subscribed",
      "purposeCount": 1,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 2,
      "name": "test",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-19T20:48:00.758Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-05-19T22:50:44.190Z",
      "filterId": 2,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 2,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 3,
      "name": "Tpc",
      "status": "open",
      "description": "This project contains all data sources under the schema, tpc, from [e-mail]:1433/example.",
      "deleted": false,
      "updatedAt": "2021-05-20T16:29:09.679Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-05-20T16:29:09.679Z",
      "filterId": 3,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 0,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": "Schema",
      "allowMaskedJoins": false
    }
  ],
  "facets": {},
  "count": 5
}

Search for projects by ID

GET /project/{projectId}

Get the project with the given ID.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
checkForSqlAccount	boolean Default is true.	No

Response parameters

Attribute	Description
id	integer Project ID.
projectKey	string Name of the project.
name	string Name of the project.
status	string Statuses are open or closed.
description	string Project description.
documentation	string Project documentation.
tags	array Project tags.
purposes	array Project purposes.
stagedPurposes	array Project purposes staged for approval.
deleted	boolean If true, the project has been deleted.
snowflake	array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.
allowMaskedJoins	boolean If true, masked joins are allowed.
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.
workspace	array Information on native workspaces in the project.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
createdAt	timestamp Date of the project creation.
updatedAt	timestamp Date of the most recent update.
acknowledgeRequired	boolean When true, the requesting user has not yet agreed to the project acknowledgement.
subscriptionId	integer The project member's subscription ID.
subscribedAsUser	boolean If true, the user running the request is currently subscribed.
subscriptionStatus	string Subscription status of the user running the request.

Example request

This example gets the project object for the project with the ID 2.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/project/2

Example response

{
  "id": 2,
  "projectKey": "test",
  "name": "test",
  "status": "open",
  "description": null,
  "documentation": "# test\n\n12345",
  "deleted": true,
  "allowMaskedJoins": true,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "workspace": null,
  "snowflake": null,
  "type": null,
  "schema": null,
  "createdBy": 2,
  "updatedBy": 2,
  "createdAt": "2021-05-19T22:50:44.190Z",
  "updatedAt": "2021-07-29T18:30:04.066Z",
  "schemaEvolutionId": null,
  "subscribedAsUser": true,
  "subscriptionId": 5,
  "acknowledgeRequired": false,
  "subscriptionStatus": "owner",
  "requestedState": "owner",
  "approved": true,
  "subscriptionExpiration": null,
  "filterId": 2,
  "purposeCount": null,
  "purposes": [
    {
      "id": 8,
      "name": "Analyzing Onboarding and Job Satisfaction",
      "acknowledgement": null,
      "description": "Data can only be accessed for analyzing the effectiveness of current onboarding practices and trends in employee job satisfaction  reasons for data access must be approved by a compliance committee.",
      "addedByProfile": 2,
      "displayAcknowledgement": true,
      "deleted": false,
      "systemGenerated": false,
      "policyMetadata": null,
      "createdAt": "2021-07-07T19:56:06.360Z",
      "updatedAt": "2021-07-07T19:56:06.360Z",
      "createdBy": 2
    },
    {
      "id": 4,
      "name": "Use Case Outside De-identification",
      "acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. In the event that I discover risks that I believe could lead to unauthorized access, I agree to immediately notify the project owner or governance team and take immediate action t  address and mitigate such risks.",
      "description": null,
      "addedByProfile": 1,
      "displayAcknowledgement": true,
      "deleted": false,
      "systemGenerated": true,
      "policyMetadata": null,
      "createdAt": "2021-05-19T20:32:03.437Z",
      "updatedAt": "2021-07-28T14:17:22.690Z",
      "createdBy": 2
    }
  ],
  "stagedPurposes": [],
  "tags": []
}

Manage projects

Method	Path	Purpose
PUT	/project/{projectId}
GET	/project/{projectId}/activity
GET	/project/{projectId}/checkEqualizationState

Update project by ID

PUT /project/{projectId}

Update the project with the given ID.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
deleteDataSources	boolean If true, the data sources in the project will be deleted.	No

Payload parameters

Attribute	Description	Required
type	string The type of Immuta project, either user created project (user) or system generated project (schema).	No
name	string The project's new name.	No
description	string The project's new description.	No
documentation	string The project's new documentation.	No
status	string Accepted statuses are open or closed.	No
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).	No
tags	array The project's new tags.	No
purposes	array The project's new purposes.	No
stagedPurposes	array The project's new purposes staged for approval.	No
deleted	boolean If true, the project will be deleted.	No
snowflake	array This enables a Snowflake workspace for the project and details the schema, hostname, and warehouse.	No
allowMaskedJoins	boolean If true, masked joins will be allowed.	No
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription. If this is not set, it will be the default manual.	No
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.	No
workspace	array Information on native workspaces in the project.	No

Response parameters

Attribute	Description
id	integer Project ID.
projectKey	string Name of the project.
name	string Name of the project.
status	string Statuses are open or closed.
description	string Project description.
documentation	string Project documentation.
tags	array Project tags.
purposes	array Project purposes.
stagedPurposes	array Project purposes staged for approval.
deleted	boolean If true, the project will be deleted.
snowflake	array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.
allowMaskedJoins	boolean If true, masked joins will be allowed.
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.
workspace	array Information on native workspaces in the project.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
createdAt	timestamp Date of the project creation.
updatedAt	timestamp Date of the most recent update.
workspaceWarnings	string This message describes issues with the created workspace.

Example request

This example request with the payload below will update the project with the project ID 2.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/2

Example request payload

This example payload will update the project to be named Documentation Project.

{
  "name": "Documentation Project",
  "deleted": false
}

Example response

{
  "workspace"