2024.3
Search powered by AI

Manage Projects

Projects API reference guide

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. Use projects.

  7. Delete projects.

Create a project

POST /project

Create the project.

Payload parameters

AttributeDescriptionRequired

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

AttributeDescription

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

MethodPathPurpose

GET

/project

Search for projects.

GET

/project/{projectId}

Get the project with the given ID.

Search all projects

GET /project

Search for projects.

Query parameters

AttributeDescriptionRequired

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

AttributeDescription

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 immuta@example.database.sample.net: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 immuta@example.database.sample.net: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

AttributeDescriptionRequired

projectId

integer The project ID.

Yes

checkForSqlAccount

boolean Default is true.

No

Response parameters

AttributeDescription

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

MethodPathPurpose

PUT

/project/{projectId}

Update the project with the given ID.

GET

/project/{projectId}/activity

Get all of the recent activity for a given project.

GET

/project/{projectId}/checkEqualizationState

Get current state of an equalized project.

Update project by ID

PUT /project/{projectId}

Update the project with the given ID.

Query parameters

AttributeDescriptionRequired

projectId

integer The project ID.

Yes

deleteDataSources

boolean If true, the data sources in the project will be deleted.

No

Payload parameters

AttributeDescriptionRequired

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

AttributeDescription

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": null,
  "createdBy": 2,
  "updatedBy": 2,
  "schemaEvolutionId": 1,
  "projectKey": "Medical Records",
  "name": "Documentation Project",
  "status": "open",
  "description": "This project contains all data sources under the schema, medical_records, from immuta@example.database.sample.net:1433/example.",
  "documentation": "This is an automatically generated project that collects data sources under the schema, medical_records, from immuta@example.database.sample.net:1433/example. When data sources in this schema are added to the system, they will automatically be added to this project.",
  "deleted": false,
  "allowMaskedJoins": false,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "snowflake": null,
  "type": "Schema",
  "schema": "medical_records",
  "id": 2,
  "createdAt": "2021-08-24T15:44:29.477Z",
  "updatedAt": "2021-09-10T21:49:00.678Z",
  "purposeCount": 0,
  "tags": [],
  "projectPurposes": [],
  "stagedPurposes": [],
  "purposes": [],
  "workspaceWarnings": []
}

View project activity by project ID

GET /project/{projectId}/activity

Get all of the recent activity for a given project.

Query parameters

AttributeDescriptionRequired

projectId

integer The project ID.

Yes

offset

integer Used in combination with size to fetch pages.

No

size

integer Used to select the number of activities.

No

Response parameters

AttributeDescription

count

integer The total number of actions.

activities

array The id, modelType, modelId, notificationType, actionsBy, targetUser, targetGroup, additionalText, array, createdAt, updatedAt, and read for each action listed.

id

integer The activity ID.

modelType

string The Immuta feature the activity is attached to.

modelId

string The ID of the Immuta feature the activity is attached to.

notificationType

string The type of activity or notification, such as modelCreated, modelUserAdded, or projectUpdated.

actionBy

array The user data for the user who took the action.

targetUser

array The user data for the user who the action was directed towards.

targetGroup

array The group data for the group who the action was directed towards.

metadata

array Details about the action. For example, if the notificationType was modelCreated, the metadata attribute would include the project name.

createdAt

timestamp Date the action was taken.

updatedAt

timestamp Date of the most recent activity on the action.

read

boolean If true, the activity has been viewed.

unread

integer The number of unviewed activities on that project.

Example request

This example gets one activity for the project with the project ID 2.

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

Example response

{
  "count": 40,
  "activities": [
    {
      "modelType": "project",
      "modelId": "2",
      "createdAt": "2021-07-29T20:56:11.856Z",
      "notificationType": "projectUpdated",
      "metadata": {
        "fields": [
          "deleted",
          "purposes"
        ],
        "projectName": "test",
        "approvedPurposeCount": 0,
        "deniedPurposesCount": 0,
        "requestedPurposeCount": 0,
        "newPurposesAddedCount": 2
      },
      "read": false,
      "id": 191,
      "updatedAt": "2021-07-29T20:56:11.856Z",
      "actionBy": {
        "id": 2,
        "name": "John Doe",
        "email": "john.doe@immuta.com"
      },
      "targetUser": {
        "id": 2,
        "name": "John Doe",
        "email": "john.doe@immuta.com"
      }
    }
  ],
  "unread": 40,
  "next": "191_2021-07-29T20:56:11.856Z"
}

View the state of an equalized project

GET /project/{projectId}/checkEqualizationState

Get current state of an equalized project.

Query parameters

AttributeDescriptionRequired

projectId

integer The project ID.

Yes

Response parameters

AttributeDescription

equalizationState

string The state of the project's equalization. Options include: off, recommended, active, upgrade, or nonCompliantMembers.

Example request

This example gets the state of project equalization of the project with the project ID 2.

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

Example response

{
  "equalizationState": "recommended"
}

Manage project members

MethodPathPurpose

GET

/project/{projectId}/members

Get all of the members for a given project.

POST

/project/{projectId}/checkEqualizedAuths

Check that all members meet the provided equalized entitlements.

POST

/project/{projectId}/members

Add a member to the project.

PUT

/project/{projectId}/members/{subscriptionId}

Update a member of the project.

View project members

GET /project/{projectId}/members

Get all of the members for a given project.

Query parameters

AttributeDescriptionRequired

projectId

integer The project ID.

Yes

offset

integer Used in combination with size to fetch pages.

No

size

integer The number of results to return per page.

No

sortField

string Sorts results by field. The default is name.

No

sortOrder

string Sorts results by order, which must be asc or desc. The default is asc.

No

searchText