2024.1
Search powered by AI

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

Response parameters

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

Search all projects

GET /project

Search for projects.

Query parameters

Response parameters

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

Response parameters

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

Update project by ID

PUT /project/{projectId}

Update the project with the given ID.

Query parameters

Payload parameters

Response parameters

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

Response parameters

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

Response parameters

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

View project members

GET /project/{projectId}/members

Get all of the members for a given project.

Query parameters

Response parameters

Example request

This request gets all of the members 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/members

Example response

{
  "count": 1,
  "members": [
    {
      "profile": 2,
      "name": "John Doe",
      "iamid": "bim",
      "userid": "john.doe@immuta.com",
      "email": "john.doe@immuta.com",
      "type": "user",
      "approved": true,
      "state": "owner",
      "systemGenerated": false,
      "lastExternalRefresh": "2021-07-30T17:49:55.050Z",
      "subscriptionId": 5,
      "createdAt": "2021-05-19T22:50:44.206Z",
      "updatedAt": "2021-07-19T20:47:53.069Z",
      "approvals": [],
      "currentUserCanApprove": false
    }
  ]
}

Check the members' equalized entitlements

POST /project/{projectId}/checkEqualizedAuths

Check that all members meet the provided equalized entitlements.

Query parameters

Payload parameters

Response parameters

Request example

This request with the payload below will check if the requesting user is in the "View Masked Values" group.

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

Payload example

{
  "conditionsObj": {
    "operator": "and",
    "conditions": [
      {
        "type": "groups",
        "group": {
          "id": 1,
          "name": "View Masked Values"
        }
      }
    ]
  }
}

Response example

{
  "validSet": true,
  "usersMissingAuths": {}
}

Add a member to a project

POST /project/{projectId}/members

Add a member to the project.

Query parameters

Payload parameters

Example request

This example request with the payload below will add a new member to the project with the project ID 1.

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

Example request payload

{
  "profileId": 3,
  "state": "subscribed",
}

Example response

{
  "subscriptionId": 18,
  "state": "subscribed",
  "approved": true
}

Update a project member

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

Update a member of the project.

Query parameters

Payload parameters

Response parameters

Request example

This example request with the payload below will update the user with the subscription ID 2 to be a subscriber of the project with the project ID 3.

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

Payload example

{
  "state": "subscribed"
}

Response example

{
  "state": "subscribed",
  "expiration": null
}

Manage project data sources

View project data sources by project ID

GET project/{projectId}/dataSources

Get all of the data sources for a given project.

Query parameters

Response parameters

Example request

This example gets the data source details for all of the data sources 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/dataSources

Example response

{
  "count": 3,
  "dataSources": [
    {
      "addedBy": "John Doe",
      "dataSourceName": "Fake Medical Claims 2017",
      "policyHandlerType": "Builder",
      "addedOn": "2021-06-25T19:11:03.230Z",
      "dataSourceId": 8,
      "addedByProfile": 2,
      "deleted": false,
      "subscriptionType": "policy",
      "subscriptionStatus": "owner",
      "subscriptionPolicy": {
        "type": "subscription",
        "exceptions": {
          "operator": "or",
          "conditions": [
            {
              "type": "groups",
              "group": {
                "name": "HR Department"
              }
            },
            {
              "type": "authorizations",
              "authorization": {
                "auth": "Manager",
                "value": "Receiving Surveys"
              }
            }
          ]
        },
        "shareResponsibility": false,
        "automaticSubscription": true
      },
      "connectionString": "immuta@example.database.sample.net:1433/example",
      "blobHandlerType": "Snowflake",
      "derivedInThisProject": false
    },
    {
      "addedBy": "John Doe",
      "dataSourceName": "Tpc Randomized",
      "policyHandlerType": "Builder",
      "addedOn": "2021-06-25T22:26:38.170Z",
      "dataSourceId": 6,
      "addedByProfile": 2,
      "deleted": false,
      "subscriptionType": "policy",
      "subscriptionStatus": "owner",
      "subscriptionPolicy": {
        "type": "subscription",
        "exceptions": {
          "operator": "and",
          "conditions": [
            {
              "type": "groups",
              "group": {
                "name": "HR"
              }
            }
          ]
        },
        "shareResponsibility": false,
        "automaticSubscription": true
      },
      "connectionString": "immuta@example.database.sample.net:1433/example",
      "blobHandlerType": "Azure Synapse Analytics",
      "derivedInThisProject": false
    },
    {