Skip to content

Developer's Guide

The Siemens Building X APIs are based on the JSON:API specification. On top of JSON:API we have applied some conventions of our own. This document aims to describe those and give you other useful information to get started and operate an application base on our APIs.


You can use your Machine User credentials to obtain an API Token using the OAuth 2.0 Client Credentials grant.

The token endpoint is found at:

Parameter Value
client_id (mandatory) The client_id you received when registering
client_secret (mandatory) The client_secret you received when registering
audience (mandatory)
grant_type (mandatory) client_credentials

For information on how to create you own client credentials, or Machine User, check out the Getting Started. Refer to Create a Token for more hands-on guidance.

Token Validity

The token has limited validity. After expiry you may create a new token by repeating the create token flow. The JWT itself, as well as the response of the create token request, will provide information about the expiry time. In the JWT there is a exp-claim and in the response there is a expires_in property.


Filters are provided as query string parameters using the filter-family style. The available filters for each List-operation are described in the 'API Reference'.


Filter devices with serialNumber of value 12345.

GET /partitions/5435b9ac-8823-9e89-804bd4710e90/devices?filter[serialNumber]=12345


Paging functionality is provided as query string parameters using the page-family style. The available paging strategy and specific options for each List-operation are described in the 'API Reference'.

Controlling Page Size

Page size is controlled by using the page[limit] param.


Set the maximal number of records to receive in the response to 5.

GET /partitions/5435b9ac-8823-9e89-804bd4710e90/devices?page[limit]=5

Navigation links are provided within the links property using different keys to represent different targets as described in the table below.

Key Description
self the current page of data
first the first page of data
last the last page of data
prev the previous page of data
next the next page of data

Keys are omitted to indicate that a particular link is unavailable.

When listing resources, e.g. devices, there are typically one or two links present. self is always present and next is present if there is a next page to fetch. When the next link is no longer in the response, then there are no more pages to fetch.

Building-X APIs adhere to the JSON:API specification. For some operations the include-parameter is supported. If the include-parameter is specified for an operation it can be used with the defined values. This gives you the option to include resources that appear in the relationships without performing another request to the server.

When used, the response will contain a top-level property included which contains the requested resources

In addition, there is a parameter called field, available for some operations. By specifying it, the client can retrieve certain fields that are not otherwise in the response.


Every response contains a response header called X-Request-Id. The value of the header is a unique identifier of the transaction. Use this and share with the Development Team when reporting problems.

Example Response

HTTP/1.1 400 Bad Request
X-Request-Id: 2e92b826-8d7f-4a86-bf84-241c02c1b90a

JSON Error Object

Term Description
id A unique identifier for this particular occurrence of the problem.
status The HTTP status code applicable to this problem, expressed as a string value.
code An application-specific error code, expressed as a string value.
title A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

Example Response

            "id": "2e92b826-8d7f-4a86-bf84-241c02c1b90a",
            "status": "400",
            "code": "34-0001",
            "title": "Missing mandatory property 'name'"

HTTP Status Codes

Term Description
200 Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
201 The request has been fulfilled, resulting in the creation of a new resource.
202 The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.
204 The server successfully processed the request and is not returning any content.
400 The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
401 Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.
403 The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort. This code is also typically used if the request provided authentication via the WWW-Authenticate header field, but the server did not accept that authentication.
404 The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
405 A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource.
406 The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
409 Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
429 The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.
500 A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
503 The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.
504 The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.

Standards & Formats

Term Description
RFC 3339 Date and Time on the Internet: Timestamps The chosen way to represent time and dates.
The OAuth 2.0 Authorization Framework OAuth 2.0 for authorization and client_credentials grant type
WGS84 The representation of geographical coordinates.
Project Haystack Project Haystack is an open source initiative to streamline working with data from the Internet of Things in the domain of Building Automation.
RFC7946 The GeoJSON Format GeoJSON is a geospatial data interchange format based on JavaScript Object Notation (JSON).
JSON:API JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.

JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.|


Rate Limitation

Each client may make 10 request per second and API. If you have additional requirements please contact us.

Exceeding the rate limit will result in a 429 error code.

Compatibility Policy

The APIs will evolve over time by the introduction of new properties and endpoints. Prepare your parsers for new properties, so that they are allowed in order not to break the client.

Backwards compatibility

As long as possible we strive not to change the behavior of existing properties. However, the behavior of an API may change without warning if the existing behavior is incorrect or constitutes a security vulnerability.


We reserve the right to deprecate APIs in full or in part. Usually this is only done after introducing improved ways to achieve the same goals.

When deprecating we will inform all registered users at least 3 months in advance of API sunset.


Connect and Collaborate with Industrial Professionals and Join the Community!

Click to load comments