Quick Start¶

Getting started with using Lifecycle Twin APIs involves the following steps:

1. Create an account and a machine user.
2. Create a JSON Web Token (JWT) by using the machine user credentials.
3. Make API requests using the JWT.

Create an account and a machine user¶

The Getting Started page documents the required steps to get a hold of the clientId, clientSecret.

Create a token¶

Use the values described in the Authorization- section to construct the Create Token request.

Example request¶

export CLIENT_ID=<YOUR_CLIENT_ID>
export CLIENT_SECRET=<YOUR_CLIENT_SECRET>

curl https://eu.buildingx.siemens.com/oauth/token \
  -H 'content-type: application/json' \
  -d "{
            \"client_id\":\"$CLIENT_ID\",
            \"client_secret\":\"$CLIENT_SECRET\",
            \"audience\":\"https://horizon.siemens.com\",
            \"grant_type\":\"client_credentials\"
      }"

To run this example yourself, set the CLIENT_ID and CLIENT_SECRET first.

Example response¶

{
  "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt",
  "token_type": "Bearer",
  "expires_in": 86400
}

The token, or JWT (JSON Web Token), is the value of the access_token-property in the response. You can now use it by passing it in the Authorization-header of any subsequent API requests. The expires_in-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token.

Now you have all you need to start using the API. As a last step of preparation set the token and your client name as environmental variables.

export CLIENT_NAME=<YOUR_CLIENT_NAME>
export TOKEN=<YOUR_TOKEN>

Make API requests¶

This guide will take you through the steps you need to perform to read information about a Site and the Assets, Components and Documents contained within it. We will assume you don't yet know the id of the Site, meaning that before you can retrieve Assets or Documents you must first discover the Site by listing your client projects.

List your Sites¶

The first step to perform is to list the Sites (portfolios) you have access to. This you can do by performing the List Client Projects operation.

curl "https://eu.buildingx.siemens.com/api/lifecycletwin/clientprojects" \
    -H "clientname: $CLIENT_NAME" \
    -H "Authorization: Bearer $TOKEN" \
    -H "select: {\"Name\", \"Id\", \"CityName\", \"Location\": {\"Id\", \"Name\"}}"

The response contains all sites available to your account. If you have a large number of sites you may need to retrieve multiple pages — use the pagination header as described in the Querying guide.

The most important properties returned for each site are:

Select the Id property of one of the sites in the response and set it in an environmental variable. E.g. if the Id is 8db4216d-61c5-4e79-8558-164aa179bfe9 then set it using the following command:

export PROJECT_ID=8db4216d-61c5-4e79-8558-164aa179bfe9

List Assets¶

The next step is to list the assets (components and equipment) registered in your site. This is achieved by using the List Assets operation.

curl "https://eu.buildingx.siemens.com/api/lifecycletwin/assets" \
    -H "clientname: $CLIENT_NAME" \
    -H "Authorization: Bearer $TOKEN" \
    -H "projectId: $PROJECT_ID" \
    -H "select: {\"Id\", \"Name\", \"Category\": {\"Id\", \"Name\"}}"

The response contains all assets (components) for the given site. You can narrow results using the filter header — for example, to find assets by name:

curl "https://eu.buildingx.siemens.com/api/lifecycletwin/assets" \
    -H "clientname: $CLIENT_NAME" \
    -H "Authorization: Bearer $TOKEN" \
    -H "projectId: $PROJECT_ID" \
    -H "filter: {\"contains\": {\"Name\": \"Pump\"}}" \
    -H "select: {\"Id\", \"Name\", \"Category\": {\"Id\", \"Name\"}}"

Select the Id property of the asset you want to inspect and store it in the ASSET_ID environmental variable. E.g.

export ASSET_ID=a850ec9a-daf6-4630-9c22-af680e82b3a4

List Documents¶

To retrieve documents associated with a site, the List Documents operation can be used. Documents include drawings, manuals, floor plans, and 3D models.

curl "https://eu.buildingx.siemens.com/api/lifecycletwin/documents" \
    -H "clientname: $CLIENT_NAME" \
    -H "Authorization: Bearer $TOKEN" \
    -H "projectId: $PROJECT_ID" \
    -H "select: {\"Id\", \"Name\", \"CreatedOn\"}"

In the response, you will find the documents associated with the site, e.g. drawings or manuals.

Create Asset¶

To create a new asset, the Create Asset operation can be used:

curl -X 'POST' \
  "https://eu.buildingx.siemens.com/api/lifecycletwin/assets" \
  -H "Accept: application/json" \
  -H "clientname: $CLIENT_NAME" \
  -H "Authorization: Bearer $TOKEN" \
  -H "projectId: $PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"Name\": \"string\",
    \"Category\": {
      \"Id\": \"string\"
    }
  }"

In the response, you will find the asset created with the given Name and Category.