Manage a Host

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.

MethodEndpointDescription

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

POST

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

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

curl -X 'GET' \
  'https://your-immuta-url.com/data/connection/yourConnectionKey' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-bearer-token'

Path parameters

AttributeDescriptionRequired

connectionKey string

The key to uniquely identify the host connection.

Yes

Response schema

AttributeDescription

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.

Example response

{
  "connectionKey": "yourConnectionKey",
  "connection": {
    "port": 443,
    "role": "IMMUTA_SNOWFLAKE_ROLE",
    "hostname": "example.us-east-1.snowflakecomputing.com",
    "username": "IMMUTA_DB_SYSTEM_ACCOUNT",
    "warehouse": "your-warehouse",
    "technology": "Snowflake",
    "authenticationType": "userPassword"
  },
  "createdAt": "2023-12-22T18:28:46.328Z",
  "createdBy": 2,
  "updatedAt": "2023-12-22T18:28:46.328Z",
  "updatedBy": 2,
  "creator": {
    "id": 2,
    "name": "Taylor Smith",
    "email": "taylor@immuta.com"
  },
  "updater": {
    "id": 2,
    "name": "Taylor Smith",
    "email": "taylor@immuta.com"
  },
  "nativeIntegrationId": 1
}

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

curl -X 'GET' \
  'https://your-immuta-url.com/data/object/yourConnectionKey' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-bearer-token'

Path parameters

AttributeDescriptionRequired

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

Response schema

AttributeDesciription

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.

Example response

{
    "objectPath": ["yourConnectionKey"],
    "technology": "Snowflake",
    "state": "active",
    "settings": {
        "activateNewChildren": {
            "value": true,
            "hasDescendantsWithOverrides": false
        },
        "dataOwners": {
            "value": [
                {
                    "id": 2,
                    "type": "user"
                },
            ],
            "hasDescendantsWithOverrides": false
        },
        "infrastructureAdmins": {
            "value": [
                {
                    "id": 3,
                    "type": "group"
                }
            ],
            "hasDescendantsWithOverrides": false
        },
        "isActive": {
            "value": true,
            "hasDescendantsWithOverrides": false
        }
    },
    "overrides": [],
    "lastCrawled": 2023-08-21T10:39:00.250Z,
    "createdAt": 2023-08-21T10:39:00.250Z,
    "remoteId": null
}

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

curl -X 'POST' \
  'https://your-immuta-url.com/data/object/search/yourConnectionKey' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-bearer-token'

Path parameters

AttributeDescriptionRequired

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

Query parameters

AttributeDescriptionRequired

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

Response schema

AttributeDescription

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.

Example response

{
    "count": 1,
    "hits": [
        {
            "objectPath": ["yourConnectionKey"],
            "technology": "Snowflake",
            "state": "active",
            "settings": {
                "activateNewChildren": {
                    "value": true,
                    "hasDescendantsWithOverrides": false
                },
                "dataOwners": {
                    "value": [
                        {
                            "id": 2,
                            "type": "user"
                        },
                    ],
                    "hasDescendantsWithOverrides": false
                },
                "infrastructureAdmins": {
                    "value": [
                        {
                            "id": 3,
                            "type": "group"
                        }
                    ],
                    "hasDescendantsWithOverrides": false
                },
                "isActive": {
                    "value": true,
                    "hasDescendantsWithOverrides": false
                }
            },
            "overrides": [],
            "lastCrawled": 2023-08-21T10:39:00.250Z,
            "createdAt": 2023-08-21T10:39:00.250Z,
            "remoteId": null
        }
    ]
}

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

curl -X 'PUT' \
    'https://<your-immuta-url>/data/connection/yourConnectionKey' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
     connection: {
       technology: "Snowflake",
       hostname: "<your-Snowflake-hostname-url>",
       port: <your-Snowflake-port>,
       warehouse: "<your-Snowflake-warehouse>",
       role: "<your-Snowflake-role>",
       authenticationType: "userPassword",
       username: "<your-Snowflake-username>",
       password: "<your-Snowflake-password>",
     },
     settings: {
         isActive: false
     },
     options: {
       forceRecursiveCrawl: true
     },
     nativeIntegration: {
       type: "Snowflake",
       autoBootstrap: false,
       config: {
         authenticationType: "userPassword",
         username: "<your-Snowflake-username>",
         password: "<your-Snowflake-password>",
         host: "<your-Snowflake-hostname-url>",
         port: <your-Snowflake-port>,
         warehouse: "<your-Snowflake-warehouse>",
         database: "<your-Snowflake-database>",
         impersonation: { enabled: false },
         audit: { enabled: true },
         workspaces: { enabled: false },
         lineage: { enabled: false },
         userRolePattern: { exclude: [] }
       }
     }
    }'

Path parameters

AttributeDescriptionRequired

connectionKey string

The key to uniquely identify the host connection.

Yes

Body parameters

The connection parameters differ based on your backing technology. See the Data payloads reference guide for details about the payloads.

Response schema

AttributeDescription

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.

Example response

{
  objectPath: ['yourConnectionKey'],
  bulkId: "a-new-uuid"
}

POST /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

curl -X 'POST' \
    'https://<your-immuta-url>/data/crawl/yourConnectionKey/yourDatabase/yourSchema' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
     forceRecursive: false
     }'

Path parameters

AttributeDescriptionRequired

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

Query parameters

AttributeDescriptionRequired

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.

Response schema

AttributeDescription

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.

Example response

{
  objectPath: ['yourConnectionKey', 'yourDatabase', 'yourSchema'],
  bulkId: 'the-job's-unique-identifier'
}

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

curl -X 'PUT' \
    'https://<your-immuta-url>/data/settings/yourConnectionKey/yourDatabase' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
        overrides: {
            isActive: true
            activateNewChildren: true,
            infrastructureAdmins: [
              { id: 2, type: "user" },
            ],
            dataOwners: [
              { id: 3, type: "group" },
            ]
          }
        }

Path parameters

AttributeDescriptionRequired

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

Body parameters

AttributeDescriptionRequired

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.

Response schema

AttributeDescription

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.

Example response

{
    "objectPath": ["yourConnectionKey/yourDatabase"],
    "technology": "Snowflake",
    "state": "active",
    "settings": {
        "activateNewChildren": {
            "value": true,
            "hasDescendantsWithOverrides": true
        },
        "dataOwners": {
            "value": [
                {
                    "id": 2,
                    "type": "user"
                },
            ],
            "hasDescendantsWithOverrides": true
        },
        "infrastructureAdmins": {
            "value": [,
                {
                    "id": 3,
                    "type": "group"
                }
            ],
            "hasDescendantsWithOverrides": true
        },
        "isActive": {
            "value": true,
            "hasDescendantsWithOverrides": true
        }
    },
    "overrides": [
        "isActive",
        "activateNewChildren",
        "infrastructureAdmins",
        "dataOwners"
    ],
    "dataSourceId": null,
    "lastCrawled": 2023-08-21T10:39:00.250Z,
    "createdAt": 2023-08-21T10:39:00.250Z,
    "remoteId": null,
    "bulkId": "the-job's-unique-identifier"
}

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

curl -X 'DELETE' \
    'https://<your-immuta-url>/data/object/yourConnectionKey/yourDatabase/yourSchema' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \

Path parameters

AttributeDescriptionRequired

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

Response schema

AttributeDescription

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.

Example response

{
  objectPath: ['yourConnectionKey', 'yourDatabase', 'yourSchema'],
  childCount: 5
}

Disconnect a host

To disconnect a host from Immuta, you can do the following:

  1. Optionally, generate a script in Databricks or Snowflake to clean up any Immuta-managed resources from your environment.

  2. Delete the host connection in Immuta.

  3. 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

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/1/scripts/delete' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

Path parameters

AttributeDescriptionRequired

id integer

The integration ID.

Yes

Response schema

Response

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

curl -X 'DELETE' \
    'https://<your-immuta-url>/data/object/yourConnectionKey' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \

Path parameters

AttributeDescriptionRequired

connectionKey string

The key to uniquely identify the host connection.

Yes

Response schema

AttributeDescription

connectionKey string

The key to uniquely identify the host connection.

childCount integer

The number of child objects of the data object that were deleted.

Example response

{
  objectPath: ['yourConnectionKey'],
  childCount: 5
}

Last updated

Self-managed versions

2024.32024.22024.12023.4

Copyright © 2014-2024 Immuta Inc. All rights reserved.