# Subscribe to and Manage Data Sources This page describes the `dataSource` endpoint, through which users can subscribe to data sources and manage data source tasks. To create data sources, see the specific handler endpoints. {% hint style="info" %} Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented. {% endhint %} ## Data source workflow 1. [Search data sources and data source details](#search-data-sources-and-data-source-details). 2. [Access data sources and make data source requests](#access-data-sources-and-make-data-source-requests). 3. [Manage data source requests](#manage-data-source-requests). 4. [Update data sources](#update-data-sources). 5. [Delete a data source](#delete-a-data-source). ## Search data sources and data source details
MethodPathPurpose
GET/dataSourceSearch for data sources.
GET/dataSource/{dataSourceId}Get a data source based on the ID.
GET/dataSource/name/{dataSourceName}Get data source based on the name.
GET/dataSource/sqlTableName/{shortName}Get data source based on the short name.
GET/dataSource/{dataSourceId}/accessGet all users with the provided access level for this data source.
GET/dataSource/{dataSourceId}/users/{profileId}/policyInfoRetrieves the visibilities, masking information, and filters that the passed in user has access to in the specified data source.
GET/dataSource/{dataSourceId}/users/{profileId}/visibilityReportRetrieves a summary of total records, total visibilities, and visibilities a given user has access to.
GET/dataSource/{dataSourceId}/visibilityReportRetrieves a summary of total records, total visibilities, and visibilities the current user has access to for a specified data source.
### Search for data sources `GET` `/dataSource` Search for data sources that you own or are authorized to see. **Required**: For a data source to appear in the response, you must own the data source, the data source must be publicly visible, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy #### Query parameters | Attribute | Description | Required | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | blobHandlerType | `array[string]` Describes the type of underlying blob handler that will be used with this data source (e.g., Custom, MS SQL). | No | | subscription | `array[string]` The requesting user's subscription status: `pending`, `owner`, `subscribed`, `not_subscribed`, or `expert`. | No | | status | `array[string]` The data source status: `passed` or `failed`. | No | | tag | `array[string]` Filters data sources by tags associated with the data sources. | No | | tagOperator | `string` Use with the `tag` attribute to search for data sources with multiple tags. Options are `AND` or `OR`. | No | | tagModelTypes | `string` Use with the `tag` attribute to search for data sources with the tags applied to the `datasource` or the `column`. | No | | searchText | `string` Searches for data source names using the provided `string`. | No | | fuzzySearch | `boolean` If `true`, the search will ignore quotes and spaces. | No | | column | `array[string]` Searches for data source column names. | No | | connectionString | `array[string]` Searches by connection string. | No | | schema | `string` Searches for data source schema. | No | | nameOnly | `boolean` When `true`, `searchText` will only search data source names. **Default is `false`.** | No | | idOnly | `boolean` When `true`, only returns the ID Of the data source and the user's subscription status. | No | | dataSourceIds | `array[integer]` Searches for the provided data source IDs. | No | | selectFields | `array[string]` This field accepts the values `id`, `name`, and `columnEvolutionEnabled`. When `id` or `name` are provided, the request will return only the ID or name of the data source and the subscription status. If `columnEvolutionEnabled` is provided, the response will also include information about the policies, policy conflicts, and workspaces associated with the data sources. | No | | offset | `integer` Used in combination with `size` to fetch pages. **Default is `0`.** | No | | size | `integer` The number of results to return per page. **Default is `10`.** | No | | sortField | `string` Used to sort results by field, which must be `createdAt`, `name`, `blobHandlerType`, `subscriptionStatus`, `id`, `status`, `policy`, or `editable`. | No | | sortOrder | `string` Sorts results by order, which must be `asc` or `desc`. | No | | excludedProjects | `array[integer]` Filter out any data sources that belong to the specified projects. | No | | ephemeral | `boolean` When `true`, returns ephemeral data sources. | No | | clusterName | `string` The name of the remote cluster the data source is connected to. | No | | mode | `integer` Specifies the query mode, which must be `0` (`FULL`), `1` (`COUNT`), `4` (`TAG`), `5` (`MIN_MAX`), or `6` (`STATUS`). | No | | globalPolicy | `string` Filter by data sources that have this Global Policy applied. | No | | hostname | `string` Searches data sources by hostname. | No | | determinePolicyConflicts | `boolean` When `true`, filters results to return the data sources with policy conflicts. | No | | domainId | `string` Filter by data sources in the domain with this ID. | No | | domainExclude | `string` When `true`, filters results to return the data sources in the domain of the provided ID. | No | | domainsToExclude | `array[string]` Use with the `domainExclude` attribute to filter out data sources by the domains they are in. | No | | disabled | `boolean` If `true`, only data sources that are disabled will be returned. | No | | port | `string` Filter by data sources associated with a specific port. | No | | metastoreId | `string` Filter by data sources with the specific metastore ID. | No | | objectType | `array[string]` Filter by the specifc object type of the data source. Options include: `table`, `view`, `volume`, `function`, and `model`. | No | #### Response schema The response will return data sources you own or are authorized[^1] to see. | Attribute | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | `string` Data source name. | | id | `integer` Data source ID. | | deleted | `boolean` If `true` the data source is a deleted data source. | | description | `string` The data source description. | | createdAt | `timestamp` The date and time the data source was created. | | subscriptionPolicy | `array` Details the type of subscription policy applied to the data source. | | schemaEvolutionId | `integer` The schema evolution ID. | | status | `array[string]` Accepted statuses are `passed` or `failed`. | | subscriptionStatus | `array[string]` Accepted statuses are `owner`, `subscribed`, or `unsubscribed`. | | blobHandlerType | `array[string]` Describes the type of underlying blob handler of this data source (e.g., Custom, MS SQL). | | 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). | | connectionString | `string` The connection string information. | | sqlSchemaName | `string` The name of the schema. | | statusPriority | `integer` The priority the data source's status is based on importance. For example, a `failed` status will be a higher-priority (`1`). | | remoteTable | `string` The name of the table in the data platform. | | remoteSchema | `string` The name of the schema in the data platform. | | tableType | `string` The type of data object. Options include: `BASE TABLE`, `ICEBERG TABLE`, `VIEW`, `MATERIALIZED VIEW`, `MANAGED`, `STREAMING_TABLE`, `MATERIALIZED_VIEW`, `VOLUME_MANAGED`, `VOLUME_EXTERNAL`, `GOVERNED`, and `EXTERNAL_TABLE`. | | domains | `object` Details about the domains the data source is in. | | remoteDataObject | `object` Details about the table name and path of the data object in the remote platform. | #### Request example The following request returns 2 data sources. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource?size=2 ``` #### Response example ```json { "name": "SnowflakeConnection . snowflake . public . Public Barfoo", "id": 22, "deleted": false, "description": null, "createdAt": "2021-07-22T14:11:55.539Z", "subscriptionPolicy": { "type": "subscription", "automaticSubscription": true }, "schemaEvolutionId": 1, "status": "passed", "statusPriority": 6, "subscriptionStatus": "subscribed", "blobHandlerType": "Snowflake", "subscriptionType": "automatic", "connectionString": "test@immuta.connection.source.com:###/test", "sqlSchemaName": "public", "remoteTable": "Public Barfoo", "remoteSchema": "public", "tableType": "BASE TABLE", "domains": null, "remoteDataObject": { "objectPath": [ "SnowflakeConnection", "snowflake", "public", "Public Barfoo" ], "name": "Public Barfoo", "path": "SnowflakeConnection/snowflake/public/Public Barfoo" } }, { "name": "SnowflakeConnection . snowflake . public . tpc", "id": 39, "deleted": false, "description": null, "createdAt": "2023-08-21T10:39:00.250Z", "subscriptionPolicy": { "type": "subscription", "exceptions": { "operator": "and", "conditions": [ { "type": "groups", "group": { "name": "alpha" } } ] }, "allowDiscovery": true, "automaticSubscription": true }, "schemaEvolutionId": 1, "blobHandlerType": "Snowflake", "subscriptionType": "policy", "sqlSchemaName": "public", "status": "passed", "statusPriority": 6, "subscriptionStatus": "owner", "connectionString": "test@immuta.connection.source.com:###/test", "remoteTable": "tpc", "remoteSchema": "public", "tableType": "BASE TABLE", "domains": null, "remoteDataObject": { "objectPath": [ "SnowflakeConnection", "snowflake", "public", "tpc" ], "name": "tpc", "path": "SnowflakeConnection/snowflake/public/tpc" } } ``` ### Get a data source by ID `GET` `/dataSource/{dataSourceId}` Get a data source based on the ID. **Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy **Query parameters** | Attribute | Description | Required | | ------------ | ------------------------------ | -------- | | dataSourceId | `integer` The data source ID . | **Yes** | **Response Schema** | Attribute | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | `string` The data source name. | | recordFormat | `string` The data format of blobs in the data source, such as `json`, `xml`, `html`, or `jpeg`. | | description | `string` The description of the data source. | | policyHandler | `array` The ID of the policy handler and details about the data policies enforced on the data source. | | sqlSchemaName | `string` A string that represents this data source's schema name in Immuta. | | sqlTableName | `string` The SQL table name in Immuta. | | blobHandler | `array[object]` A list of full URLs providing the locations of all blob store handlers to use with this data source. | | blobHandlerType | `string` Describes the type of underlying blob handler that will be used with this data source (e.g., `MS SQL`). | | createdBy | `integer` The ID of the profile creating the data source. | | deleted | `boolean` If true, the data source was deleted. | | type | `string` The data source type: `queryable`. | | rowCount | `integer` The number of rows. | | id | `integer` The data source ID. | | statsExpiration | `timestamp` The time when the data source statistics (e.g., `rowCount`) expire and will need to be re-run. | | blobHandlerType | `string` The technology connector for the data source. | | policyHandlerType | `string` The type of policy handler applied to the data source: `Builder`. | | subscriptionType | `string` The type of subscription policy on the data source. 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). | | subscriptionPolicy | `array` Details about the subscription policy applied to the data source. | | globalPolicies | `string` Details about the global policies applied to the data source. | | status | `string` The data source health status. | | statusInfo | `object` Details about the status of all the jobs and health checks that ran on the data source. | | catalogMetadata | `object` Details about the connected external catalog. | | workspace | `integer` The ID of the workspace the data is in. | | seeded | `boolean` If `true`, the data source was system-generated. | | schemaEvolutionId | `string` The ID for the schema project the data source is in. | | columnEvolutionEnabled | `boolean` If `true`, the data source has schema monitoring and column detection on. | | createdAt | `timestamp` The time the data source was created. | | updatedAt | `timestamp` The time the data source was last updated. | | dataObjectId | `integer` The ID of the data object associated with the data source. | | legacyName | `string` The name of the data source before it was upgraded to connections. | | dataObjectUniqueId | `string` The UUID for the data object associated with the data source. | | parentIdPath | `array` The list of UUIDs for the parent data objects (e.g., database, schema, etc.) that contain this data source. | | namePath | `array` The list of names for the parent data objects (e.g., database, schema, etc.) that contain this data source. | | legacyObjectType | `string` The type of data object. Options include: `BASE TABLE`, `ICEBERG TABLE`, `VIEW`, `MATERIALIZED VIEW`, `MANAGED`, `STREAMING_TABLE`, `MATERIALIZED_VIEW`, `VOLUME_MANAGED`, `VOLUME_EXTERNAL`, `GOVERNED`, and `EXTERNAL_TABLE`. | | connectionKey | `string` The connection key (or display name) for the connection the data source comes from. | | subscribedAsUser | `boolean` If `true`, the user who made the API request is subscribed to the data source. | | subscriptionContext | `string` Description of why the user does or does not have access to the data source. Optional and may not be available. | | subscriptionId | `integer` An ID of the record associated with the subscription of the user who made the API request to the data source. | | acknowledgeRequired | `boolean` If `true`, users must adknowledge the policy before they can subscribe to the data source. | | subscriptionStatus | `string` The subscription status to the data source of the user who made the API request. Accepted statuses are `owner`, `subscribed`, or `unsubscribed`. | | requestedState | `string` The subscription state of the user making the API request if they manually requested access to the data source in the Govern app. | | approved | `boolean` If `true`, the user's requested subscription status was approved. | | subscriptionExpiration | `timestamp` The time that the user who made the API request subscription to the data source will expire. | | filterId | `string` The ID of the search filter applied to this data source, if available. | | accessGrant | `string` The type of access granted to the user making the API request. Options include: `READ` and `WRITE`. | | accessPolicies | `object` Details about the access policies applied to the data source. | | subscribers | `integer` The number of Immuta users subscribed to the data source. | | tags | `object` Details about the tags applied to this data source. | | fingerprintCreatedAt | `timestamp` The last time the data source fingerprint was generated, if available. | | remoteDataObject | `object` Details about the remote data object including the name and path. | #### Request example The following request gets a data source based on the ID `22`. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/22 ``` #### Response example ```json { "name": "SnowflakeConnection . snowflake . public . tcp", "recordFormat": "Not Provided", "description": null, "policyHandler": null, "sqlSchemaName": "public", "sqlTableName": "tcp", "blobHandler": { "url": "https://your-url/snowflake/handler/22", "ca": { "name": "Certificate Authority Bundle" }, "manualDictionary": false }, "createdBy": 2, "deleted": false, "type": "queryable", "recordCount": 0, "rowCount": 6, "statsExpiration": "2021-08-27T16:34:47.846Z", "id": 22, "blobHandlerType": "Snowflake", "policyHandlerType": "Builder", "subscriptionType": "automatic", "subscriptionPolicy": { "type": "subscription", "automaticSubscription": true }, "globalPolicies": null, "status": "passed", "statusInfo": { "sql": { "status": "passed", "message": "Passed" } }, "catalogMetadata": null, "workspace": null, "seeded": false, "schemaEvolutionId": null, "columnEvolutionEnabled": false, "createdAt": "2025-11-19T23:20:08.297Z", "updatedAt": "2026-03-17T17:27:40.514Z", "dataObjectId": 398083, "legacyName": null, "dataObjectUniqueId": "4eed11f5-1368-4b75-afda-e7c5634544b4", "parentIdPath": [ "db86f25d-f4e9-4e86-9862-2ca22f0213f7", "9c008f0d-69b5-446c-ac2c-bc34e544aef4", "2c786c68-87a9-4896-8925-93423ddfb5b3" ], "namePath": [ "snowflake", "public", "tcp" ], "legacyObjectType": "BASE TABLE", "connectionKey": "SnowflakeConnection", "subscribedAsUser": true, "subscriptionContext": null, "subscriptionId": 15291, "acknowledgeRequired": false, "subscriptionStatus": "owner", "requestedState": "owner", "approved": true, "subscriptionExpiration": null, "filterId": null, "accessGrant": "READ", "accessPolicies": null, "subscribers": 2, "tags": [ { "id": 73517, "name": "Immuta Connections.Snowflake.SnowflakeConnection.snowflake.public", "displayName": "public", "source": "connections", "context": "connections", "addedBy": 1, "deleted": false }, { "id": 77919, "name": "Immuta Marketplace Data Object.4eed11f5-1368-4b75-afda-e7c5634544b4", "displayName": "4eed11f5-1368-4b75-afda-e7c5634544b4", "source": "marketplace", "context": "marketplace", "addedBy": 1, "deleted": false } ], "fingerprintCreatedAt": null, "remoteDataObject": { "objectPath": [ "SnowflakeConnection", "snowflake", "public", "tcp" ], "name": "tcp", "path": "SnowflakeConnection/snowflake/public/tcp", "lastCrawled": "2025-12-01T01:49:57.883Z" } } ``` ### Get data source by name `GET` `/dataSource/name/{dataSourceName}` Get a data source based on the name. **Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy #### Query parameters | Attribute | Description | Required | | -------------- | ------------------------------ | -------- | | dataSourceName | `string` The data source name. | **Yes** | #### Response schema | Attribute | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | `string` The data source name. | | recordFormat | `string` The data format of blobs in the data source, such as `json`, `xml`, `html`, or `jpeg`. | | description | `string` The description of the data source. | | policyHandler | `array` The ID of the policy handler and details about the data policies enforced on the data source. | | sqlSchemaName | `string` A string that represents this data source's schema name in Immuta. | | sqlTableName | `string` The SQL table name in Immuta. | | blobHandler | `array[object]` A list of full URLs providing the locations of all blob store handlers to use with this data source. | | blobHandlerType | `string` Describes the type of underlying blob handler that will be used with this data source (e.g., `MS SQL`). | | createdBy | `integer` The ID of the profile creating the data source. | | deleted | `boolean` If true, the data source was deleted. | | type | `string` The data source type: `queryable`. | | rowCount | `integer` The number of rows. | | id | `integer` The data source ID. | | policyHandlerType | `string` The type of policy handler applied to the data source: `Builder`. | | subscriptionType | `string` The type of subscription policy on the data source. 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). | | subscriptionPolicy | `array` Details about the Subscription Policy applied to the data source. | | globalPolicies | `string` Details about the Global Policies applied to the data source. | | status | `string` The data source health status. | #### Request example The following request gets a data source based on the name `Public Barfoo`. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/name/Public%20Barfoo ``` #### Response example ```json { "name": "Public Barfoo", "recordFormat": "Not Provided", "description": null, "policyHandler": null, "sqlSchemaName": "public", "sqlTableName": "barfoo", "blobHandler": { "url": "https://your-url/snowflake/handler/22", "ca": { "name": "Certificate Authority Bundle" }, "manualDictionary": false }, "createdBy": 2, "deleted": false, "type": "queryable", "recordCount": 0, "rowCount": 6, "statsExpiration": "2021-08-27T16:34:47.846Z", "id": 22, "blobHandlerType": "Snowflake", "policyHandlerType": "None", "subscriptionType": "automatic", "subscriptionPolicy": { "type": "subscription", "automaticSubscription": true }, "globalPolicies": null, "status": "passed", "statusInfo": { "sql": { "status": "passed", "message": "Passed" } } } ``` ### Get a data source by the short name `GET` `/dataSource/sqlTableName/{shortName}` Get a data source based on the SQL table name. **Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy #### Query parameters | Attribute | Description | Required | | --------- | ---------------------------------------- | -------- | | shortName | `string` The data source SQL table name. | **Yes** | #### Response schema | Attribute | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | `string` The data source name. | | recordFormat | `string` The data format of blobs in the data source, such as `json`, `xml`, `html`, or `jpeg`. | | description | `string` The description of the data source. | | policyHandler | `array` The ID of the policy handler and details about the data policies enforced on the data source. | | sqlSchemaName | `string` A string that represents this data source's schema name in Immuta. | | sqlTableName | `string` The SQL table name in Immuta. | | blobHandler | `array[object]` A list of full URLs providing the locations of all blob store handlers to use with this data source. | | blobHandlerType | `string` Describes the type of underlying blob handler that will be used with this data source (e.g., `MS SQL`). | | createdBy | `integer` The ID of the profile creating the data source. | | deleted | `boolean` If true, the data source was deleted. | | type | `string` The data source type: `queryable`. | | rowCount | `integer` The number of rows. | | id | `integer` The data source ID. | | policyHandlerType | `string` The type of policy handler applied to the data source: `Builder`. | | subscriptionType | `string` The type of subscription policy on the data source. 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). | | subscriptionPolicy | `array` Details about the Subscription Policy applied to the data source. | | globalPolicies | `string` Details about the Global Policies applied to the data source. | | status | `string` The data source health status. | #### Request example The following request gets a data source based on the SQL table name `customer_data`. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/sqlTableName/customer_data ``` #### Response example ```json { "name": "Dbo Customer Data", "recordFormat": "Not Provided", "description": null, "policyHandler": { "visibilitySchema": { "fields": [], "version": "2021-10-06T19:39:39.145Z" }, "handlerId": 55, "dataSourceId": 26 }, "sqlSchemaName": "dbo", "sqlTableName": "customer_data", "blobHandler": { "url": "https://1.1.1.1.1/snowflake/testhandler/26", "ca": { "name": "Certificate Authority Bundle" }, "manualDictionary": false }, "createdBy": 2, "deleted": false, "type": "queryable", "recordCount": 0, "rowCount": 1000, "statsExpiration": "2021-11-05T19:37:43.270Z", "id": 26, "blobHandlerType": "Snowflake", "policyHandlerType": "Builder", "subscriptionType": "automatic", "subscriptionPolicy": { "type": "subscription", "automaticSubscription": false }, "globalPolicies": null, "status": "passed", "statusInfo": { "sql": { "status": "passed", "message": "Passed" }, "stats": { "status": "passed", "lastAttempted": "2021-10-06T19:37:43.337Z" }, "lastAttempt": { "date": "2021-10-06T19:39:39.821Z" }, "highCardinality": { "status": "passed", "lastAttempted": "2021-10-06T19:37:43.337Z" } }, "expiration": null, "catalogMetadata": null, "workspace": null, "seeded": false, "schemaEvolutionId": 4, "columnEvolutionEnabled": true, "createdAt": "2021-10-01T14:23:27.225Z", "updatedAt": "2021-10-06T19:39:39.145Z", "subscribedAsUser": true, "subscriptionId": 45, "acknowledgeRequired": false, "subscriptionStatus": "owner", "requestedState": "owner", "approved": true, "subscriptionExpiration": null, "filterId": null } ``` ### Get users by access level `GET` `/dataSource/{dataSourceId}/access` Get all users with the provided access level for this data source. **Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy #### Query parameters | Attribute | Description | Required | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | | states | `Array[string]` The status levels to include when querying for user access. | No | | approved | `boolean` Denotes whether the returned access objects should be approved. | No | | searchText | `string` A string used to filter returned users. The query is executed with a wildcard prefix and suffix. | No | | size | `integer` The number of results to return. | No | | offset | `integer` The number of results to skip (for paging). | No | | sortField | `string` The field on which to sort the result set. | No | | sortOrder | `string` The order in which to sort the results. | No | | expandGroups | `boolean` If true will return individual members of any group subscribed. | No | | ignoreSystemGenerated | `boolean` If true, will not return system generated accounts. | No | | filterBySchemaEvolution | `boolean` If true, will only return users who have the specified level of access across ALL data sources within the same schema evolution group as this one. | No | #### Response schema | Attribute | Description | | --------- | ------------------------------------------------------------------------- | | count | `integer` The number of users with access to the data source. | | users | `string` The metadata regarding the users with access to the data source. | #### Request example The following request gets all users with the provided access level for this data source. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/22/access?sortOrder=desc ``` #### Response example ```json { "count": 2, "users": [ { "profile": 2, "name": "First Last", "iamid": "bim", "userid": "first.last@immuta.com", "email": "first.last@immuta.com", "type": "user", "admin": "First Last", "approved": true, "state": "owner", "systemGenerated": false, "lastExternalRefresh": "2021-10-06T14:58:46.983Z", "subscriptionId": 586, "createdAt": "2021-10-05T14:33:01.518Z", "updatedAt": "2021-10-05T14:33:01.518Z", "approvals": [ { "requiredPermission": "OWNER", "state": "approved", "approverId": null, "ownerModelId": null, "approver": "First Last", "ownerModelName": null } ], "currentUserCanApprove": false }, { "profile": 3, "name": "Tommy Test", "iamid": "bim", "userid": "tommy.test@immuta.com", "email": "tommy.test@immuta.com", "type": "user", "admin": "First Last", "approved": true, "state": "subscribed", "systemGenerated": false, "lastExternalRefresh": "2021-09-07T16:16:29.957Z", "subscriptionId": 649, "createdAt": "2021-10-06T14:58:31.366Z", "updatedAt": "2021-10-06T14:58:31.366Z", "approvals": [ { "requiredPermission": "OWNER", "state": "approved", "approverId": null, "ownerModelId": null, "approver": "First Last", "ownerModelName": null } ], "currentUserCanApprove": false } ] } ``` ### Get user access info for a data source `GET` `/dataSource/{dataSourceId}/users/{profileId}/policyInfo` Retrieves the visibilities, masking information, and filters that the passed in user has access to in the specified data source. **Required Immuta permission**: `FETCH_POLICY_INFO` #### Query parameters | Attribute | Description | Required | | ------------ | --------------------------------------------------------------------------------------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | | profileId | `integer` The profile ID of the user. | **Yes** | | projectId | `integer` The project ID. If provided, this project will be used when evaluating the user's visibilities. | No | #### Response schema | Attribute | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | visibilities | `array` Details of the user's visibilities, including `anyKey`. | | visibilityRuleApplies | `boolean` If `true`, a visibility rule exists and the user is not excepted from it. | | masked | `array` Masking information for the data source, including `metadata`, `name`, `type`, and `actionType`. | | additionalFilters | `array` Policy information for the data source, including `customWhere`, `differentialPrivacy`, `eventTimeColumn`, `minimization`, `time`, `filterSeconds`, and `isOlderOrNewer`. | #### Request example The following request gets the visibility information for the user with the profile ID `2` on the data source with the data source ID `16`. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/16/users/2/policyInfo ``` #### Response example ```json { "visibilities": [], "visibilityRuleApplies": false, "masked": [ { "type": "Consistent Value", "metadata": { "constant": null }, "name": "WS_SOLD_DATE_SK", "actionType": "Nullify" }, { "type": "Consistent Value", "metadata": { "constant": null }, "name": "WS_BILL_CUSTOMER_SK", "actionType": "Nullify" } ], "additionalFilters": {} } ``` ### Get user visibility info for a data source `GET` `/dataSource/{dataSourceId}/users/{profileId}/visibilityReport` Retrieves a summary of total records, total visibilities (the unique values contained in a column protected by a row-level security policy that allow Immuta to determine whether or not a user can see a given row if they possess an attribute that matches the visibility of that row), and visibilities a given user has access to. **Required**: The global `GOVERNANCE` permission or be the data source owner #### Query parameters | Attribute | Description | Required | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | | profileId | `integer` The profile ID of the user. | **Yes** | | informationOnly | `boolean` If `true`, the query will just return information for the UI and will skip running some queries for ephemeral data sources. | No | | includeNestedColumns | `boolean` If `true`, the query will return just information for the dictionary page, including the masking policies for nested columns. | No | #### Response schema | Attribute | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | noVisibilities | `boolean` If `true`, the data source has no row-level security or purpose-based restriction policies applied to it. | | dataSourceVisibilitiesCount | `integer` The total number of possible visibilities the given data source has. | | userVisibilitiesCount | `integer` The number of visibilities the current user can see for the given data source. | | masked | `array` Masking information for the data source, including `metadata`, `name`, `type`, and `actionType`. | | dataSource | `integer` The data source ID. | | dataSourceName | `string` The data source name. | | additionalFilters | `array` Policy information for the data source, including `customWhere`, `differentialPrivacy`, `eventTimeColumn`, `minimization`, `time`, `filterSeconds`, and `isOlderOrNewer`. | | allowMaskedJoins | `boolean` If `true` the data source allows masked joins. | | policySet | `array` Details about the policies on the data source. | #### Request example The following request gets all of the visibility information for the user with the profile ID `2` on the data source with the data source ID `16`. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/16/users/2/visibilityReport ``` #### Response example ```json [ { "noVisibilities": true, "dataSourceVisibilitiesCount": 0, "userVisibilitiesCount": 0, "masked": [ { "type": "Consistent Value", "metadata": { "constant": null }, "name": "WS_SOLD_DATE_SK" }, { "type": "Consistent Value", "metadata": { "constant": null }, "name": "WS_BILL_CUSTOMER_SK" } ], "dataSource": 16, "dataSourceName": "Web Sales", "additionalFilters": {}, "allowMaskedJoins": false, "policySet": "[{\"type\":\"masking\",\"rules\":[{\"type\":\"masking\",\"config\":{\"fields\":[\"WS_BILL_CUSTOMER_SK\"],\"maskingConfig\":{\"type\":\"Consistent Value\",\"metadata\":{\"constant\":null}}},\"exceptions\":null,\"ruleAppliedForUser\":true}],\"global\":{\"id\":9,\"tag\":\"Confidential\",\"live\":true,\"name\":\"Data Policy\",\"reason\":null,\"staged\":false,\"deleted\":false,\"conflict\":null,\"disabled\":false,\"metadata\":null,\"template\":false,\"createdAt\":\"2022-08-09T17:23:02.634Z\",\"createdBy\":\"jane\",\"policyKey\":\"Data Policy\",\"updatedAt\":\"2022-08-09T17:23:02.634Z\",\"clonedFrom\":null,\"certification\":null,\"createdByName\":\"jane\",\"changedOnApply\":[\"dataTypeMismatch\"],\"parentPolicyId\":null,\"systemGenerated\":false,\"originalPolicyId\":\"masking(^_^)data policy(^_^)ws_bill_customer_sk(^_^)consistent value(^_^)(^_^)(^_^)\",\"ownerRestrictions\":null},\"description\":null,\"policyHash\":\"3a2faac13e332cca1829ed773afa298a5455ac5bb54e68c53ae00991575d2a4b\"},{\"type\":\"masking\",\"rules\":[{\"type\":\"masking\",\"config\":{\"fields\":[\"WS_SOLD_DATE_SK\"],\"maskingConfig\":{\"type\":\"Consistent Value\",\"metadata\":{\"constant\":null}}},\"exceptions\":null,\"ruleAppliedForUser\":true}],\"global\":{\"id\":9,\"tag\":\"Confidential\",\"live\":true,\"name\":\"Data Policy\",\"reason\":null,\"staged\":false,\"deleted\":false,\"conflict\":null,\"disabled\":false,\"metadata\":null,\"template\":false,\"createdAt\":\"2022-08-09T17:23:02.634Z\",\"createdBy\":\"jane\",\"policyKey\":\"Data Policy\",\"updatedAt\":\"2022-08-09T17:23:02.634Z\",\"clonedFrom\":null,\"certification\":null,\"createdByName\":\"jane\",\"changedOnApply\":[\"dataTypeMismatch\"],\"parentPolicyId\":null,\"systemGenerated\":false,\"originalPolicyId\":\"masking(^_^)data policy(^_^)ws_sold_date_sk(^_^)consistent value(^_^)(^_^)(^_^)\",\"ownerRestrictions\":null},\"description\":null,\"policyHash\":\"2877a1ace4cfa6427370fd39b254ce0ea75dc22cb024a2f857e033c82a987f9a\"}]" } ] ``` ### Get current user visibility info `GET` `/dataSource/{dataSourceId}/visibilityReport` Retrieves a summary of total records, total visibilities (the unique values contained in a column protected by a row-level security policy that allow Immuta to determine whether or not a user can see a given row if they possess an attribute that matches the visibility of that row), and visibilities the current user has access to for a specified data source. **Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy #### Query parameters | Attribute | Description | Required | | ------------ | ----------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | #### Response schema | Attribute | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | noVisibilities | `boolean` If `true`, the data source has no row-level security or purpose-based restriction policies applied to it. | | dataSourceVisibilitiesCount | `integer` The total number of possible visibilities the given data source has. | | userVisibilitiesCount | `integer` The number of visibilities the current user can see for the given data source. | | denialReason | `string` Reason the user was denied visibility. | | masked | `array` Masking information for the data source, including `metadata`, `name`, `type`, and `actionType`. | | dataSource | `integer` The data source ID. | | dataSourceName | `string` The data source name. | | additionalFilters | `array` Policy information for the data source, including `customWhere`, `differentialPrivacy`, `eventTimeColumn`, `minimization`, `time`, `filterSeconds`, and `isOlderOrNewer`. | | allowMaskedJoins | `boolean` If `true` the data source allows masked joins. | | policySet | `array` Details about the policies on the data source. | #### Request example The following request gets all of the visibility information for the current user on the data source with the data source ID `16`. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/16/visibilityReport ``` #### Response example ```json { "noVisibilities": true, "dataSourceVisibilitiesCount": 0, "userVisibilitiesCount": 0, "masked": [ { "type": "Consistent Value", "metadata": { "constant": null }, "name": "WS_SOLD_DATE_SK" }, { "type": "Consistent Value", "metadata": { "constant": null }, "name": "WS_BILL_CUSTOMER_SK" } ], "dataSource": 16, "dataSourceName": "Web Sales", "additionalFilters": {}, "allowMaskedJoins": false, "policySet": "[{\"type\":\"masking\",\"rules\":[{\"type\":\"masking\",\"config\":{\"fields\":[\"WS_BILL_CUSTOMER_SK\"],\"maskingConfig\":{\"type\":\"Consistent Value\",\"metadata\":{\"constant\":null}}},\"exceptions\":null,\"ruleAppliedForUser\":true}],\"global\":{\"id\":9,\"tag\":\"Confidential\",\"live\":true,\"name\":\"Data Policy\",\"reason\":null,\"staged\":false,\"deleted\":false,\"conflict\":null,\"disabled\":false,\"metadata\":null,\"template\":false,\"createdAt\":\"2022-08-09T17:23:02.634Z\",\"createdBy\":\"jane\",\"policyKey\":\"Data Policy\",\"updatedAt\":\"2022-08-09T17:23:02.634Z\",\"clonedFrom\":null,\"certification\":null,\"createdByName\":\"jane\",\"changedOnApply\":[\"dataTypeMismatch\"],\"parentPolicyId\":null,\"systemGenerated\":false,\"originalPolicyId\":\"masking(^_^)data policy(^_^)ws_bill_customer_sk(^_^)consistent value(^_^)(^_^)(^_^)\",\"ownerRestrictions\":null},\"description\":null,\"policyHash\":\"3a2faac13e332cca1829ed773afa298a5455ac5bb54e68c53ae00991575d2a4b\"},{\"type\":\"masking\",\"rules\":[{\"type\":\"masking\",\"config\":{\"fields\":[\"WS_SOLD_DATE_SK\"],\"maskingConfig\":{\"type\":\"Consistent Value\",\"metadata\":{\"constant\":null}}},\"exceptions\":null,\"ruleAppliedForUser\":true}],\"global\":{\"id\":9,\"tag\":\"Confidential\",\"live\":true,\"name\":\"Data Policy\",\"reason\":null,\"staged\":false,\"deleted\":false,\"conflict\":null,\"disabled\":false,\"metadata\":null,\"template\":false,\"createdAt\":\"2022-08-09T17:23:02.634Z\",\"createdBy\":\"jane\",\"policyKey\":\"Data Policy\",\"updatedAt\":\"2022-08-09T17:23:02.634Z\",\"clonedFrom\":null,\"certification\":null,\"createdByName\":\"jane\",\"changedOnApply\":[\"dataTypeMismatch\"],\"parentPolicyId\":null,\"systemGenerated\":false,\"originalPolicyId\":\"masking(^_^)data policy(^_^)ws_sold_date_sk(^_^)consistent value(^_^)(^_^)(^_^)\",\"ownerRestrictions\":null},\"description\":null,\"policyHash\":\"2877a1ace4cfa6427370fd39b254ce0ea75dc22cb024a2f857e033c82a987f9a\"}]" } ``` ## Access data sources and make data source requests
MethodPathPurpose
POST/dataSource/subscribeSubscribe to a data source.
POST/dataSource/{dataSourceId}/accessAdd a user to a specific data source.
### Subscribe to a data source `POST` `/dataSource/subscribe` Subscribe to a data source. #### Query parameters | Attribute | Description | Required | | ------------ | -------------------------------- | -------- | | dataSourceId | `integer` Data source ID number. | **Yes** | #### Payload parameters | Attribute | Description | Required | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | dataSourceIds | `array` The ID of the data source the user is subscribing to. | No | | approvals | `array` Includes details about the Subscription policy on the data source: `requiredPermissions`, `specificApproverRequired`, `specificApprover`, and `ownerModelId`. | No | #### Response schema | Attribute | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | body | `array` Contains details about the data source, including the data source ID, subscription status of the user, the profile ID of the user, and the dates the data source was created and updated. | #### Request example The following request subscribes to the data source with ID `22`. ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://your-immuta-url.com/dataSource/subscribe?dataSourceId=22 ``` **Payload example** ```json { "dataSourceIds": [ 22 ], "metadata": {}, "approvals": [ { "requiredPermission": "Owner", "specificApproverRequired": false, "specificApprover": 2, "ownerModelId": 23 } ], "groupId": 12 } ``` #### Response example ```json { "inError": [], "success": [{ "id": 64, "modelId": "22", "modelType": "datasource", "state": "subscribed", "metadata": {}, "admin": null, "denialReasoning": null, "profile": 2, "group": null, "expiration": null, "acknowledgeRequired": false, "createdAt": "2021-08-26T16:36:09.587Z", "updatedAt": "2021-08-26T16:36:09.587Z", "approved": true }] } ``` ### Add a user to a data source `POST` `/dataSource/{dataSourceId}/access` Add a user to a specific data source. Requestors cannot add themselves to a data source. To request access to a data source, [use the `/dataSource/subscribe` endpoint](#subscribe-to-a-data-source). **Required**: The global `GOVERNANCE` permission or be the data source owner #### Query parameters | Attribute | Description | Required | | ------------ | ----------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | #### Payload parameters | Attribute | Description | Required | | ---------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | | state | `string` The status of the user: `subscribed`, `owner`, `expert`, or `ingest`. | **Yes** | | profileId | `integer` The profile ID of the user being added to the data source. | **Yes** | | groupId | `integer` The ID of the group being added to the data source. | No | | approvals | `array` Details about the user approving access: `requiredPermission`, `specificApproverRequired`, and `specificApprover`. | No | | expiration | `date` The date the user's data source subscription ends. | No | #### Response schema | Attribute | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | `integer` The user's subscription ID. | | modelId | `integer` The model ID. | | modelType | `string` The Immuta component to add the user to: `datasource` or `project`. | | state | `string` The user's data source role, such as `subscribed`. | | denialReasoning | `string` If the user was denied access, the reason for denial. | | profile | `integer` The user's profile ID. | | group | `integer` If a group was added, the group ID. | | expiration | `date` The date the user's subscription to the data source will expire. | | acknowledgeRequired | `boolean` If the data source is associated with a project, this value will be `true` if the user needs to confirm they have read the project acknowledgement. | | createdAt | `timestamp` The date and time of creation. | | updatedAt | `timestamp` The date and time of update. | | approved | `boolean` When `true`, the user's request has been approved. | #### Request example The following request adds a user (saved in `example-payload.json`) to this data source. ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://your-immuta-url.com/dataSource/22/access ``` **Request payload example** ```json { "profileId": 3, "state": "subscribed" } ``` #### Response example ```json { "id": 19, "modelId": "1", "modelType": "datasource", "state": "subscribed", "metadata": null, "admin": 2, "denialReasoning": null, "profile": 3, "group": null, "expiration": null, "acknowledgeRequired": false, "createdAt": "2021-09-21T14:24:12.528Z", "updatedAt": "2021-09-21T14:24:12.528Z", "approved": true } ``` ## Manage data source requests
MethodPathPurpose
GET/dataSource/tasks/pendingGet all pending tasks for this user and pending tasks this user has created.
GET/dataSource/{dataSourceId}/tasksReturns all tasks the user has made, can approve or deny, or validate for this data source.
PUT/dataSource/{dataSourceId}/access/{id}Change user status for a specific data source.
### Get pending tasks by user `GET` `/dataSource/tasks/pending` Get all pending tasks for this user and pending tasks this user has created. #### Query parameters | Attribute | Description | Required | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | searchText | `string` If specified, will filter results using the specified string. | No | | searchModel | `string` Will filter the results by model type: `dataSource` or `schemaEvolution`. | No | | offset | `integer` The number of results to skip (for paging). | No | | size | `integer` The number of results to return per page. | No | | schemaEvolutionConnectionString | `string` The schema evolution connection string to filter by. | No | | countBySchemaEvolution | `boolean` If`true`, will only return the number of tasks, grouped by schema evolution. | No | | countByDataSource | `boolean` If`true`, will only return the number of tasks, grouped by data source. | No | | countOnly | `boolean` When `true`, will only return a count of the pending tasks. | No | | groupByDataSource | `boolean` If `true`, will return the results as an array of `{ dataSourceId: , rows: }`. | No | | types | `Array[string]` Filters the results by the type of task: `dataSourceCreated`, `columnAdded`, `columnDeleted`, or `columnTypeChanged`. The `dataSourceCreated`, `columnAdded`, `columnDeleted`, and `columnTypeChanged` tasks are only created if a policy that contains the `New` tag is active and [schema monitoring](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-metadata/schema-monitoring/reference-guides/schema-monitoring#data-source-requests) or [object sync](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/connections-overview#data-source-requests) identifies a change in the remote platform. | No | #### Response schema | Attribute | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------- | | outgoing | `array` Includes details of the tasks or requests created by the user, such as the `count`, `type`, and `targetEmails`. | | incoming | `array` Includes details about the tasks received by the user, such as the `count`, `type`, and `targetEmails`. | #### Request example The following request gets all pending tasks for a user and pending tasks the user has created. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/tasks/pending ``` #### Response example ```json { "outgoing": [], "incoming": [{ "fullCount": 1, "dataSource": { "id": 11, "name": "Public Customer" }, "isOutgoing": false, "rows": [{ "id": 1, "state": "pending", "type": "columnAdded", "reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Customer\"", "targetNames": [ "Katie" ], "targetEmails": [ "katie@immuta.com" ], "requester": { "name": "Immuta System Account", "id": 1, "email": null }, "dataSource": { "id": 11, "name": "Public Customer" }, "createdAt": "2024-08-06T14:37:09.279+00:00", "metadata": { "colName": "org", "colType": "VARCHAR(16777216)" }, "isOutgoing": false }] }] } ``` ### Return tasks for a data source `GET` `/dataSource/{dataSourceId}/tasks` Returns all tasks the user has made, can approve or deny, or validate for this data source. #### Query parameters | Attribute | Description | Required | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | | states | `Array[string]` The state of the tasks: `pending` or `completed`. | No | | targetProfileId | `integer` Only returns tasks where the target user has this profile ID. | No | | requestingUserProfileId | `integer` Only returns tasks where the requesting user has this profile ID. | No | | profileId | `integer` Returns tasks where either the target or requesting user has this profile ID. | No | | searchText | `string` A string used to filter returned users. The query is executed with a wildcard prefix and suffix. | No | | searchModel | `string` A string used to determine how results should be filtered using searchText. | No | | types | `Array[string]` The type of task: `dataSourceCreated`, `columnAdded`, `columnDeleted`, or `columnTypeChanged`. The `dataSourceCreated`, `columnAdded`, `columnDeleted`, and `columnTypeChanged` tasks are only created if a policy that contains the `New` tag is active and [schema monitoring](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-metadata/schema-monitoring/reference-guides/schema-monitoring#data-source-requests) or a [object sync](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/connections-overview#data-source-requests) identifies a change in the remote platform. | No | | size | `integer` The number of results to return. | No | | offset | `integer` The number of results to skip (for paging). | No | | sortField | `string` The field by which to sort the result set. | No | | sortOrder | `string` The order in which to sort the results. **The default is `desc`.** | No | | countOnly | `boolean` If `true`, will only return the number of tasks. | No | #### Response schema | Attribute | Description | | --------- | --------------------------------------------------------------------------------------------- | | hits | `array` Includes details about each task, such as the `id`, `state`, `type`, and `requestor`. | | count | `integer` The total number of tasks. | #### Request example The following request returns all tasks the user has made, can approve or deny, or validate for this data source. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/23/tasks?sortOrder=desc ``` #### Response example ```json { "hits": [ { "fullCount": 2, "id": 6, "state": "completed", "type": "columnAdded", "reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Customer\"", "targetNames": [ "John" ], "targetEmails": [ "john@example.com" ], "requester": { "name": "Immuta System Account", "id": 1, }, "dataSource": { "id": 11, "name": "Public Customer" }, "createdAt": "2021-10-12T15:48:23.095Z" }, { "fullCount": 2, "id": 7, "state": "completed", "type": "columnAdded", "reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Fake Medical Claims 2017\"", "targetNames": [ "John" ], "targetEmails": [ "john@example.com" ], "requester": { "name": "Immuta System Account", "id": 1 }, "dataSource": { "id": 3, "name": "Public Fake Medical Claims 2017" }, "createdAt": "2021-10-12T18:56:22.954Z" } ], "count": 2 } ``` ### Change user status `PUT` `/dataSource/{dataSourceId}/access/{subscriptionId}` Change user status for a specific data source. Requestors cannot update their own status for a data source. **Required**: The global `GOVERNANCE` permission or be the data source owner #### Query parameters | Attribute | Description | Required | | -------------- | --------------------------------------------------- | -------- | | dataSourceId | `Integer` The data source ID. | **Yes** | | subscriptionId | `Integer` The data source member's subscription ID. | **Yes** | #### Payload parameters | Attribute | Description | Required | | --------- | ---------------------------------------------------------------------------------- | -------- | | state | `string` The new status for the user: `subscribed`, `owner`, `expert` or `ingest`. | **Yes** | #### Response schema | Attribute | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | id | `integer` The data source member's subscription ID. | | modelId | `integer` The model ID. | | modelType | `array` The Immuta component the user's subscription is updated for: `datasource` or `project`. | | state | `array` The current state of the user's role: `subscribed`, `owner`, `expert`, or `ingest`. | | profile | `integer` The profile ID. | | group | `integer` If a group's status is being updated, this is the group ID. | | expiration | `timestamp` The date the user will no longer have access to the data source. | | acknowledgeRequired | `boolean` This attribute is specific to projects. When `true` the user needs to confirm they have read the project acknowledgement statement. | | createdAt | `timestamp` The date and time created. | | updatedAt | `timestamp` The date and time updated. | | originalState | `array` The user's previous status for the data source. | | approved | `boolean` If `true`, the status is approved. | #### Request example The following request changes the user status to `subscribed` for the specified data source. ```bash curl \ --request PUT \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://your-immuta-url.com/dataSource/23/access/95 ``` **Payload example** ```json { "state": "subscribed" } ``` #### Response example ```json { "id": 95, "modelId": "3", "modelType": "datasource", "state": "subscribed", "metadata": {}, "admin": 2, "profile": 3, "group": null, "expiration": null, "acknowledgeRequired": false, "createdAt": "2021-10-12T15:40:13.878Z", "updatedAt": "2021-10-12T16:10:46.801Z", "originalState": "expert", "approved": true } ``` ## Update data sources
MethodPathPurpose
PUT/dataSource/{dataSourceId}Update a data source.
PUT/dataSource/bulk/{type}Update multiple data sources.
POST/dataSource/bulkRefreshViewsRefresh the data policies and grants for a data source in the remote data platform.
PUT/dataSource/detectRemoteChangesTrigger the schema monitoring job for the specified detection group, or all groups if no ID is given.
### Update a data source `PUT` `/dataSource/{dataSourceId}` Update a data source. **Required**: The global `GOVERNANCE` permission or be the data source owner #### Query parameters | Attribute | Description | Required | | ------------ | ----------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | #### Payload parameters | Attribute | Description | Required | | --------------- | -------------------------------------------------------------------------------------------------------------------- | -------- | | blobHandler | `array[object]` A list of full URLs providing the locations of all blob store handlers to use with this data source. | No | | blobHandlerType | `string` Describes the type of underlying blob handler that will be used with this data source (e.g., `MS SQL`). | No | | recordFormat | `string` The data format of blobs in the data source, such as `json`, `xml`, `html`, or `jpeg`. | No | | type | `string` The type of data source: `queryable` (metadata is dynamically queried). | No | | name | `string` The name of the data source. It must be unique within the Immuta tenant. | No | | sqlTableName | `string` A string that represents this data source's table in Immuta. | No | | organization | `string` The organization that owns the data source. | No | | category | `string` The category of the data source. | No | | description | `string` The description of the data source. | No | | hasExamples | `boolean` When `true`, the data source contains examples. | No | #### Response schema | Attribute | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | private | `boolean` When `false`, the data source will be publicly available in the Immuta UI. | | blobHandler | `array[object]` A list of full URLs providing the locations of all blob store handlers to use with this data source. | | blobHandlerType | `string` Describes the type of underlying blob handler that will be used with this data source (e.g., `MS SQL`). | | recordFormat | `string` The data format of blobs in the data source, such as `json`, `xml`, `html`, or `jpeg`. | | type | `string` The type of data source: `queryable` (metadata is dynamically queried). | | name | `string` The name of the data source. It must be unique within the Immuta tenant. | | sqlTableName | `string` A string that represents this data source's table in Immuta. | | organization | `string` The organization that owns the data source. | | description | `string` The description of the data source. | | policyHandler | `array` The ID of the policy handler and details about the data policies enforced on the data source. | | subscriptionPolicy | `array` Details about the subscription policy enforced on the data source, including the type of policy and exceptions. | #### Request example The following request updates the data source's name (saved in `example-payload.json`). ```bash curl \ --request PUT \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://your-immuta-url.com/dataSource/22 ``` **Request payload example** ```json { "name": "Public Credit Accounts for Training" } ``` #### Response example ```json { "name": "Public Credit Accounts for Training", "recordFormat": "Not Provided", "description": null, "policyHandler": { "handlerId": 21, "visibilitySchema": { "fields": [], "version": "2021-09-15T17:44:20.678Z" }, "previousHandlerId": 20, "dataSourceId": 1 }, "sqlSchemaName": "public", "sqlTableName": "credit_accounts", "blobHandler": { "url": "https://1.1.1.1:1111/snowflake/handler/1", "ca": { "name": "Certificate Authority Bundle" }, "manualDictionary": false }, "createdBy": 2, "deleted": false, "type": "queryable", "recordCount": 0, "rowCount": "100000", "statsExpiration": "2021-09-22T13:51:46.646Z", "id": 1, "blobHandlerType": "Snowflake", "policyHandlerType": "Builder", "subscriptionType": "approval", "subscriptionPolicy": { "type": "subscription", "approvals": [{ "requiredPermission": "OWNER", "specificApproverRequired": false }] }, "globalPolicies": null, "status": "failed", "statusInfo": { "sql": { "status": "passed", "message": "Passed" }, "stats": { "status": "passed", "lastAttempted": "2021-09-21T13:51:46.674Z" }, "fingerprint": { "status": "passed", "lastAttempted": "2021-09-09T14:12:25.177Z" }, "lastAttempt": { "date": "2021-09-20T19:35:21.929Z" }, "globalPolicy": { "status": "passed", "lastAttempted": "2021-09-17T19:07:38.092Z" }, "highCardinality": { "status": "failed", "message": "Error could not connect to remote database", "lastAttempted": "2021-09-20T16:43:19.426Z" } }, "expiration": null, "catalogMetadata": null, "workspace": null, "seeded": false, "schemaEvolutionId": 1, "columnEvolutionEnabled": true, "createdAt": "2021-09-09T14:12:09.511Z", "updatedAt": "2021-09-21T13:52:42.908Z" } ``` ### Update multiple data sources `PUT` `/dataSource/bulk/{type}` Update data sources. **Required**: The global `GOVERNANCE` permission or be the data source owner for all data sources included in the payload #### Query parameters | Attribute | Description | Required | | --------- | ----------------------------------------------------------------------------------------------------------- | -------- | | type | `string` The action to perform on the data sources: `add-users`, `disable`, `restore`, `delete`, or `tags`. | **Yes** | #### Payload parameters | Attribute | Description | Required | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | ids | `array[integer`] The IDs of the data sources to update. | **Yes** | | update | `array[object]` Only required for `add-users` (includes metadata about the users' `profiles`: `id` and `state`) and `tags` (includes metadata about the `tags`: `name` and `source`) types. | No | #### Response schema | Attribute | Description | | ----------- | ----------------------------------------------- | | bulkId | `string` The ID of the bulk data source update. | | jobsCreated | `integer` The number of jobs created. | #### Request example The following request adds the `Address.email` tag to two data sources. ```bash curl \ --request PUT \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://your-immuta-url.com/dataSource/bulk/tags ``` **Payload example** ```json { "ids": [49, 50], "update": { "tags": [{ "name": "Address.email", "source": "curated" }] } } ``` #### Response example ```json { "bulkId": "bulk_ds_update_4896d300e04c4a8f89493ebf125c5c6b", "jobsCreated": 2 } ``` ### Resync data policies and grants `POST` `/dataSource/bulkRefreshViews` Refresh the data policies and grants for a data source in the remote data platform. **Required**: The global `GOVERNANCE` permission or be the data source owner for all data sources included in the payload #### Payload parameters | Attribute | Description | Required | | ------------- | ------------------------------------------------------- | -------- | | dataSourceIds | `array[integer]` The IDs of the data sources to update. | **Yes** | #### Request example The following request with the payload below refreshes the data policies and grants in the remote data platform for the data source with the ID 202. ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer " \ --data @example-payload.json \ https://your-immuta-url.com/dataSource/bulkRefreshViews ``` **Payload example** ```json { "dataSourceIds": [202] } ``` ### Trigger schema monitoring jobs `PUT` `/dataSource/detectRemoteChanges` Trigger the schema monitoring job for the specified detection group, or all groups if no payload parameters are given. **Required**: The global `GOVERNANCE` permission or be the data source owner for all data sources included in the payload #### Payload parameters | Attribute | Description | Required | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | dataSourceIds | `array[integer]` The data source IDs to run the column detection job on. Leave empty to run this job globally on all data sources. This parameter cannot be included in the payload if **schemaEvolutionId** or any combination of **hostname**, **database**, **port**, or **table** is included. | No | | hostname | `string` The hostname of the data sources. This parameter cannot be included in the payload if **dataSourceIds** or **schemaEvolutionId** is included. | No | | port | `integer` The port used to connect the data sources to Immuta. This parameter cannot be included in the payload if **dataSourceIds** or **schemaEvolutionId** is included. | No | | database | `string` The database name. This runs schema monitoring on the database provided. If data sources were initially registered via the V2 API, including this parameter will locate new schemas that contain tables Immuta has the ability to access, and Immuta will create a new schema project associated with these newly discovered schemas and create data sources for each table located. If data sources were initially registered via the V1 API, including this parameter will only update the columns and tables of registered schema and tables of the specified database; it will not register any new schemas. This parameter cannot be included in the payload if **dataSourceIds** or **schemaEvolutionId** is included. | No | | table | `string` The table name. This will run column detection to just update the columns in this table. This parameter cannot be included in the payload if **dataSourceIds** or **schemaEvolutionId** is included. | No | | schemaEvolutionId | `integer` The ID of the schema to run the schema monitoring job on. This will run on all tables associated with the specified ID. *The schema ID can be found in the response body of* [*`/dataSource/{dataSourceId}`*](#get-a-data-source-by-id)*.* This parameter cannot be included in the payload if **dataSourceIds** or any combination of **hostname**, **database**, **port**, or **table** is included. | No | | skipColumnDetection | `boolean` When `true`, Immuta will only pull new tables from the source server. This parameter can only be paired with **schemaEvolutionId**. | No | | overrides.httpPath | `string` If [Databricks ephemeral overrides](https://documentation.immuta.com/saas/configuration/integrations/databricks/databricks-spark/reference-guides/databricks/ephemeral-overrides) are configured, provide the alternative HTTP path to trigger schema monitoring on that ephemeral cluster. | No | #### Response schema | Attribute | Description | | --------------- | ------------------------------------------------------------------------------------------ | | schemaDetection | `object` Includes details about the resulting schema detection jobs. | | columnDetection | `object` Includes details about the resulting column detection jobs. | | bulkId | `string` The unique identifier of the jobs running schema monitoring and column detection. | Responses may include `bulkId`, `schemaDetection`, or `columnDetection` objects, depending on the payload. #### Request example The following request triggers the schema monitoring job for the specified detection group. ```bash curl \ --request PUT \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://your-immuta-url.com/dataSource/detectRemoteChanges ``` **Payload example** The tabs below illustrate payloads for triggering schema monitoring on a host, database, or table. The request will run schema monitoring for all databases registered under the hostname provided in the payload. {% tabs %} {% tab title="Host" %} The request will run schema monitoring for all databases registered under the hostname provided in the payload. ```json { "hostname": "organization.us-east-1.snowflakecomputing.com" } ``` {% endtab %} {% tab title="Database" %} The request will run schema monitoring on the database provided in the payload. If data sources were initially registered via the V2 API, this request will locate new schemas that contain tables Immuta has the ability to access, and Immuta will create a new schema project associated with these newly discovered schemas and create data sources for each table located. If data sources were initially registered via the V1 API, this request will only update the columns and tables of registered schema and tables of the specified database; it will not register any new schemas. ```json { "database": "public" } ``` {% endtab %} {% tab title="Table" %} The request will run column detection and update the columns on the table specified in the payload. ```json { "database": "public", "table": "healthcare" } ``` {% endtab %} {% endtabs %} #### Response examples The tabs below illustrate the example response for each example payload provided above. {% tabs %} {% tab title="Host" %} ```json { "bulkId": "31ab4312-b90a-49a6-baf8-70f87cd92a89" } ``` {% endtab %} {% tab title="Database" %} ```json { "bulkId": "5d129011-6254-413d-a365-6e394c06e277" } ``` {% endtab %} {% tab title="Table" %} ```json { "bulkId": "5d129011-6254-413d-a365-6e394c06e277", "schemaDetection": { "jobs": ["7d129033-6254-413d-a345-9o3242c06f242"] }, "columnDetection" : { "jobs": ["8d129033-6254-413d-a345-9o3123c06f123"] } } ``` {% endtab %} {% endtabs %} ## View and Review Data Sources
MethodPathPurpose
GET/dataSource/{dataSourceId}/testRefresh tags from an external catalog on a data source. The external catalog must be linked to the data source.
GET/dataSource/blobHandlerTypesRetrieve all blob handlers the current user is allowed to create.
GET/dataSource/byPurposesGet data sources that match a set of purposes.
GET/dataSource/rpc/mineRetrieve all the data sources the current user has access to.
GET/dataSource/{dataSourceId}/activitiesGet all of the recent policy activities for a given data source.
GET/dataSource/{dataSourceId}/contactsGet the profiles for the data source owners and experts.
GET/dataSource/{dataSourceId}/tagsGet the tags for a data source.
### Refresh data source health checks `GET` `/dataSource/{dataSourceId}/test` Refreshes the data source health checks. **Required**: The global `GOVERNANCE` permission or be the data source owner #### Query parameters | Attribute | Description | Required | | ------------ | ----------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | #### Response schema | Attribute | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | blob | `object` Indicates whether or not the blob was successfully crawled. | | columnEvolution | `object` Indicates whether or not the job run to check for columns added or removed from the data source `passed` and when it was last run. | | externalCatalog | `object` Indicates whether or not the external catalog was successfully linked to the data source. | | fingerprint | `object` Indicates whether or not the fingerprint job was successful (`passed`) and when it was last run. The fingerprint captures summary statistics of a Snowflake data source. | | framework | `object` Indicates whether or not the classification was successfully run on the data source to determine its sensitivity. | | globalPolicy | `object` Indicates whether or not global policies were successfully applied to the data source. | | highCardinality | `object` Indicates whether or not the job run to calculate the data source's high cardinality column `passed` and when it was last run. | | schemaEvolution | `object` Indicates whether or not the job run to check if a new table had been added in the remote database `passed` and when it was last run. If a new table was added, Immuta automatically creates a new data source. Correspondingly, if a remote table is removed, that data source will be disabled in the console. | | sdd | `object` Indicates whether or not identification was successfully run on the data source. | | sql | `object` Indicates whether or not the SQL query run to check the data source's health `passed` and when it was last run. | | stats | `object` Indicates whether or not the job run to calculate the number of rows in the data source `passed` and when it was last run. | #### Request example The following request refreshes external catalog tags on the data source. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/23/test ``` #### Response example ```json { "sql": { "status": "passed", "message": "Passed" }, "stats": { "status": "passed", "lastAttempted": "2021-09-09T13:43:43.948Z" }, "fingerprint": { "status": "passed", "lastAttempted": "2021-07-22T14:12:01.525Z" }, "lastAttempt": { "date": "2021-09-09T16:47:05.173Z" }, "columnEvolution": { "status": "passed", "lastAttempted": "2021-09-08T16:36:05.557Z" }, "highCardinality": { "status": "passed", "lastAttempted": "2021-07-22T14:11:58.439Z" }, "schemaEvolution": { "status": "passed", "lastAttempted": "2021-09-08T16:35:57.867Z" }, "status": "passed" } ``` ### Retrieve blob handlers `GET` `/dataSource/blobHandlerTypes` Retrieve all blob handlers the current user is allowed to create. #### Response schema | Attribute | Description | | --------- | ---------------------------------------------------------------- | | name | `string` The name of the blob handler. | | baseUrl | `string` The base URL for the data source. | | config | `array` Includes information about the connection configuration. | | port | `integer` The port number. | | driver | `string` The name of the driver. | #### Request example The following request retrieves all blob handlers the current user is allowed to create. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/blobHandlerTypes ``` #### Response example ```json { "name": "Azure Synapse Analytics", "pluginType": "queryable", "clientUrl": "/asa", "baseUrl": "https://0.0.0.0:8823/asa", "config": { "port": 1433, "allowSSLToggle": false }, "displayOrder": 41, "requiresHashPhraseForDP": true, "driver": "Azure Synapse Analytics" } ``` ### Get data sources by purpose `GET` `/dataSource/byPurposes` Get data sources that match a set of purposes. #### Query parameters | Attribute | Description | Required | | ---------------- | ----------------------------------------------------------------------------- | -------- | | purposes | `array[string]` The purposes to filter the data sources by. | **Yes** | | excludedProjects | `array[integer]` Excludes data sources associated with specified project IDs. | No | #### Response schema | Attribute | Description | | ------------ | ------------------------------------------------------------------------ | | id | `integer` The data source ID. | | name | `array` The name of the data source. | | policyId | `integer` The policy ID. | | restrictions | `array` Details regarding the `operator` (`and` or `or`) and `purposes`. | #### Request example The following request gets data sources that match a set of purposes. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/byPurposes?purposes=Data+Analysis ``` #### Response example ```json [{ "id": 42, "name": "Army Army Records", "policyId": 56, "restrictions": [{ "operator": "and", "purposes": ["Data Analysis"] }] }] ``` ### Retrieve data sources by user `GET` `/dataSource/rpc/mine` Retrieves all the data sources the current user has access to. #### Response schema | Attribute | Description | | --------------- | -------------------------------------------------- | | id | `integer` The data source ID. | | name | `string` The data source name. | | type | `string` The type of data source: `queryable`. | | sqlTableName | `string` The name of the table in Immuta. | | sqlSchemaName | `string` The name of the schema in Immuta. | | blobHandlerType | `string` The type of handler, such as `Snowflake`. | | sparkUseJDBC | `boolean` When `true`, uses a JDBC driver. | #### Request example The following request retrieves all the data sources the current user has access to. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/rpc/mine ``` #### Response example ```json { "id": 23, "name": "Public Record", "type": "queryable", "sqlTableName": "record", "sqlSchemaName": "public", "blobHandlerType": "Snowflake", "sparkUseJDBC": true } ``` ### Get recent policy activities for a data source `GET` `/dataSource/{dataSourceId}/activities` Get all of the recent policy activities for a given data source. **Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy #### Query parameters | Attribute | Description | Required | | ------------ | ----------------------------------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | | offset | `integer` The number of results to skip (for paging). | No | | size | `integer` The number of results to return per page. | No | #### Response schema | Attribute | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | count | `integer` The number of results. | | activities | `array` Includes details about the policy and the data source, including the policy and data source type, when the activity notification was triggered, and whether or not the policy change was triggered by a Global policy. | | actionBy | `array` Details about who triggered the action. | | targetUser | `array` Information about the user who received the notification. | #### Request example The following request gets all of the recent policy activities for a given data source. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/23/activities ``` #### Response example ```json { "count": 3, "activities": [{ "modelType": "datasource", "modelId": "23", "createdAt": "2021-09-07T16:13:25.197Z", "notificationType": "policyUpdated", "metadata": { "dataSourceName": "Public Foobar", "triggeredByGlobal": false, "conflictCount": 0, "policyType": "data", "handlerId": 3, "previousHandlerId": 2, "dataSourceType": "queryable" }, "read": false, "id": 256, "updatedAt": "2021-09-07T16:13:25.197Z", "actionBy": { "id": 2, "name": "first last", "email": "first.last@immuta.com" }, "targetUser": { "id": 2, "name": "first last", "email": "first.last@immuta.com" } }] } ``` ### Get profiles for data source owners and experts `GET` `/dataSource/{dataSourceId}/contacts` Gets the profiles for the data source owners and experts. #### Query parameters | Attribute | Description | Required | | ------------ | ----------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | #### Response schema | Attribute | Description | | --------- | ---------------------------------------------------------------------- | | id | `integer` The data source ID. | | state | `string` The user's data source role, such as `owner` or `subscribed`. | | name | `string` The user's name. | | email | `string` The user's email. | | profile | `integer` The user's profile ID. | #### Request example The following request gets all the profiles for the data source owners and experts. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/23/contacts ``` #### Response example ```json { "type": "profile", "id": 23, "state": "owner", "name": "first last", "email": "first.last@immuta.com", "profile": 2 }, { "type": "profile", "id": 23, "state": "owner", "name": "Tommy Test", "email": "tommy.test@immuta.com", "profile": 3 } ``` ### Get tags by data source `GET` `/dataSource/{dataSourceId}/tags` Get the tags for a data source. **Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy #### Query parameters | Attribute | Description | Required | | ------------ | --------------------------------------------------------------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | | blobId | `string` Returns the tags for the specified blob. | No | | blobTagsOnly | `boolean` When `true`, will only display blob tags associated with a data source. | No | #### Response schema | Attribute | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------ | | tags | `array` Includes details about the tags, such as the `name`, `source`, and the profile ID of the user who added the tag. | #### Request example The following request gets the tags for data source `4`. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/4/tags ``` #### Response example ```json { "tags": [ { "name": "Discovered.Entity.Medicare Number", "source": "curated", "modelType": "datasource", "modelId": "4", "addedBy": 1, "deleted": false } ] } ``` ## Delete Data Sources and More
MethodPathPurpose
DELETE/dataSource/{dataSourceId}Delete a data source. This will perform a soft delete on the first call and a hard delete the second time.
DELETE/dataSource/tasks/{taskId}Delete the specified task.
DELETE/dataSource/{dataSourceId}/unsubscribeUnsubscribe from a data source.
### Delete a data source `DELETE` `/dataSource/{dataSourceId}` Delete a data source. This will perform a soft delete on the first call and a hard delete the second time. **Required**: The global `GOVERNANCE` permission or be the data source owner #### Query parameters | Attribute | Description | Required | | ------------ | ----------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | #### Response schema | Attribute | Description | | ------------------------- | ------------------------------------------------------------------------------------- | | success | `boolean` If `true`, the request to disable or delete the data source was successful. | | id | `integer` The data source ID. | | schemaEvolutionId | `integer` The schema evolution ID. | | name | `string` The data source name. | | disabled | `boolean` If `true`, the data source is disabled. | | handlerDeleteErrorMessage | `string` The delete error message. | #### Request example The following request deletes the data source `23`. ```bash curl \ --request DELETE \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/23 ``` #### Response example ```json { "success": true, "id": 23, "schemaEvolutionId": 1, "name": "Public Foobar", "disabled": true, "handlerDeleteErrorMessage": null } ``` ### Delete a task `DELETE` `/dataSource/tasks/{taskId}` Delete the specified task. #### Query parameters | Attribute | Description | Required | | --------- | ------------------------- | -------- | | taskId | `integer` Target task ID. | **Yes** | #### Response schema | Attribute | Description | | ------------ | --------------------------------------------------------- | | id | `integer` The deleted task ID. | | state | `array` The state of the deleted task, such as `pending`. | | type | `array` The type of deleted task, such as `columnAdded`. | | targetNames | `string` The name of the user who received the request. | | targetEmails | `string` The email of the user who received the request. | | requester | `metadata` Details regarding the requesting profile. | | dataSource | `metadata` details regarding the data source. | | metadata | `array` Details about the deleted task. | #### Request example The following request deletes a specified task. ```bash curl \ --request DELETE \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/tasks/8 ``` #### Response example ```json { "fullCount": 1, "id": 8, "state": "pending", "type": "columnAdded", "reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Customer\"", "targetNames": ["Katie"], "targetEmails": ["katie@example.com"], "requester": { "name": "Immuta System Account", "id": 1 }, "dataSource": { "id": 11, "name": "Public Customer" }, "createdAt": "2021-10-12T19:28:04.999Z" } ``` ### Unsubscribe from a data source `DELETE` `/dataSource/{dataSourceId}/unsubscribe` Unsubscribe from a data source. #### Query parameters | Attribute | Description | Required | | ------------ | ----------------------------- | -------- | | dataSourceId | `integer` The data source ID. | **Yes** | #### Response schema | Attribute | Description | | --------- | ------------------------------------------------------------------------------ | | status | `boolean` If `true`, the requesting user is unsubscribed from the data source. | #### Request example The following request unsubscribes the user from data source `23`. ```bash curl \ --request DELETE \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://your-immuta-url.com/dataSource/23/unsubscribe ``` #### Response example ```json { "success": true } ``` [^1]: It's possible for you to be authorized to see data sources you are not subscribed to, as long as you meet the conditions in the policy on the data source and it is publicly visible. For example, if a policy allows anyone to manually subscribe to the data source but you have not manually subscribed to it yet, then you are authorized to see the data source and it will appear in the response.