Managing datastream-destination bindings in Management API

This guide explains how to list all destinations assigned to datastreams and how to enable or disable destination bindings using the Management API.

Introduction

The bindings endpoint provides a simplified way to retrieve all destination assignments for your datastreams. Instead of querying multiple endpoints to find which destinations are linked to a specific datastream, you can use a single API call with optional filters.

Limitations

The bindings endpoint is only available when using an API key generated in the Adverity user interface. These keys use the Bearer scheme in the Authorization header. For more information, see Generating an API key in Adverity.

Prerequisites

The required scope depends on the operation you want to perform:

Operation	Required scope
List bindings (GET)	destination:read
Enable or disable a binding (PATCH)	destination:write

Listing all destination bindings

To list all datastream-destination bindings, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/v1/bindings/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. Send the request.

As a result, you obtain the list of all datastream-destination bindings in the response.

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/v1/bindings/' \
--header 'Authorization: Bearer {{KEY}}'

Note

The bindings endpoint only supports API keys generated in the Adverity user interface, which use the Bearer scheme in the Authorization header.

Filtering bindings

You can filter the results using the following query parameters:

Parameter	Description
datastream_id	Filter bindings by datastream ID
target_id	Filter bindings by destination ID

Filtering by datastream

To list all destinations assigned to a specific datastream, add the datastream_id parameter:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/bindings/?datastream_id={{DATASTREAM_ID}}' \
--header 'Authorization: Bearer {{KEY}}'

Filtering by destination

To list all datastreams assigned to a specific destination, add the target_id parameter:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/bindings/?target_id={{TARGET_ID}}' \
--header 'Authorization: Bearer {{KEY}}'

Combining filters

You can combine both filters to check if a specific datastream is assigned to a specific destination:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/bindings/?datastream_id={{DATASTREAM_ID}}&target_id={{TARGET_ID}}' \
--header 'Authorization: Bearer {{KEY}}'

Pagination

The endpoint supports pagination using the following parameters:

Parameter	Default value	Maximum value
page	1	N/A
page_size	50	100

The endpoint with the default parameters looks the following way:

https://{{INSTANCE}}/api/v1/bindings/?page=1&page_size=50

Example with custom pagination:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/bindings/?page=1&page_size=20' \
--header 'Authorization: Bearer {{KEY}}'

Response format

The response includes an items array containing the bindings and a count field with the total number of bindings matching your query:

{
    "items": [
        {
            "id": 123,
            "datastream_id": 456,
            "target_id": 789,
            ...
        }
    ],
    "count": 1
}

If no bindings match your filters, the response returns an empty array:

{
    "items": [],
    "count": 0
}

Enabling and disabling destination bindings

You can enable or disable a destination binding using the PATCH /api/v1/bindings/{{BINDING_ID}}/ endpoint. This allows you to programmatically toggle the binding state without using the Adverity user interface.

Note

This endpoint requires an API key with destination:write scope. An API key with destination:read scope only returns a 403 response.

Disabling a binding

To disable an enabled destination binding, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/v1/bindings/{{BINDING_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

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

4. In the HTTP request body, set enabled to false:

   {
       "enabled": false
   }
   

5. Send the request.

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/v1/bindings/{{BINDING_ID}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"enabled": false}'

A successful request returns a 200 response with the updated binding:

{
    "id": 123,
    "datastream_id": 456,
    "target_id": 789,
    "target_name": "My BigQuery Destination",
    "target_type": "BigQueryTarget",
    "enabled": false,
    "created": "2024-01-15T10:00:00Z",
    "updated": "2024-06-01T14:32:00Z"
}

Re-enabling a binding

To re-enable a disabled destination binding, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/v1/bindings/{{BINDING_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

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

4. In the HTTP request body, set enabled to true:

   {
       "enabled": true
   }
   

5. Send the request.

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/v1/bindings/{{BINDING_ID}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"enabled": true}'

A successful request returns a 200 response with the updated binding:

{
    "id": 123,
    "datastream_id": 456,
    "target_id": 789,
    "target_name": "My BigQuery Destination",
    "target_type": "BigQueryTarget",
    "enabled": true,
    "created": "2024-01-15T10:00:00Z",
    "updated": "2024-06-01T14:32:00Z"
}

Note

PATCH is idempotent with respect to the enabled value. Sending {"enabled": true} on an already-enabled binding returns 200 with the current state. The updated timestamp is refreshed on each successful call.

Note

Extra or unknown fields in the request body (such as target_id or datastream_id) are ignored — only the enabled field is applied.

Error reference

The following table describes the error responses returned by the PATCH /api/v1/bindings/{{BINDING_ID}}/ endpoint:

Status code	Cause
401	No Authorization header provided, or the token is invalid.
403	The API key has destination:read scope but not destination:write.
404	The binding ID does not exist, belongs to a workspace not accessible to the API key, or the binding has available: false.
422	The request body is empty, the enabled field is missing, or enabled is null.