# Manage Connection Objects

This page details the `/data` v1 API options available to all objects within a connection.

* For a how-to on registering a connection, see the [Register a connection guide](/saas/developer-guides/api-intro/connections-api/how-to-guides/register-a-connection.md).
* For details on the `/data` v1 API options available for connection-level objects, see the [Manage connection settings guide](/saas/developer-guides/api-intro/connections-api/how-to-guides/manage-connection-settings.md).

These endpoints can be used for any connection on any supported technology.

<table><thead><tr><th width="114">Method</th><th width="352">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><strong>GET</strong></td><td><a href="#get-data-object-objectpath"><mark style="color:blue;"><code>/data/object/{objectPath}</code></mark></a></td><td>Search for a specific data object</td></tr><tr><td><strong>POST</strong></td><td><a href="#post-data-object-search-objectpath"><mark style="color:blue;"><code>/data/object/search/{objectPath}</code></mark></a></td><td>Search for the child objects of the data object defined in the objectPath or search all top-level data objects (connections) if the objectPath is omitted</td></tr><tr><td><strong>POST</strong></td><td><a href="#post-data-crawl-objectpath"><mark style="color:blue;"><code>/data/crawl/{objectPath}</code></mark></a></td><td>Trigger object sync for the specified data object</td></tr><tr><td><strong>PUT</strong></td><td><a href="#put-data-settings-objectpath"><mark style="color:blue;"><code>/data/settings/{objectPath}</code></mark></a></td><td>Update the settings through overrides for the specified data object</td></tr><tr><td><strong>DELETE</strong></td><td><a href="#delete-data-object-objectpath"><mark style="color:blue;"><code>/data/object/{objectPath}</code></mark></a></td><td>Delete the given data object and all its child objects</td></tr></tbody></table>

## <mark style="color:green;">`GET`</mark> `/data/object/{objectPath}`

Search for a specific data object using the object path.

**Required Immuta permission**: `CREATE_DATA_SOURCE`, `APPLICATION_ADMIN`, `GOVERNANCE`, 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

<table><thead><tr><th width="163">Attribute</th><th width="435">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>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 <a data-footnote-ref href="#user-content-fn-1"><code>connectionKey</code></a> and all names should be separated by forward slashes (<code>/</code>). For example, <code>yourConnectionKey/yourDatabase/yourSchema</code>.</td><td><strong>Yes</strong></td></tr></tbody></table>

#### Response schema

<table><thead><tr><th width="162">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>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 <code>connectionKey</code> and all names are separated by forward slashes.</td></tr><tr><td><strong>technology</strong> <code>string</code></td><td>The technology that the object comes from: <code>Databricks</code> , <code>Glue</code> , or <code>Snowflake</code>.</td></tr><tr><td><strong>state</strong> <code>string</code></td><td>Whether the object is currently <code>active</code> (enabled) or <code>inactive</code> (disabled).</td></tr><tr><td><strong>settings</strong> <code>object</code></td><td>Specifications of the connection's settings, including status, new children status, and data owners.</td></tr><tr><td><strong>overrides</strong> <code>object</code></td><td>Specifications of the data object's settings that differ from its parents' settings.</td></tr><tr><td><strong>dataSourceId</strong> <code>integer</code></td><td>The ID of the data source if it is a table object that is active.</td></tr><tr><td><strong>createdAt</strong> <code>timestamp</code></td><td>The time the data object was created in Immuta.</td></tr><tr><td><strong>lastCrawled</strong> <code>timestamp</code></td><td>The time object sync was last run on the data object.</td></tr><tr><td><strong>remoteId</strong> <code>string</code></td><td>The ID of the remote data object.</td></tr></tbody></table>

#### Example response

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

## <mark style="color:green;">`POST`</mark> `/data/object/search/{objectPath}`

Search for the children of the object defined in the objectPath. Or search all top-level data objects if the objectPath is omitted.

**Required Immuta permission**: `CREATE_DATA_SOURCE`, `APPLICATION_ADMIN`, `GOVERNANCE`, or Data Owner on the object

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

#### Path parameters

<table><thead><tr><th width="184">Attribute</th><th width="433">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>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 <a data-footnote-ref href="#user-content-fn-1"><code>connectionKey</code></a> and all names should be separated by forward slashes (<code>/</code>). For example, <code>yourConnectionKey/yourDatabase/yourSchema</code>.</td><td><strong>Yes</strong></td></tr></tbody></table>

#### Query parameters

<table><thead><tr><th width="181">Attribute</th><th width="442">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>sortField</strong> <code>string</code></td><td>The field to sort the search results.</td><td>No</td></tr><tr><td><strong>sortOrder</strong> <code>string</code></td><td>Denotes whether to sort the results in ascending (<code>asc</code>) or descending (<code>desc</code>) order. <strong>Default is <code>asc</code>.</strong></td><td>No</td></tr><tr><td><strong>offset</strong> <code>integer</code></td><td>Use in combination with <code>limit</code> to fetch pages.</td><td>No</td></tr><tr><td><strong>limit</strong> <code>integer</code></td><td>Limits the number of results displayed per page.</td><td>No</td></tr><tr><td><strong>searchText</strong> <code>string</code></td><td>A partial, case-insensitive search on name.</td><td>No</td></tr></tbody></table>

#### Response schema

<table><thead><tr><th width="183">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>count</strong> <code>integer</code></td><td>The number of results for your search.</td></tr><tr><td>hits.<strong>objectPath</strong> <code>string</code></td><td>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 <code>connectionKey</code> and all names are separated by forward slashes.</td></tr><tr><td>hits.<strong>technology</strong> <code>string</code></td><td>The technology that the object comes from (i.e., Snowflake, Databricks, Glue, etc.).</td></tr><tr><td>hits.<strong>state</strong> <code>string</code></td><td>Whether the object is currently <code>active</code> (enabled) or <code>inactive</code> (disabled).</td></tr><tr><td>hits.<strong>settings</strong> <code>object</code></td><td>Specifications of the connection's settings, including status, new children status, and data owners.</td></tr><tr><td>hits.<strong>overrides</strong> <code>object</code></td><td>Specifications of the data object's settings that differ from its parents' settings.</td></tr><tr><td>hits.<strong>dataSourceId</strong> <code>integer</code></td><td>The ID of the data source if it is a table object that is active (enabled).</td></tr><tr><td>hits.<strong>createdAt</strong> <code>timestamp</code></td><td>The time the data object was created in Immuta.</td></tr><tr><td>hits.<strong>lastCrawled</strong> <code>timestamp</code></td><td>The time object sync was last run on the data object.</td></tr><tr><td>hits.<strong>remoteId</strong> <code>string</code></td><td>The ID of the remote data object.</td></tr></tbody></table>

#### 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
      },
      "isActive": {
        "value": true,
        "hasDescendantsWithOverrides": false
      }
    },
    "overrides": [],
    "lastCrawled": 2023 - 08 - 21 T10: 39: 00.250 Z,
    "createdAt": 2023 - 08 - 21 T10: 39: 00.250 Z,
    "remoteId": null
  }]
}
```

## <mark style="color:green;">`POST`</mark> `/data/crawl/{objectPath}`

Trigger object sync for the specified data object.

**Required Immuta permission**: `GOVERNANCE` or `APPLICATION_ADMIN` global permission 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

<table><thead><tr><th width="172">Attribute</th><th width="372">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>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 <a data-footnote-ref href="#user-content-fn-1"><code>connectionKey</code></a> and all names should be separated by forward slashes (<code>/</code>). For example, <code>yourConnectionKey/yourDatabase/yourSchema</code>.</td><td><strong>Yes</strong></td></tr></tbody></table>

#### Query parameters

<table><thead><tr><th width="172">Attribute</th><th width="372">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>forceRecursive</strong> <code>boolean</code></td><td>If <code>false</code>, only active (enabled) objects will have object sync run. If <code>true</code>, both active (enabled) and inactive (disabled) data objects will be synced; any child objects from inactive (disabled) objects will be set as inactive (disabled). Defaults to <code>false</code>.</td><td>No.</td></tr></tbody></table>

#### Response schema

<table><thead><tr><th width="170">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>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 <code>connectionKey</code> and all names are separated by forward slashes.</td></tr><tr><td><strong>bulkId</strong> <code>string</code></td><td>A bulk ID that can be used to search for the status of background jobs triggered by this request.</td></tr></tbody></table>

#### Example response

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

## <mark style="color:green;">`PUT`</mark> `/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 cannot be removed, only added. To remove data owners, edit the settings at the connection level.

**Required Immuta permission**: `APPLICATION_ADMIN` or `GOVERNANCE` global permission

```
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,
          "dataOwners": [{
            "id": 3,
            "type": "group"
          }]
        }
      }'
```

#### Path parameters

<table><thead><tr><th width="214">Attribute</th><th width="440">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>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 <a data-footnote-ref href="#user-content-fn-1"><code>connectionKey</code></a> and all names should be separated by forward slashes (<code>/</code>). For example, <code>yourConnectionKey/yourDatabase/yourSchema</code>.</td><td><strong>Yes</strong></td></tr></tbody></table>

#### Body parameters

<table><thead><tr><th width="300">Attribute</th><th width="419">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>overrides</strong> <code>object</code></td><td>A list of settings configured differently from the parent object's settings.</td><td>No</td></tr><tr><td>overrides.<strong>isActive</strong> <code>boolean</code></td><td><p>If <code>true</code>, the object and all its child objects are active (enabled).<br><br>If you enable a Databricks Unity Catalog data object and it has no subscription policy set on it, Immuta will REVOKE access to the data in Databricks for all Immuta users, even if they had been directly granted access to the table in Unity Catalog.</p><p>If a user is not registered in Immuta, Immuta will have no effect on that user's access to data in Unity Catalog. See the <a href="/pages/v7i0KNuck7dOiVw2Joci#what-does-immuta-do-in-my-databricks-environment">Databricks Unity Catalog reference guide</a> for more details.</p></td><td>No</td></tr><tr><td>overrides.<strong>activateNewChildren</strong> <code>boolean</code></td><td>If <code>true</code>, all new children found during object sync will be registered as active (enabled).</td><td>No</td></tr><tr><td>overrides.<strong>dataOwners</strong> <code>array</code></td><td>A list of users and groups that are data owners on the connection. These users will be data owners for all the data sources under the data object they are assigned to.</td><td>No</td></tr><tr><td>overrides.dataOwners.<strong>id</strong> <code>integer</code></td><td>The ID of the user or group to make data owner.</td><td>No</td></tr><tr><td>overrides.dataOwners.<strong>type</strong> <code>string</code></td><td>The type to make data owner. Options are <code>user</code> or <code>group</code>.</td><td>No</td></tr></tbody></table>

#### Response schema

<table><thead><tr><th width="160">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>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 <code>connectionKey</code> and all names should be separated by forward slashes.</td></tr><tr><td><strong>technology</strong> <code>string</code></td><td>The backing technology of the connection. Options are <code>Databricks</code> , <code>Glue</code> , or <code>Snowflake</code>.</td></tr><tr><td><strong>state</strong> <code>string</code></td><td>Whether the object is currently <code>active</code> (enabled) or <code>inactive</code> (disabled).</td></tr><tr><td><strong>settings</strong> <code>object</code></td><td>Specifications of the connection's settings, including status, new children status, and data owners.</td></tr><tr><td><strong>overrides</strong> <code>object</code></td><td>Specifications of the data object's settings that differ from its parents' settings.</td></tr><tr><td><strong>dataSourceId</strong> <code>integer</code></td><td>The ID of the data source if it is a table object that is active (enabled).</td></tr><tr><td><strong>createdAt</strong> <code>timestamp</code></td><td>The time the data object was created in Immuta.</td></tr><tr><td><strong>lastCrawled</strong> <code>timestamp</code></td><td>The time object sync was last run on the data object.</td></tr><tr><td><strong>remoteId</strong> <code>string</code></td><td>The ID of the remote data object.</td></tr><tr><td><strong>bulkId</strong> <code>string</code></td><td>A bulk ID that can be used to search for the status of background jobs triggered by this request.</td></tr></tbody></table>

#### Example response

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

```

## <mark style="color:green;">`DELETE`</mark> `/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**: `GOVERNANCE` or `APPLICATION_ADMIN` global permission or Data Owner on the object

{% hint style="info" %}
See the [Deregister a connection guide](/saas/developer-guides/api-intro/connections-api/how-to-guides/deregister-a-connection.md) to delete a connection and all its data objects.
{% endhint %}

```
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`](#user-content-fn-1)[^1] 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
}
```

[^1]: This is the same as the display name of the connection in the Immuta UI.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/saas/developer-guides/api-intro/connections-api/how-to-guides/manage-a-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.