Ga naar inhoud
buildinglinksbuildinglinks

Write setpoints

POST
/v1/buildings/{building_id}/setpoints
curl --request POST \
  --url https://example.com/v1/buildings/example/setpoints \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <X-Api-Key>' \
  --data '{ "issued_at": "2026-04-15T12:00:00Z", "valid_until": "2026-04-15T12:00:00Z", "idempotency_key": "example", "setpoints": [ { "point_id": "example", "value": 1 } ] }'

Asks the building to set points to values. The receipt confirms receipt, not execution; items the backend refuses are listed in rejected. idempotency_key makes a repeated request safe.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
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
SetpointWrite

Request of POST /v1/buildings/{building_id}/setpoints.

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
setpoints
required
Array<object>
>= 1 items
object
point_id
required

Stable address of a point, for example 9b41d0aa.

string
>= 1 characters
value
required

Matches the point’s value_type.

number | integer | boolean | string

Example generated

{
  "issued_at": "2026-04-15T12:00:00Z",
  "valid_until": "2026-04-15T12:00:00Z",
  "idempotency_key": "example",
  "setpoints": [
    {
      "point_id": "example",
      "value": 1
    }
  ]
}

Responses

Section titled “Responses”

202

Section titled “202”

Received.

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

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”

unauthenticated: no or a wrong key.

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”

forbidden: the key may not use this building.

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.

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

429

Section titled “429”

rate_limited; retry_after says when to try again.

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

503

Section titled “503”

upstream_unavailable: the building’s systems cannot be reached; retryable.

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