Create a connection
const url = 'https://example.com/api/v1/connections';const options = { method: 'POST', headers: { cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E', 'Content-Type': 'application/json' }, body: '{"alias":"example","provider_did":"example","dataset_id":"example","offer_id":"example","purpose":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/connections \ --header 'Content-Type: application/json' \ --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \ --data '{ "alias": "example", "provider_did": "example", "dataset_id": "example", "offer_id": "example", "purpose": "example" }'Makes a dataset of another participant available to our applications under an alias: the connector negotiates an agreement, starts a transfer and hands the data address to the gateway of our data plane. This runs in the background; the connection goes through negotiating, awaiting_approval (when the provider approves by hand) and transferring to active, or ends failed or expired. A connection that ended may be requested again under the same alias, for the same dataset.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
2 to 63 lower-case letters, digits or -: the name in the gateway address.
The provider.
The dataset in the provider’s catalog.
The offer of that dataset to accept.
The purpose of the use, e.g. bl:climate_control: one the offer
allows. Left out: the offer’s, when it names one.
Example generated
{ "alias": "example", "provider_did": "example", "dataset_id": "example", "offer_id": "example", "purpose": "example"}Responses
Section titled “Responses”Started; follow the state.
A connection (subscription) as the management API shows it.
object
The points the agreement covers; null: all points of the objects.
The agreement allows reading only.
The supplier that delivers on the provider’s behalf, if any.
An own subscription of an aanwijzing (decisions #74).
An own subscription to the indeling rather than the data.
One of negotiating, awaiting_approval, transferring, active,
suspended, terminated, failed or expired.
Until when the provider can approve the request.
The address applications use: {data plane}/gateway/{alias}.
The same address as a browser reaches it.
object
Requests through the gateway in the last 24 hours.
Example generated
{ "alias": "example", "provider_did": "example", "provider_name": "example", "dataset_id": "example", "dataset_title": "example", "building_id": "example", "objects": [ "example" ], "points": [ "example" ], "read_only": true, "delivered_by": "example", "delivered_by_name": "example", "own_use": true, "own_use_topology": true, "delegation_id": "example", "offer_id": "example", "purpose": "example", "state": "example", "negotiation_id": "example", "approval_expires_at": "2026-04-15T12:00:00Z", "agreement_id": "example", "transfer_id": "example", "error": "example", "gateway_url": "example", "gateway_browser_url": "example", "created_at": "2026-04-15T12:00:00Z", "updated_at": "2026-04-15T12:00:00Z", "stats": { "requests_24h": 1, "last_request_at": "2026-04-15T12:00:00Z" }}An invalid alias, or the provider is not a registered participant.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}No valid session, DPoP-bound token or API key.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}The caller lacks the role this operation needs; or a change with the session cookie came from a page of another site (cross_site_request, decisions #83).
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}A connection with this alias exists.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}The authority could not be reached.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}