Data API reference guide
This page details the /data
v1 API, which allows users to connect a host to Immuta with a single set of credentials rather than configuring an integration and registering data sources separately. For a how-to on connecting a host, see the Connect a host reference guide.
GET
/data/connection/{connectionKey}
Search for a host using a connection key.
Required Immuta permission: CREATE_DATA_SOURCE
, APPLICATION_ADMIN
, or INFRASTRUCTURE_ADMIN
or DATA_OWNER
within the hierarchy
GET
/data/object/{objectPath}
Search for a specific data object using the object path.
Required Immuta permission: CREATE_DATA_SOURCE
, APPLICATION_ADMIN
, or INFRASTRUCTURE_ADMIN
or DATA_OWNER
within the hierarchy
POST
/data/object/search/{objectPath}
Search for the children of the object defined in the objectPath. Or search all top-level data objects (hosts) if the objectPath is omitted.
Required Immuta permission: CREATE_DATA_SOURCE
, APPLICATION_ADMIN
, or INFRASTRUCTURE_ADMIN
or DATA_OWNER
within the hierarchy
PUT
/data/connection/{connectionKey}
Update the connection information for the specified host. Partial updates are not supported.
Required Immuta permission: INFRASTRUCTURE_ADMIN
on the host
Test run
Opt to test and validate the update connection payload using a dry run:
PUT
/data/connection/{connectionKey}/test
The connection parameters differ based on your backing technology. See the Data payloads reference guide for details about the payloads.
PUT
/data/crawl/{objectPath}
Trigger an ad hoc crawl starting at the specified object. Note: A crawl cannot happen at the table level.
Required Immuta permission: INFRASTRUCTURE_ADMIN
or DATA_OWNER
on the object
PUT
/data/settings/{objectPath}
Update the settings through overrides for the specified data object. All changes will trickle down to child objects as new overrides; however, existing overrides on child objects will still be respected. Data owners and infrastructure admins cannot be removed, only added. To remove data owners and infrastructure admins, edit the settings at the host level.
Required Immuta permission: INFRASTRUCTURE_ADMIN
on the object
DELETE
/data/object/{objectPath}
Delete the given object and all its child objects. For example, if you delete a database, all its schemas and tables will also be deleted.
Required Immuta permission: INFRASTRUCTURE_ADMIN
or DATA_OWNER
on the object
To disconnect a host from Immuta, you can do the following:
Optionally, generate a script in Databricks or Snowflake to clean up any Immuta-managed resources from your environment.
Delete the host connection in Immuta.
Run the script in Databricks or Snowflake to clean up any Immuta-managed resources from your environment.
POST
/integrations/{id}/scripts/delete
Creates a script to remove Immuta-managed resources from your platform.
Required Immuta permission: APPLICATION_ADMIN
The response returns the script that you will run in your Databricks Unity Catalog or Snowflake environment.
DELETE
/data/object/{connectionKey}
Delete the given host and all its child objects.
Required Immuta permission: INFRASTRUCTURE_ADMIN
or DATA_OWNER
on the object
Method | Endpoint | Description |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Desciription |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
GET
Search for a host using a connection key
GET
Search for a specific data object using the object path
POST
Search for the children of the object defined in the objectPath or search all top-level data objects (hosts) if the objectPath is omitted
PUT
Update the connection information for the specified host
PUT
Trigger an ad hoc crawl starting at the specified object
PUT
Update the settings through overrides for the specified data object
DELETE
Delete the given object and all its child objects
DELETE
Delete the given host and all its child objects
connectionKey string
The key to uniquely identify the host connection.
Yes
connectionKey string
The key to uniquely identify the host connection.
connection object
Integration-specific connection information (i.e., hostname, authentication type, warehouse, etc.)
createdAt timestamp
The time the host was connected to Immuta.
createdBy integer
The ID of the user who connected the host.
creator.id integer
The ID of the user who connected the host.
creator.name string
The name of the user who connected the host.
creator.email string
The email of the user who connected the host.
updatedAt timestamp
The time the host was updated in Immuta.
updatedBy integer
The ID of the user who updated the host.
updater.id integer
The ID of the user who updated the host.
updater.name string
The name of the user who updated the host.
updater.email string
The email of the user who updated the host.
nativeIntegrationId integer
The ID of the native integration backing the host.
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names should be separated by forward slashes (/
). For example, yourConnectionKey/yourDatabase/yourSchema
.
Yes
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names are separated by forward slashes.
technology string
The technology that the object comes from: Snowflake
or Databricks
.
state string
Whether the object is currently active
or inactive
.
settings array
Specifications of the host's settings, including active status, new children status, infrastructure admins, and data owners.
overrides array
Specifications of the data object's settings that differ from its parents' settings.
dataSourceId integer
The ID of the data source if it is a table object that is active.
createdAt timestamp
The time the data object was created in Immuta.
lastCrawled timestamp
The time the data object was last crawled during object sync.
remoteId string
The ID of the remote data object.
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names should be separated by forward slashes (/
). For example, yourConnectionKey/yourDatabase/yourSchema
.
Yes
sortField string
The field to sort the search results.
No
sortOrder string
Denotes whether to sort the results in ascending (asc
) or descending (desc
) order. Default is asc
.
No
offset integer
Use in combination with limit
to fetch pages.
No
limit integer
Limits the number of results displayed per page.
No
searchText string
A partial, case-insensitive search on name.
No
count integer
The number of results for your search.
hits.objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names are separated by forward slashes.
hits.technology string
The technology that the object comes from (i.e., Snowflake, Databricks, etc.).
hits.state string
Whether the object is currently active
or inactive
.
hits.settings array
Specifications of the host's settings, including active status, new children status, infrastructure admins, and data owners.
hits.overrides array
Specifications of the data object's settings that differ from its parents' settings.
hits.dataSourceId integer
The ID of the data source if it is a table object that is active.
hits.createdAt timestamp
The time the data object was created in Immuta.
hits.lastCrawled timestamp
The time the data object was last crawled during object sync.
hits.remoteId string
The ID of the remote data object.
connectionKey string
The key to uniquely identify the host connection.
Yes
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names are separated by forward slashes.
bulkId string
A bulk ID that can be used to search for the status of background jobs triggered by this request.
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names should be separated by forward slashes (/
). For example, yourConnectionKey/yourDatabase/yourSchema
.
Yes
forceRecursive boolean
If false
, only active objects will be crawled. If true
, both active and inactive data objects will be crawled; any child objects from inactive objects will be set as inactive. Defaults to false
.
No.
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names are separated by forward slashes.
bulkId string
A bulk ID that can be used to search for the status of background jobs triggered by this request.
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names should be separated by forward slashes (/
). For example, yourConnectionKey/yourDatabase/yourSchema
.
Yes
overrides array
A list of settings configured differently from the parent object's settings.
overrides.isActive boolean
If true
, the object and all its child objects are active.
overrides.activateNewChildren boolean
If true
, all new children found during object sync will be registered as active.
overrides.infrastructureAdmins array
A list of the users and groups that are infrastructure admins on the host. These users can crawl the host, edit the connection, and delete data objects.
overrides.infrastructureAdmins.id integer
The ID of the user or group to make infrastructure admin.
overrides.infrastructureAdmins.type string
The type to make infrastructure admin. Options are user
or group
.
overrides.dataOwners array
A list of users and groups that are data owners on the host. These users will be data owners for all the data sources under the data object they are assigned to.
overrides.dataOwners.id integer
The ID of the user or group to make data owner.
overrides.dataOwners.type string
The type to make data owner. Options are user
or group
.
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names should be separated by forward slashes.
technology string
The backing technology of the host. Options are Databricks
or Snowflake
.
state string
Whether the object is currently active
or inactive
.
settings array
Specifications of the host's settings, including active status, new children status, infrastructure admins, and data owners.
overrides array
Specifications of the data object's settings that differ from its parents' settings.
dataSourceId integer
The ID of the data source if it is a table object that is active.
createdAt timestamp
The time the data object was created in Immuta.
lastCrawled timestamp
The time the data object was last crawled during object sync.
remoteId string
The ID of the remote data object.
bulkId string
A bulk ID that can be used to search for the status of background jobs triggered by this request.
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names should be separated by forward slashes (/
). For example, yourConnectionKey/yourDatabase/yourSchema
.
Yes
objectPath string
The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey
and all names are separated by forward slashes.
childCount integer
The number of child objects of the data object that were deleted.
id integer
The integration ID.
Yes
connectionKey string
The key to uniquely identify the host connection.
Yes
connectionKey string
The key to uniquely identify the host connection.
childCount integer
The number of child objects of the data object that were deleted.