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.

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.

Tip

To retrieve the destinations of a single datastream together with their settings, you can also add ?expand=destinations to the datastream detail endpoint. For more information, see Retrieving the assigned destinations.

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

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 a key with Destination: Write (destination:write). A key with only Destination: Read-only receives a 403 response.

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

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 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`.