Manage a Host

Data API reference guide

This page details the /data v1 API, which allows users to register a host to Immuta with a single set of credentials rather than configuring an integration and creating data sources separately. For a how-to on registering a host, see the Register a host reference guide.

Method	Endpoint	Description
GET	/data/connection/{connectionKey}	Search for a host using a connection key
GET	/data/object/{objectPath}	Search for a specific data object
POST	/data/object/search/{objectPath}	Search for the child objects of the data object defined in the objectPath or search all top-level data objects (hosts) if the objectPath is omitted
PUT	/data/connection/{connectionKey}	Update the connection information for the specified host
POST	/data/crawl/{objectPath}	Trigger an ad hoc crawl starting at the specified data object
PUT	/data/settings/{objectPath}	Update the settings through overrides for the specified data object
DELETE	/data/object/{objectPath}	Delete the given data object 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

Attribute	Description	Required
connectionKey string	The key to uniquely identify the host connection.	Yes

Response schema

Attribute	Description
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": "[e-mail]"
  },
  "updater": {
    "id": 2,
    "name": "Taylor Smith",
    "email": "[e-mail]"
  },
  "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

Attribute	Description	Required
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

Attribute	Desciription
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

Attribute	Description	Required
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

Attribute	Description	Required
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

Attribute	Description
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

What can be updated?

Using this endpoint, you can only update connection information. To update other integration details, use the PUT/integrations/{id} endpoint.

Snowflake username and password

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>"
     }
    }'

Snowflake key pair

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: "keyPair",
       username: "<the-Snowflake-username>",
       privateKeyPassword: "<your-Snowflake-key-password>",
       privateKey: {
         keyName: "PRIV_KEY_FILE",
         userFilename: "<your-private-key-file-name>",
         content: "<-----BEGIN PRIVATE KEY-----your-private-key-----END PRIVATE KEY----->"
       }
     }
    }'

Snowflake OAuth with certificate

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: "oAuthClientCredentials",
       oAuthClientConfig: {
         useCertificate: true,
         clientId: "<your-client-ID>",
         authorityUrl: "<your-example.authority.com>",
         scope: "session:role-any",
         publicCertificateThumbprint: "<your-certificate-thumbprint>",
         resource: "<your-optional-resource>",
         oauthPrivateKey: {
           keyName: "oauth client certificate",
           userFilename: "<your-user-file.pem>",
           content: "<-----BEGIN PRIVATE KEY-----your-private-key-----END PRIVATE KEY----->"
         }
       }
     }
    }'

Snowflake OAuth with secret

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: "oAuthClientCredentials",
       oAuthClientConfig: {
         useCertificate: false,
         clientId: "<your-client-ID>",
         authorityUrl: "<your-example.authority.com>",
         scope: "session:role-any",
         resource: "<your-optional-resource>",
         clientSecret: "<your-client-secret>"
       }
     }
    }'

Databricks Unity Catalog

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: "Databricks",
       hostname: "<www.your-workspace.cloud.databricks.com>",
       port: <your-Databricks-port>,
       httpPath: "<your-Databricks-warehouse-path>",
       authenticationType: "token",
       token: "<your-service-principal-pat>"
     }
    }'

Path parameters

Attribute	Description	Required
connectionKey string	The key to uniquely identify the host connection.	Yes

Body parameters

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

Response schema

Attribute	Description
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

Attribute	Description	Required
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

Attribute	Description	Required
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

Attribute	Description
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

Attribute	Description	Required
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

Attribute	Description	Required
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

Attribute	Description
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

See the Disconnect a Host guide to delete a host and all its data objects.

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

Attribute	Description	Required
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

Attribute	Description
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
}