Managing datastream-destination bindings in Management API

On this page

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

See GET /api/v1/bindings/ and PATCH /api/v1/bindings/{binding_id}/ in the API reference.

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 Creating a Connect API key in Adverity.

Prerequisites

Before you complete the procedures in this guide, perform the following action:

Use a Connect API key with the following permissions:
- Destination: Read-only (destination:read) to list bindings.
- Destination: Write (destination:write) to enable or disable a binding.
Picking Write for a permission also gives the key its Read-only access. Without the permission a request needs, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

Listing all destination bindings

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

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/v1/bindings/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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}}'

Filtering bindings

You can filter the results using the following query parameters:

Scroll horizontally to see the full table.

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:

Scroll horizontally to see the full table.

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.

Disabling a binding

To disable an enabled destination binding, follow these steps:

Create a PATCH request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, set enabled to false:
```
{
    "enabled": false
}
```
Send the request.

As a result, the binding is disabled.

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:

Create a PATCH request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, set enabled to true:
```
{
    "enabled": true
}
```
Send the request.

As a result, the binding is enabled.

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

Error reference

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

Scroll horizontally to see the full table.

Status code	Cause
`401`	No `Authorization` header provided, or the key 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`.