Configuring Snowflake managed by Adverity binding settings in Management API

This guide explains how to manage Snowflake managed by Adverity (previously ADS) settings using the Management API. Snowflake managed by Adverity is an Adverity-managed warehouse. In the Management API, it is exposed as a destination type that can be configured and bound to datastreams.

Note

In the Management API, the Snowflake managed by Adverity target type is registered under the name Dashboards. When listing available destination types (GET /api/target-types/), look for the entry named Dashboards to obtain the TARGET_TYPE_ID. The settings exposed through the MAPI include both general data storage settings (overwrite behaviour) and Dashboards visualization settings (workspace mapping). The same settings are available in the Adverity user interface in the Dashboards section when loading data into your connected warehouse. For more information, see Loading data into Data Warehouse.

Limitations

The Management API does not provide endpoints to enumerate the valid values for workspace_single_mapping and workspace_mapping_table. To obtain the IDs of valid workspaces and mapping tables, use the Adverity user interface.

Prerequisites

Before you complete the procedures in this guide, perform all of the following actions:

• Obtain a Management API key with the appropriate scope:

  • destination:read to list and view bindings.

  • destination:write to create, update, or delete bindings.

  For more information, see Authorizing to Management API.

• Determine the following IDs:

  • TARGET_TYPE_ID — the content-type ID of the Snowflake managed by Adverity destination. To find it, send a GET request to https://{{INSTANCE}}/api/target-types/ and look for the entry named Dashboards in the response.

  • TARGET_ID — the numeric ID of the Snowflake managed by Adverity destination instance. After obtaining the TARGET_TYPE_ID, send a GET request to https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/ and locate the relevant ID.

Listing Snowflake managed by Adverity bindings

To list the Snowflake managed by Adverity bindings, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

As a result, you obtain the list of Snowflake managed by Adverity bindings, including the current values of all configurable settings.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Retrieving a single binding

To retrieve the settings of a specific Snowflake managed by Adverity binding, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

As a result, you obtain the current settings for the specified binding.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Discovering available settings

To see all configurable fields, their accepted values, and help text before creating or updating a binding, send an OPTIONS request.

To discover available settings, follow these steps:

1. Create an OPTIONS request to the following endpoint:

   https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

As a result, the response contains the full schema for the binding endpoint, including all accepted fields, their types, choices, and which are required.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request OPTIONS 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Creating an Snowflake managed by Adverity binding

To create a new Snowflake managed by Adverity binding, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the binding parameters. At minimum, include the datastream field. For the full list of available parameters, see Available binding settings:

   {
       "datastream": "{{DATASTREAM_ID}}",
       "workspace_mapping_type": 1,
       "workspace_single_mapping": "{{WORKSPACE_ID}}",
       "datasource_label": "My Datasource"
   }
   

5. Send the request.

As a result, you created a new Snowflake managed by Adverity binding. The response contains the created binding with all its settings and returns HTTP 201.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"datastream": "{{DATASTREAM_ID}}", "workspace_mapping_type": 1, "workspace_single_mapping": "{{WORKSPACE_ID}}", "datasource_label": "My Datasource"}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Note

The target field is taken from the URL path and is read-only. Any target value included in the request body is ignored. Creating a second binding for the same datastream and destination pair returns a 400 response.

Updating Snowflake managed by Adverity binding settings

To update the settings of an existing Snowflake managed by Adverity binding, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include only the settings you want to update:

   {
       "datasource_label": "Updated Label",
       "overwrite_filename": true
   }
   

5. Send the request.

As a result, the binding is updated and the response reflects the new values.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request PATCH 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"datasource_label": "Updated Label", "overwrite_filename": true}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Note

Extra or unknown fields in the request body are ignored — only the fields listed in Available binding settings are applied.

Deleting an Snowflake managed by Adverity binding

To delete an existing Snowflake managed by Adverity binding, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

As a result, you deleted the Snowflake managed by Adverity binding and the destination is removed from the datastream. The response returns HTTP 204 with no body.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request DELETE 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Available binding settings

The settings are grouped into three categories: Dashboards workspace selection, overwrite settings, and other settings. To see the full set of accepted values for each field, send an OPTIONS request as described in Discovering available settings.

Dashboards workspace selection

Parameter	Description
workspace_mapping_type	Controls how the datastream’s data is mapped to a workspace. Known values: 1 (single workspace mapping), 2 (column-based mapping). Use the OPTIONS endpoint to see all accepted values.
workspace_single_mapping	The numeric ID of the Dashboards workspace to map to. Required when workspace_mapping_type is 1. Only client-type workspaces are valid. See the Limitations section for how to obtain valid IDs.
workspace_mapping_column_name	The name of the column in your data extract used to map data to workspaces. Required when workspace_mapping_type is 2.
workspace_mapping_table	The workspace mapping table that resolves column values to workspaces. Required when workspace_mapping_type is 2. See the Limitations section for how to obtain valid IDs.
workspace_missing_action	The action to take when a workspace cannot be resolved from the mapping column. Use the OPTIONS endpoint to see available choices.

Overwrite settings

Parameter	Description
overwrite_key_columns	Boolean. When true, existing rows are overwritten based on key columns configured in the Data Mapping for this datastream.
overwrite_datastream	Boolean. When true, existing data for the datastream is overwritten on each load.
overwrite_filename	Boolean. When true, existing data with the same data extract filename is overwritten.
overwrite_date_range_column_name	The name of the date column used to determine which data is overwritten. When set, previously loaded data within the matching date range is replaced.

Other settings

Parameter	Description
datasource_label	A label for the data source. Must be title-case. Appears as the data source name in Dashboards.
is_insights_mediaplan	Boolean. When true, the binding is treated as a media plan binding in Dashboards.
enabled	Boolean. When true, the binding is active and data is loaded on each fetch.

Read-only base fields

Field	Description
id	The numeric ID of the binding.
target	The numeric ID of the Snowflake managed by Adverity destination. Read-only; set from the URL path.
datastream	The numeric ID of the bound datastream.