Ga naar inhoud
buildinglinksbuildinglinks

Send a building command

POST
/gateway/{alias}/v1/buildings/{building_id}/commands
curl --request POST \
  --url https://example.com/gateway/example/v1/buildings/example/commands \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '"example"'

A command for equipment or a group of the building, such as bl:SetActivePower, bl:SetPowerLimit or bl:SubmitReservePlan.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
alias
required
string

The connection (abonnement) to call through, as Verbindingen in the connector names it.

building_id
required

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters

The object id of the building: its register identification in dotted form, e.g. nl.bag.pand.0014100040022681.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
BuildingCommand

Request of POST /v1/buildings/{building_id}/commands. bl:SetActivePower and bl:SetPowerLimit take { value, unit } (group total; positive delivers power to the building). bl:SubmitReservePlan takes { blocks: [{ start, end, value, unit }] }.

object
issued_at
required

RFC 3339 timestamp.

string format: date-time
valid_until

RFC 3339 timestamp.

string format: date-time
idempotency_key

Lets the consumer retry safely: the same key returns the same receipt.

string
>= 1 characters <= 200 characters
target
required
One of:

Exactly one of asset_class and group_id.

object
asset_class
required

Compact IRI such as brick:Temperature_Sensor or unit:DEG_C.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
group_id
string
>= 1 characters
command
required
Allowed values: bl:SetActivePower bl:SetPowerLimit bl:SubmitReservePlan
parameters
required
object

Responses

Section titled “Responses”

202

Section titled “202”

Received.

Media typeapplication/json
Receipt

202 response of every write. Confirms receipt, not execution.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id
required

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
receipt_id
required
string
>= 1 characters
received_at
required

RFC 3339 timestamp.

string format: date-time
status
required
Allowed values: accepted partially_accepted rejected
accepted_count
required
integer
rejected
Array<object>
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
point_id

Stable address of a point, for example 9b41d0aa.

string
>= 1 characters
target
One of:

Exactly one of asset_class and group_id.

object
asset_class
required

Compact IRI such as brick:Temperature_Sensor or unit:DEG_C.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
group_id
string
>= 1 characters
equipment_id

Extension: the individual asset that failed a building-level command.

string
message
string
verify_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/

Example 

{
  "status": "accepted",
  "rejected": [
    {
      "code": "invalid_request"
    }
  ]
}

400

Section titled “400”

invalid_request, or a write the backend refuses as a whole (point_not_writable, value_out_of_range, …).

Media typeapplication/json
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

401

Section titled “401”

From the backend: unauthenticated: no or a wrong key. From the gateway: unauthenticated: no key, an unknown key, or an invalid token of the control plane.

Media typeapplication/json
Any of:
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

403

Section titled “403”

From the backend: forbidden: the key may not use this building. From the gateway: forbidden: the key lacks the gateway scope, its app may not use this connection, or the app may only read. The provider’s data plane refuses with 403 what the agreement does not cover.

Media typeapplication/json
Any of:
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

404

Section titled “404”

building_not_found, or not_found for an unknown route.

Media typeapplication/json
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

413

Section titled “413”

invalid_request: the body is larger than 16 MiB.

Media typeapplication/json

An answer of the gateway itself, not one it passes on.

object
error
required
object
code
required
string
message
required
string
retryable
required

Whether the same request may succeed later.

boolean

Example 

{
  "error": {
    "code": "forbidden"
  }
}

429

Section titled “429”

rate_limited; retry_after says when to try again.

Media typeapplication/json
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

502

Section titled “502”

upstream_unavailable: the provider’s data plane could not be reached, its answer was larger than 16 MiB, or, when the agreement requires signed requests, its answer had no valid signature.

Media typeapplication/json

An answer of the gateway itself, not one it passes on.

object
error
required
object
code
required
string
message
required
string
retryable
required

Whether the same request may succeed later.

boolean

Example 

{
  "error": {
    "code": "forbidden"
  }
}

503

Section titled “503”

From the backend: upstream_unavailable: the building’s systems cannot be reached; retryable. From the gateway: upstream_unavailable: the connection is not active (yet), or renewing the access token failed; evidence_unavailable: the agreement requires signed requests and the request or answer could not be recorded; standby: another instance of this data plane is active. Retryable.

Media typeapplication/json
Any of:
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}