Quick Start¶

Welcome to the Fire API Quick Start guide! This document will walk you through the essential steps to authenticate and interact with the Fire APIs, from account creation to making your first API requests.

Prerequisites¶

Before you begin, ensure you have:

• Access to the Fire API portal.
• Credentials for a machine user (clientId, clientSecret, and partitionId).
• A terminal environment (Linux/MacOS shell or Windows command prompt).
• curl installed, or another HTTP client of your choice.

Step 1: Create an Account and Machine User¶

To access the Fire APIs, you need to create an account and register a machine user. Follow the instructions in the Getting Started guide to obtain your clientId, clientSecret, and partitionId.

Step 2: Obtain a JSON Web Token (JWT)¶

Authenticate your machine user by generating a JWT. This token will be used to authorize your API requests.

Example: Generate a Token¶

Set your credentials as environment variables:

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

Endpoint: POST https://siemens-bt-015.eu.auth0.com/oauth/token

Body Parameters:

• client_id (string, required): Your machine user's client ID.
• client_secret (string, required): Your machine user's client secret.
• audience (string, required): The audience for the token, typically the API identifier.
• grant_type (string, required): The OAuth2 grant type, usually client_credentials.

Example:

curl https://siemens-bt-015.eu.auth0.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\"
            }"

Note:

• The above example uses a Linux/MacOS shell. On Windows, use set instead of export.
• You can use any HTTP client or programming language to make these requests.

Example Response¶

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

• The access_token is your JWT.
• The expires_in value (in seconds) indicates how long the token is valid (typically 24 hours).

Set your token and partition as environment variables for convenience:

export PARTITION=<YOUR_PARTITION_ID>
export TOKEN=<YOUR_TOKEN>

Step 3: Make API Requests¶

With your token and partition ID, you can now interact with the Fire API.

3.1 List Locations¶

Retrieve all buildings (locations) within your partition.

Endpoint: GET partitions/{$partitionId}/locations

Path Parameters:

• partitionId (string, required): The unique identifier of the partition.

Example:

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/fire/partitions/$PARTITION/locations"

• The response includes a list of locations, each with an id property.
• For large partitions, refer to the Pagination section.

Store a location ID for later use:

export LOCATION=<LOCATION_ID>

3.2 Get Location by ID¶

Retrieve details for a specific location.

Endpoint: GET partitions/{$partitionId}/locations/{$locationId}

Path Parameters:

• partitionId (string, required): The unique identifier of the partition.
• locationId (string, required): The unique identifier of the location.

Example:

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/fire/partitions/$PARTITION/locations/$LOCATION"

• Replace $LOCATION with the desired location ID.

3.3 List Devices¶

List all devices in your selected building.

Endpoint: GET partitions/{$partitionId}/devices

Path Parameters:

• partitionId (string, required): The unique identifier of the partition.

Example:

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/fire/partitions/$PARTITION/devices"

• Devices are associated with locations (buildings).

3.4 List Events¶

Retrieve past events and alarms for a specific device. You can filter events based on timestamp ranges using query parameters.

Endpoint: GET partitions/{$partitionId}/devices/{$deviceId}/events

Path Parameters:

• partitionId (string, required): The unique identifier of the partition.
• deviceId (string, required): The unique identifier of the device.

Query Parameters:

• filter[timestamp][from] (string, optional): Start of the timestamp range (ISO 8601 format).
• filter[timestamp][to] (string, optional): End of the timestamp range (ISO 8601 format).

Example:

curl -G -H "Authorization: Bearer $TOKEN" \
    --data-urlencode "filter[timestamp][from]=2024-05-01T00:00:00Z" \
    --data-urlencode "filter[timestamp][to]=2024-05-31T23:59:59Z" \
    "https://api.bpcloud.siemens.com/fire/partitions/$PARTITION/devices/$DEVICE/events"

• Replace the timestamp values with your desired date and time range in ISO 8601 format.
• The response will include events within the specified time window.

3.5 Get Location Configuration¶

Retrieves the configuration details for a specific location. This endpoint allows clients to fetch settings and parameters associated with a given location, such as thresholds, enabled features, and other configuration elements.

Endpoint: GET partitions/{$partitionId}/locations/{$locationId}/configuration

Path Parameters:

• partitionId (string, required): The unique identifier of the partition.
• locationId (string, required): The unique identifier of the location.

Example:

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/fire/partitions/$PARTITION/locations/$LOCATION/configuration"

3.6 Get Last Values for Points¶

Fetch the most recent values for specified points. This endpoint is useful for monitoring and displaying the latest state or value of various points.

Endpoint: GET partitions/{$partitionId}/points/lastValues

Path Parameters:

• partitionId (string, required): The unique identifier of the partition.

Query Parameters:

• pointIds (string, required): Comma-separated point IDs to retrieve the last values for. Note: You can specify up to 50 point IDs per request.
• lastChangedLatest (string, optional): Only return the latest value for each point up to and including this timestamp (ISO 8601 format).

Example:

curl -G -H "Authorization: Bearer $TOKEN" \
    --data-urlencode "pointIds=<POINT_ID_1>,<POINT_ID_2>" \
    --data-urlencode "lastChangedLatest=2024-06-01T12:00:00Z" \
    "https://api.bpcloud.siemens.com/fire/partitions/$PARTITION/points/lastValues"

• Replace <POINT_ID_1>, <POINT_ID_2>, etc., with the desired point IDs (up to 50 per request).
• Set lastChangedLatest to the latest timestamp you want to include (optional).
• The response will include the latest values for each specified point, up to the given timestamp if provided.

Response¶

The response contains an array of objects, each representing the last value for a requested point. Each object includes at least the following fields:

• id: The point ID.
• value: The latest value for the point.
• createdAt: The timestamp when the value was recorded.

Depending on the point type, the value and additional fields may vary. Below are examples of possible responses for different point types:

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "value": "TEST_SUCCESSFUL",
    "createdAt": "2021-03-08T13:51:40.541Z"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": "NORMAL"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": "TEST_SUCCESSFUL"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": "14.32"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": "82"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": "82"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": "MEDIUM"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": "10"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": "MINOR"
}

{
    "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725",
    "createdAt": "2021-03-08T13:51:40.541Z",
    "value": 12
}

Note:
The response of the lastValue API can be any of these types, and each response will always include at least value, createdAt, and id fields. Refer to the API documentation for the full list of supported point types and value formats.

Example:

curl -G -H "Authorization: Bearer $TOKEN" \
        --data-urlencode "pointIds=<POINT_ID_1>,<POINT_ID_2>" \
        --data-urlencode "lastChangedLatest=2024-06-01T12:00:00Z" \
        "https://api.bpcloud.siemens.com/fire/partitions/$PARTITION/points/lastValues"

• Replace <POINT_ID_1>, <POINT_ID_2>, etc., with the desired point IDs (up to 50 per request).
• Set lastChangedLatest to the latest timestamp you want to include (optional).
• The response will include the latest values for each specified point, up to the given timestamp if provided.

Note:
For more information on deprecation policies, pagination, filtering, and error handling, see the Developer's Guide.

Visual Overview¶

Configuration API usage¶

You are now ready to start building with the Fire API! For advanced usage, troubleshooting, and best practices, consult the Developer's Guide.