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.
POST /project
Create the project.
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
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.
This example request with the payload below will create a new project.
This example payload will create a new project named API Project.
GET
/project
GET
/project/{projectId}
GET /project
Search for projects.
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
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.
This example request gets a list of all of the projects.
GET /project/{projectId}
Get the project with the given ID.
projectId
integer The project ID.
Yes
checkForSqlAccount
boolean Default is true.
No
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.
This example gets the project object for the project with the ID 2.
PUT
/project/{projectId}
GET
/project/{projectId}/activity
GET
/project/{projectId}/checkEqualizationState
PUT /project/{projectId}
Update the project with the given ID.
projectId
integer The project ID.
Yes
deleteDataSources
boolean If true, the data sources in the project will be deleted.
No
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
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.
This example request with the payload below will update the project with the project ID 2.
Example request payload
This example payload will update the project to be named Documentation Project.
GET /project/{projectId}/activity
Get all of the recent activity for a given project.
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
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.
This example gets one activity for the project with the project ID 2.
GET /project/{projectId}/checkEqualizationState
Get current state of an equalized project.
projectId
integer The project ID.
Yes
equalizationState
string The state of the project's equalization. Options include: off, recommended, active, upgrade, or nonCompliantMembers.
This example gets the state of project equalization of the project with the project ID 2.
GET
/project/{projectId}/members
POST
/project/{projectId}/checkEqualizedAuths
POST
/project/{projectId}/members
PUT
/project/{projectId}/members/{subscriptionId}
GET /project/{projectId}/members
Get all of the members for a given project.
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
string Searches text of member names.
No
approved
boolean Filters results based on whether or not members' subscription status has been approved.
No
checkDataSources
boolean When true, will check if users' meet the compliance requirements set on data sources within the project.
No
expandGroups
boolean
No
count
integer The number of members in the project.
members
array The profile, name, iamId, userId, email, type, approved, state, systemGenerated, lastExternalRefresh, subscriptionId, createdAt, updatedAt, approvals, currentUserCanApprove, and compliance for each member result.
profile
integer The user's profile ID.
name
string The user's name.
iamId
string The ID of the IAM, which is configured on the App Settings page.
userId
string The user's Immuta username.
string The user's email.
type
string The type of Immuta project, either user created project (user) or system generated project (schema).
approved
boolean When true, the members' subscription status has been approved.
state
string The user's relationship to the project. Options include owner, not_subscribed, pending, subscribed, and expert.
systemGenerated
boolean When true, the user is a system generated account.
lastExternalRefresh
timestamp The date of the last time this user's information was updated from an external IAM.
subscriptionId
integer The project member's subscription ID.
createdAt
timestamp The date that this user was created in Immuta.
updatedAt
timestamp The date of the most recent update of the user.
approvals
array Details on how this new member will fit into the project's approval process.
compliance
array Details about the compliance requirements of the project, including missingDataSources and invalidSubscriptions.
This request gets all of the members of the project with the project ID 2.
POST /project/{projectId}/checkEqualizedAuths
Check that all members meet the provided equalized entitlements.
projectId
integer The project ID.
Yes
conditionsObj
array Details containing operator, conditions, type, group, and field values.
Yes
operator
string
Yes
conditions
array Details containing type, group, and field.
Yes
type
string The type of Immuta project, either user created project (user) or system generated project (schema).
No
group
array Includes the group id, name, and iam.
No
validSet
boolean When true, users meet the specified entitlements.
usersMissingAuths
array Metadata about the user (name and subscription id) and the name of the group they're missing.
This request with the payload below will check if the requesting user is in the "View Masked Values" group.
Payload example
POST /project/{projectId}/members
Add a member to the project.
projectId
integer The project ID.
Yes
profileId
integer The new user's ID.
Yes
groupId
integer The group ID that the new user is a part of. This will add a whole group.
No
state
string The new user's connection to the project. Options include owner, not_subscribed, pending, subscribed, and expert.
No
expiration
timestamp The date when the member should no longer have access to the project.
No
approvals
array Details on how this new member will fit into the project's approval process.
No
This example request with the payload below will add a new member to the project with the project ID 1.
Example request payload
PUT /project/{projectId}/members/{subscriptionId}
Update a member of the project.
projectId
integer The project ID.
Yes
subscriptionId
integer The project member's subscription ID.
Yes
state
array[string] The user's role in the project. Options include owner, not_subscribed, pending, subscribed, and expert.
Yes
expiration
timestamp The date when the member should no longer have access to the project.
No
state
array[string] The user's role in the project. Options include owner, not_subscribed, pending, subscribed, and expert.
expiration
timestamp The date when the member should no longer have access to the project.
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.
Payload example
GET
/project/{projectId}/dataSources
DELETE
/project/{projectId}/dataSources
POST
/project/{projectId}/dataSources
PUT
/project/{projectId}/dataSources/{dataSourceId}
GET project/{projectId}/dataSources
Get all of the data sources for a given project.
projectId
integer The project ID.
Yes
offset
integer Used in combination with size to fetch pages.
No
searchText
string Searches text of the data source names.
No
size
integer The number of results to return per page.
No
sortField
string Used to sort results by field. Options include addedBy, addedOn, and dataSourceName. The default is dataSourceName.
No
sortOrder
string Sorts results by order, which must be asc or desc. The default is asc.
No
unsubscribed
boolean If true, filters by unsubscribed status (includes data sources with a pending subscription). If false, filters by subscribed status.
No
subscription
string Searches based on the subscription status of the user. Options include not_subscribed, owner, pending, or subscribed.
No
count
integer The total number of data sources in the project.
dataSources
array[object] An array of data source objects that includes addedBy, dataSourceName, policyHandlerType, addedOn, dataSourceId, addedByProfile, deleted, subscriptionType, subscriptionStatus, subscriptionPolicy, connectionString, blobHandlerType, and derivedThisProject values for each data source.
addedBy
string The user who added the data source to the project.
dataSourceName
string The name of the data source.
policyHandlerType
string
addedOn
timestamp The date the data source was added to the project.
dataSourceId
integer The data source ID.
addedByProfile
integer The profile ID of the user who added the data source to the project.
deleted
boolean If true, the data source has been deleted.
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).
subscriptionStatus
string
subscriptionPolicy
array[object] A policy object for the Subscription Policy on the data source. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
connectionString
string The data source connection string.
blobHandlerType
string The data platform.
derivedInThisProject
boolean If true, this data source was created as a derived data source in this project.
This example gets the data source details for all of the data sources of the project with the project ID 2.
DELETE /project/{projectId}/dataSources
Remove supplied data sources from the project.
projectId
integer The project ID.
Yes
ids
integer The IDs of the data sources to remove from the project.
Yes
success
array The id, blobHandlerType, and name values of the data sources that have been successfully removed.
inError
array The id, blobHandlerType, and name values of the data sources that have not been successfully removed.
id
integer The data source ID.
blobHandlerType
string The type of blob handler of the data source.
name
string The data source name.
This example request deletes the data source with the ID 8 from the project with the project ID 2.
POST /project/{projectId}/dataSources
Adds data sources to a project.
projectId
integer The project ID.
Yes
dataSourceIds
integer The data source IDs for the data sources to add to the project.
Yes
success
array The id, blobHandlerType, and name values of the data sources that have been successfully added.
inError
array The id, blobHandlerType, and name values of the data sources that have not been successfully added.
id
integer The data source ID.
blobHandlerType
string The type of blob handler of the data source.
name
string The data source name.
This example request with the payload below will add the data source with the data source ID 1 to the project with the project ID 1.
Example request payload
This example payload will add the data source with the data source ID 2 to the project.
PUT /project/{projectId}/dataSources/{dataSourceId}
Updates the reason for adding a data source to a project.
projectId
integer The project ID.
Yes
dataSourceId
integer The data source ID.
Yes
This example request with the payload below will update the reason that the data source with the data source ID 1 was added to the project with the project ID 1.
None.
DELETE
/project/{projectId}/unsubscribe
POST
/project/current/{projectId}
POST
/project/current/null
POST
/project/{projectId}/members/{subscriptionId}/acknowledge
DELETE /project/{projectId}/unsubscribe
Unsubscribe from a project.
projectId
string The project ID.
Yes
This example request unsubscribes the user from the project with the project ID 5.
POST /project/current/{projectId}
Set the current project ID the current user is acting under.
projectId
integer The project ID.
Yes
This example request sets the current project to act under as the project with the project ID 1.
NonePOST /project/current/null
Set the project context to None.
POST /project/{projectId}/members/{subscriptionId}/acknowledge
Acknowledge all the restrictions on this project.
projectId
integer The project ID.
Yes
subscriptionId
integer The project member's subscription ID.
Yes
text
string
Yes
acknowledgeRequired
boolean When true, the requesting user has not yet agreed to the project acknowledgement.
purposes
array Details of the purpose that has been acknowledged.
This example request acknowledges all of the purposes in the project with the project ID 1.
Payload example
DELETE /project/{projectId}
Delete the project with the given ID.
projectId
integer The project ID.
Yes
hardDelete
boolean If true, the project was permanently deleted.
This example request will delete the project with the project ID 4.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.