Listing datastream-destination bindings in Management API

This guide explains how to list all destinations (targets) assigned to datastreams 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 API key must have the destination:read scope to access this endpoint.

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
}