Ga naar inhoud
buildinglinksbuildinglinks

Get a connection

GET
/api/v1/connections/{alias}
curl --request GET \
  --url https://example.com/api/v1/connections/example \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
alias
required
string

The alias of the connection: the name in its gateway address.

Responses

Section titled “Responses”

200

Section titled “200”

OK.

Media typeapplication/json

A connection (subscription) as the management API shows it.

object
alias
required
string
provider_did
required
string
provider_name
string | null
dataset_id
required
string
dataset_title
string | null
building_id
string | null
objects
required
Array<string>
points

The points the agreement covers; null: all points of the objects.

Array<string> | null
read_only

The agreement allows reading only.

boolean | null
delivered_by

The supplier that delivers on the provider’s behalf, if any.

string | null
delivered_by_name
string | null
own_use
required

An own subscription of an aanwijzing (decisions #74).

boolean
own_use_topology
required

An own subscription to the indeling rather than the data.

boolean
delegation_id
string | null
offer_id
required
string
purpose
string | null
state
required

One of negotiating, awaiting_approval, transferring, active, suspended, terminated, failed or expired.

string
negotiation_id
string | null
approval_expires_at

Until when the provider can approve the request.

string | null format: date-time
agreement_id
string | null
transfer_id
string | null
error
string | null
gateway_url
required

The address applications use: {data plane}/gateway/{alias}.

string
gateway_browser_url
required

The same address as a browser reaches it.

string
created_at
required
string format: date-time
updated_at
required
string format: date-time
stats
required
object
requests_24h
required

Requests through the gateway in the last 24 hours.

integer format: int64
last_request_at
string | null format: date-time

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

401

Section titled “401”

No valid session, DPoP-bound token or API key.

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

403

Section titled “403”

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

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

404

Section titled “404”

Not found.

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}