Audience: Data Governors and Project Owners
Content Summary: This section of API documentation is specific to managing projects and purposes.
Manage Projects: Create and manage projects, including project policies and access requests.
Manage Purposes: Create purposes that can be applied to projects and used in policies.
This page describes the governance
endpoint of the Immuta API and its request and response parameters used to manage purposes.
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
POST
/governance/purpose
Create a purpose.
This example request with the payload below creates a new purpose.
GET
/governance/purpose
Search for purposes.
This example request returns a list of all of the purposes.
GET
/governance/purpose/{purposeId}
Get a purpose by ID.
This example request returns information on the purpose with the ID 1
, including its sub-purposes.
PUT
/governance/purpose/{purposeId}
Update a purpose.
This example request with the payload below will update the description of the purpose with the ID 8
.
DELETE
/governance/purpose/{purposeId}
Delete the purpose with the given ID and its associated sub-purposes.
This example request deletes the purpose with the ID 8
.
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.
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
Search for projects.
This example request gets a list of all of the projects.
GET
/project/{projectId}
Get the project with the given ID.
This example gets the project object for the project with the ID 2
.
PUT
/project/{projectId}
Update the project with the given ID.
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.
This example gets one activity for the project with the project ID 2
.
GET
/project/{projectId}/checkEqualizationState
Get current state of an equalized project.
This example gets the state of project equalization of the project with the project ID 2
.
GET
/project/{projectId}/members
Get all of the members for a given project.
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.
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.
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.
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
Get all of the data sources for a given 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.
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.
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.
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.
GET
/project/{projectId}/comments
Get all of the comments for a given project.
For each comment listed based on the request there will be
This example request gets all of the comments for the project with the project ID 1
.
POST
/project/{projectId}/comments
Add a comment to the project.
This example request with the payload below writes a new comment for the project with the project ID 1
stating Comment made in the API.
Example request payload
GET
/project/{projectId}/comments/count
Count the comments for a project.
This example counts the comments on the project with the project ID 2
.
GET
/project/{projectId}/comments/{commentId}
Get a comment by ID for a given project.
This example gets the comment with the ID 1
on the project with the project ID 2
.
GET
/project/{projectId}/comments/{parentId}/replies
Get all of the replies for a given comment.
This example gets the replies to the comment with the comment ID 2
on the project with the project ID 1
.
DELETE
/project/{projectId}/comments/{commentId}
Delete a project comment. Deleting a project comment will delete the replies to that comment as well.
This example deletes the comment with the comment ID 1
on the project with the project ID 1
.
POST
/project/{projectId}/comments/{commentId}/resolve
Resolve a comment for a project.
This example request marks the comment with the comment ID 2
resolved in the project with the project ID 1
.
POST
/project/{projectId}/comments/{parentId}/reply
Reply to a project comment.
This example request with the payload below will reply to the comment with the comment ID 2
in the project with the project ID 1
.
Payload example
This example payload will reply to the comment with the text This is a reply through the API.
DELETE
/project/{projectId}/unsubscribe
Unsubscribe from a project.
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.
This example request sets the current project to act under as the project with the project ID 1
.
None
POST
/project/current/null
POST
/project/{projectId}/members/{subscriptionId}/acknowledge
Acknowledge all the restrictions on this project.
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.
This example request will delete the project with the project ID 4
.
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Method | Path | Purpose |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
.
.
.
.
.
.
.
.
Attribute | Description | Required |
---|
Attribute | Description |
---|
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Set the to None
.
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
name
string
The purpose name.
Yes
id
integer
The ID of the purpose.
No
acknowledgement
string
The purpose acknowledgement.
No
description
string
The purpose description.
No
displayAcknowledgement
boolean
When true
, the acknowledgement
text will display for users when they are prompted to agree to use the data in the project only for that purpose. Default is true
.
No
deleted
boolean
If true
, the purpose has been deleted.
No
subpurposes
array
A list of the sub-purposes.
No
policyMetadata
array
Information including the values for kAnonNoiseReduction
, allowUnmaskedKAnon
, adjustmentCertificationText
, isHED
, and adjustmentRequiresDataSourceTag
.
No
staged
boolean
If true
, the purpose is staged.
No
id
integer
The purpose ID.
name
string
The purpose name.
acknowledgement
string
The purpose acknowledgement.
description
string
The purpose description.
addedByProfile
integer
The profile ID of the user who created the purpose.
displayAcknowledgement
boolean
When true
, the acknowledgement
text is displayed for users when they are prompted to agree to use the data in the project only for that purpose.
deleted
boolean
If true
, the purpose has been deleted.
subpurposes
array
A list of the sub-purposes.
policyMetadata
array
Information including the values for kAnonNoiseReduction
, allowUnmaskedKAnon
, adjustmentCertificationText
, isHED
, and adjustmentRequiresDataSourceTag
.
staged
boolean
If true
, the purpose is staged.
createdAt
timestamp
The date the purpose was created.
updatedAt
timestamp
The date the purpose was last updated.
GET
/governance/purpose
GET
/governance/purpose/{purposeId}
offset
integer
Used in combination with size
to fetch pages.
No
size
integer
The number of results to return per page.
No
noLimit
boolean
When true
, the number of results to return per page will not be limited to the number defined by size
. Default is false
.
No
sortField
string
Used to sort results by field. Default is name
.
No
sortOrder
string
Sorts results by order, which must be asc
or desc
. Default is asc
.
No
searchText
string
Search for purpose names by text.
No
root
string
Restrict results to provided root or sub-purposes of root.
No
strictSearch
boolean
When true
, will search for a complete match of the whole string provided in searchText
.
No
getAffectedCount
boolean
If true
, returns the count of projects with each purpose.
No
includeDeleted
boolean
If true
, includes deleted purposes in the results.
No
count
integer
The number of results.
purposes
array
Information on each purpose returned, including id
, name
, acknowledgement
, description
, subpurposes
, policyMetadata
, the creation date, and the staged status.
purposeId
integer
The purpose ID.
Yes
includeSubpurposes
boolean
If true
, sub-purposes will be included in the results.
No
id
integer
The purpose ID.
name
string
The purpose name.
acknowledgement
string
The purpose acknowledgement.
description
string
The purpose description.
addedByProfile
integer
The profile ID of the user who created the purpose.
displayAcknowledgement
boolean
When true
, the acknowledgement
text is displayed for users when they are prompted to agree to use the data in the project only for that purpose.
deleted
boolean
If true
, the purpose has been deleted.
subpurposes
array
A list of the sub-purposes.
policyMetadata
array
Information including the values for kAnonNoiseReduction
, allowUnmaskedKAnon
, adjustmentCertificationText
, isHED
, and adjustmentRequiresDataSourceTag
.
staged
boolean
If true
, the purpose is staged.
createdAt
timestamp
The date the purpose was created.
updatedAt
timestamp
The date the purpose was last updated.
purposeId
integer
The purpose ID.
Yes
name
string
The purpose name.
No
acknowledgement
string
The purpose acknowledgement.
No
description
string
The purpose description.
No
displayAcknowledgement
boolean
When true
, the acknowledgement
text will display for users when they are prompted to agree to use the data in the project only for that purpose. Default is true
.
No
reAcknowledge
boolean
When true
, users will have to re-acknowledge the purpose after it is updated.
No
applyToSubpurposes
boolean
It true
, the updates will be applied to the sub-purposes.
No
policyMetadata
array
Information including the values for kAnonNoiseReduction
, allowUnmaskedKAnon
, adjustmentCertificationText
, isHED
, and adjustmentRequiresDataSourceTag
.
No
id
integer
The purpose ID.
name
string
The purpose name.
acknowledgement
string
The purpose acknowledgement.
description
string
The purpose description.
addedByProfile
integer
The profile ID of the user who created the purpose.
displayAcknowledgement
boolean
When true
, the acknowledgement
text is displayed for users when they are prompted to agree to use the data in the project only for that purpose.
deleted
boolean
If true
, the purpose has been deleted.
subpurposes
array
A list of the sub-purposes.
policyMetadata
array
Information including the values for kAnonNoiseReduction
, allowUnmaskedKAnon
, adjustmentCertificationText
, isHED
, and adjustmentRequiresDataSourceTag
.
staged
boolean
If true
, the purpose is staged.
createdAt
timestamp
The date the purpose was created.
updatedAt
timestamp
The date the purpose was last updated.
purposeId
integer
The purpose ID.
Yes
id
integer
The purpose ID.
name
string
The purpose name.
acknowledgement
string
The purpose acknowledgement.
description
string
The purpose description.
addedByProfile
integer
The profile ID of the user who created the purpose.
displayAcknowledgement
boolean
When true
, the acknowledgement
text is displayed for users when they are prompted to agree to use the data in the project only for that purpose.
deleted
boolean
If true
, the purpose has been deleted.
subpurposes
array
A list of the sub-purposes.
policyMetadata
array
Information including the values for kAnonNoiseReduction
, allowUnmaskedKAnon
, adjustmentCertificationText
, isHED
, and adjustmentRequiresDataSourceTag
.
staged
boolean
If true
, the purpose is staged.
createdAt
timestamp
The date the purpose was created.
updatedAt
timestamp
The date the purpose was last updated.
id |
| Yes |
projectKey |
| Yes |
name |
| Yes |
status |
| Yes |
description |
| No |
documentation |
| No |
tags |
| No |
purposes |
| No |
stagedPurposes |
| No |
deleted |
| No |
snowflake |
| No |
allowMaskedJoins |
| No |
subscriptionPolicy |
| No |
subscriptionType |
| No |
equalization |
| No |
workspace |
| No |
type |
| No |
createdAt |
| No |
updatedAt |
| No |
id |
|
projectKey |
|
name |
|
status |
|
description |
|
documentation |
|
tags |
|
purposes |
|
stagedPurposes |
|
deleted |
|
snowflake |
|
allowMaskedJoins |
|
subscriptionPolicy |
|
subscriptionType |
|
equalization |
|
workspace |
|
type |
|
createdAt |
|
updatedAt |
|
workspaceWarnings |
|
offset |
| No |
size |
| No |
sortField |
| No |
sortOrder |
| No |
subscription |
| No |
status |
| No |
searchText |
| No |
tag |
| No |
nameOnly |
| No |
isEqualized |
| No |
snowflake |
| No |
dataSourceId |
| No |
mode |
| No |
count |
|
hits |
|
id |
|
projectKey |
|
name |
|
status |
|
description |
|
documentation |
|
tags |
|
purposes |
|
stagedPurposes |
|
deleted |
|
snowflake |
|
allowMaskedJoins |
|
subscriptionPolicy |
|
subscriptionType |
|
equalization |
|
workspace |
|
type |
|
createdAt |
|
updatedAt |
|
acknowledgeRequired |
|
subscriptionId |
|
subscribedAsUser |
|
subscriptionStatus |
|
filterId |
|
facets |
|
projectId |
| Yes |
checkForSqlAccount |
| No |
id |
|
projectKey |
|
name |
|
status |
|
description |
|
documentation |
|
tags |
|
purposes |
|
stagedPurposes |
|
deleted |
|
snowflake |
|
allowMaskedJoins |
|
subscriptionPolicy |
|
subscriptionType |
|
equalization |
|
workspace |
|
type |
|
createdAt |
|
updatedAt |
|
acknowledgeRequired |
|
subscriptionId |
|
subscribedAsUser |
|
subscriptionStatus |
|
projectId |
| Yes |
deleteDataSources |
| No |
type |
| No |
name |
| No |
description |
| No |
documentation |
| No |
status |
| No |
subscriptionType |
| No |
tags |
| No |
purposes |
| No |
stagedPurposes |
| No |
deleted |
| No |
snowflake |
| No |
allowMaskedJoins |
| No |
subscriptionPolicy |
| No |
equalization |
| No |
workspace |
| No |
id |
|
projectKey |
|
name |
|
status |
|
description |
|
documentation |
|
tags |
|
purposes |
|
stagedPurposes |
|
deleted |
|
snowflake |
|
allowMaskedJoins |
|
subscriptionPolicy |
|
subscriptionType |
|
equalization |
|
workspace |
|
type |
|
createdAt |
|
updatedAt |
|
workspaceWarnings |
|
projectId |
| Yes |
offset |
| No |
size |
| No |
count |
|
activities |
|
id |
|
modelType |
|
modelId |
|
notificationType |
|
actionBy |
|
targetUser |
|
targetGroup |
|
metadata |
|
createdAt |
|
updatedAt |
|
read |
|
unread |
|
projectId |
| Yes |
equalizationState |
|
projectId |
| Yes |
offset |
| No |
size |
| No |
sortField |
| No |
sortOrder |
| No |
searchText |
| No |
approved |
| No |
checkDataSources |
| No |
expandGroups |
| No |
count |
|
members |
|
profile |
|
name |
|
iamId |
|
userId |
|
|
type |
|
approved |
|
state |
|
systemGenerated |
|
lastExternalRefresh |
|
subscriptionId |
|
createdAt |
|
updatedAt |
|
approvals |
|
compliance |
|
projectId |
| Yes |
conditionsObj |
| Yes |
operator |
| Yes |
conditions |
| Yes |
type |
| No |
group |
| No |
validSet |
|
usersMissingAuths |
|
projectId |
| Yes |
profileId |
| Yes |
groupId |
| No |
state |
| No |
expiration |
| No |
approvals |
| No |
projectId |
| Yes |
subscriptionId |
| Yes |
state |
| Yes |
expiration |
| No |
state |
|
expiration |
|
projectId |
| Yes |
offset |
| No |
searchText |
| No |
size |
| No |
sortField |
| No |
sortOrder |
| No |
unsubscribed |
| No |
subscription |
| No |
count |
|
dataSources |
|
addedBy |
|
dataSourceName |
|
policyHandlerType |
|
addedOn |
|
dataSourceId |
|
addedByProfile |
|
deleted |
|
subscriptionType |
|
subscriptionStatus |
|
subscriptionPolicy |
|
connectionString |
|
blobHandlerType |
|
derivedInThisProject |
|
projectId |
| Yes |
ids |
| Yes |
success |
|
inError |
|
id |
|
blobHandlerType |
|
name |
|
projectId |
| Yes |
dataSourceIds |
| Yes |
success |
|
inError |
|
id |
|
blobHandlerType |
|
name |
|
projectId |
| Yes |
dataSourceId |
| Yes |
projectId |
| Yes |
dataSources |
| No |
resolved |
| No |
sortField |
| No |
sortOrder |
| No |
author |
|
body |
|
resolved |
|
id |
|
createdAt |
|
updatedAt |
|
models |
|
totalReplies |
|
lastReply |
|
public |
|
projectId |
| Yes |
body |
| Yes |
dataSource |
| No |
author |
|
body |
|
parentId |
|
resolved |
|
id |
|
createdAt |
|
updatedAt |
|
projectId |
| Yes |
dataSources |
| No |
resolved |
| No |
modelId |
|
modelType |
|
count |
|
projectId |
| Yes |
commentId |
| Yes |
id |
|
author |
|
resolved |
|
body |
|
parentId |
|
replies |
|
createdAt |
|
updatedAt |
|
projectId |
| Yes |
parentId |
| Yes |
id |
|
author |
|
resolved |
|
body |
|
parentId |
|
createdAt |
|
updatedAt |
|
totalReplies |
|
public |
|
projectId |
| Yes |
commentId |
| Yes |
projectId |
| Yes |
commentId |
| Yes |
projectId |
| Yes |
parentId |
| Yes |
body |
| Yes |
id |
|
projectId |
| Yes |
projectId |
| Yes |
projectId |
| Yes |
subscriptionId |
| Yes |
text |
| Yes |
acknowledgeRequired |
|
purposes |
|
projectId |
| Yes |
hardDelete |
|
GET |
|
GET |
|
PUT |
|
GET |
|
GET |
|
GET |
|
POST |
|
POST |
|
PUT |
|
GET |
|
DELETE |
|
POST |
|
PUT |
|
GET |
|
POST |
|
GET |
|
GET |
|
DELETE |
|
GET |
|
POST |
|
POST |
|
DELETE |
|
POST |
|
POST |
|
POST |
|
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.