Skip to main content

Atrius API

Updated over a week ago

👍 This article will help you:

  • Set up OAuth 2.0 authentication for the Atrius API

  • Create buildings and data points (meters) programmatically

  • Push time series data to Atrius via API

  • Pull data from Atrius for external analysis

  • Troubleshoot your Atrius API integration

To view your current Atrius API integration details and status, go to Settings on the left side menu, select Integrations, then select Atrius API.

Overview

The Atrius API allows structured data transmission via JSON messages over HTTPS requests using OAuth 2.0 authentication. This method enables programmatic integration by sending JSON data in the request body, making it ideal for custom applications and automated data workflows.
​

Step-by-step workflow:

  1. Create Admin User Account - Set up administrative user in Atrius for exclusive use with the API Client

  2. Generate API Client Account - Create API client via Developer API

  3. Record API Credentials - Save your Client ID and Client Secret

  4. Create Gateway - Set up an API gateway integration in Atrius

  5. Obtain OAuth Token - Request an access token using your credentials

  6. Get Organization & Building IDs - Retrieve existing building information

  7. Create or Select Building - Identify or create the building for your data points

  8. Create Meters (Data Points) - Define meters with metadata and configuration

  9. Push Time Series Data - Send readings to your meter using the meter UUID

  10. Verify Data - Confirm data appears correctly in Atrius data managers

Each of these steps is detailed in the sections below.

Prerequisites

  • Network Access - Outbound HTTPS (port 443) to api.buildingos.com

  • Postman - Tool for creating and testing API messages (Download Postman)

  • API Command Collection – Link Here

  • Text Editor - Notepad, VS Code, or similar

  • JSON Viewer - For validating JSON payloads (Json Parser Online)

  • Terminal (Linux)/Command Prompt (Windows) - For executing cURL commands

  • Python (optional) - For automation scripts

Account & Credentials Setup

Step 1: Create Admin User Account

  1. Navigate to https://buildingos.com/users/

  2. Create an administrative user account

  3. Verify you have appropriate permissions for API access

When creating your admin user account, we recommend setting up a dedicated user exclusively for API use rather than tying it to an individual's personal account. This ensures uninterrupted access if personnel changes occur. The account requires an email address, but it does not need to be a valid or active mailbox. For example, the following format works well: APIUser@yourcompanydomain.com

Step 2: Generate API Client Account

  1. Navigate to https://buildingos.com/developers/

  2. Click Add an API Client

  3. Enter a descriptive API Client name

  4. Select Client Type (Confidential is preferred)

  5. Select Authorization grant (Client credentials is preferred)

  6. Enter any redirect uri's (optional)

  7. For Assigned User, select the Admin User created in Step 1

  8. Select Save

A new row will populate the table on the Developer API page, providing the Client ID & Client Secret.

Step 3: Record API Client Credentials

From the Developer API page, record the following:

  • Client ID - Your unique API client identifier

  • Client Secret - Your authentication secret (keep this secure)

Store these credentials securely. The Client Secret should be treated like a password and never shared publicly.

Gateway Configuration

Step 4: Create Gateway

  1. Navigate to https://buildingos.com/services/connect

  2. Select Atrius API as your integration type

  3. Select Add a Gateway

  4. Select Set up Gateway

  5. Assign your API user to this integration

  6. Record the 5-digit Gateway Number from the URL (e.g., https://buildingos.com/gateways/xxxxx)

Record for later use:

  • Gateway Number (e.g., xxxxx)

  • Client ID

  • Client Secret

Step 5: Obtain OAuth Token

All API requests require an OAuth 2.0 access token. Request a token using your Client ID and Client Secret.
​

Token Request:

POST

curl --location 'https://api.buildingos.com/o/token/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=YOUR_CLIENT_ID' \ --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \ --data-urlencode 'grant_type=client_credentials'

Response example:

{   "access_token": "<YOUR_ACCESS_TOKEN>",   "expires_in": 36000,   "token_type": "Bearer",   "scope": "read write" }

Save the access_token - You'll include this in the Authorization header of all subsequent API requests.

Access tokens expire after the time specified in expires_in (in seconds). Request a new token when needed.

Building & Meter Setup

Step 6: Get Organization number & Building IDs

Retrieve Organization ID

First, get your organization ID from your gateway:

GET

curl --location 'https://api.buildingos.com/gateways/YOUR_GATEWAY_NUMBER' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response example:

{   "data": {     "id": "xxxxx",     "object": "gateway",     "organization": "https://api.buildingos.com/organizations/xxxx"   } }

Record the organization number from the URL (e.g., xxxx).
​

List Existing Buildings

GET

curl --location 'https://api.buildingos.com/buildings/' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response example:

{   "results": [     {       "id": "xxxxxx",       "uuid": "UNIQUE_UUID_HERE",       "enabled": true,       "name": "Building Name Here",       "organization": "https://api.buildingos.com/organizations/xxxx"     }   ] }

Record the Building ID (e.g., xxxxxx) if your building already exists, or proceed to Step 7 to create a new building.

Step 7: Create or Select Building

If Your Building Already Exists:

Use the Building ID from Step 6.
​

If You Need to Create a New Building:

POST

curl --location 'https://api.buildingos.com/buildings/' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{   "organization": xxxx,   "name": "Your Building Name",   "postalCode": "12345" }'

Response Example:

{   "id": "176498",   "name": "Your Building Name",   "organization": "https://api.buildingos.com/organizations/6732" }

Record the Building ID from the response.

Step 8: Create Meters (Data Points)

Create a meter (data point) in Atrius by defining its metadata and configuration.

API Request:

POST

curl --location 'https://api.buildingos.com/meters/' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{   "building": "xxxxxx",   "status": "online",   "gateway": xxxxx,   "storageUnit": "x",   "displayUnit": "x",   "displayName": "Meter Display Name Here",   "sourceUnit": "x",   "resourceType": "Resource Type Here",   "vendorMeterId": "Meter_ID_Here",   "defaultTimescale": "month",   "scope": "submeter",   "readingType": "instantaneous" }'

Required Fields:

See Definitions List here.

  • building - Building ID from Step 7

  • gateway - Gateway number from Step 4

  • displayName - Human-readable name for the meter

  • resourceType - Type of resource (e.g., "temperature", "electricity", "gas", "water")

  • readingType - How data should be interpreted:

    • "instantaneous" - Current reading at each timestamp

    • "cumulative" - Accumulated total since start

  • storageUnit - Unit code for how data is stored (see Unit Reference)

  • displayUnit - Unit code for display

  • sourceUnit - Unit code from source system

  • scope - "building" or "submeter"

Response:

{   "uuid": "Meter_UUID_Returned_Here",   "id": "xxxxx",   "displayName": "Meter Display Name Here",   "resourceType": "Resource Type Here" }

Save the uuid - This is required for pushing time series data.

Other Useful Commands:

Get a List of Points

GET

curl --location --request GET 'https://api.buildingos.com/meters/' --header 'Authorization: Bearer <access_token>'

Get data from a specific point

GET

curl --location --request GET 'https://api.buildingos.com/meters/<UUID>/data/?start=YYYY-MM-DD&end=YYYY-MM-DD&resolution=live' --header 'Authorization: Bearer <access_token>'

Resource Types & Units

For a complete list of resource types and unit codes, refer to the API Unit Reference.

Common resource types:

  • electricity - Electrical consumption

  • gas - Natural gas consumption

  • water - Water consumption

  • temperature - Temperature readings

  • steam - Steam consumption

Sending Data to Atrius

Step 9: Push Time Series Data

Send time series readings to your meter using the UUID from Step 8.

API Request:

POST

curl --location 'https://api.buildingos.com/gateways/xxxxx/data' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{   "meta": {     "naive_timestamp_utc": false   },   "data": {     "Meter_UUID_Here": [       ["2024-01-15T10:00:00Z", 72.5],       ["2024-01-15T10:15:00Z", 73.2],       ["2024-01-15T10:30:00Z", 72.8]     ]   } }'

Data Format:

  • meta.naive_timestamp_utc - Set to false if timestamps include timezone information (recommended)

  • data - Object containing meter UUIDs as keys

  • Each UUID contains an array of [timestamp, value] pairs

  • Timestamps - ISO 8601 format with timezone (e.g., "2024-01-15T10:00:00Z")

  • Values - Numeric readings in the source unit specified in Step 8

Multiple Meters:

You can send data for multiple meters in a single request:
​

POST

{   "meta": {     "naive_timestamp_utc": false   },   "data": {     "Meter1_UUID_Here": [       ["2024-01-15T10:00:00Z", 72.5]     ],     "Meter2_UUID_Here": [       ["2024-01-15T10:00:00Z", 150.3]     ]   } }

Step 10: Verify Data

  1. Log into Atrius Energy

  2. Navigate to the building data was recently uploaded to > Points

  3. Select the meter you created

  4. Verify that time series data appears correctly

  5. Check that timestamps and values match your API payload

If data doesn't appear:

  • Wait a few minutes and refresh your browser

  • Verify the meter UUID matches what you used in the API request

  • Check that timestamps are in the correct format

  • Ensure values are numeric (not strings)

Pulling Data from Atrius

You can also retrieve data from Atrius for external analysis or reporting.

Get List of Meters:

GET

curl --location 'https://api.buildingos.com/meters/' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Retrieve Time Series Data:

GET

curl --location 'https://api.buildingos.com/meters/METER_UUID/data/?start=2024-01-01&end=2024-01-31&resolution=live' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Query Parameters:

  • start - Start date (YYYY-MM-DD)

  • end - End date (YYYY-MM-DD)

  • resolution - Data resolution (live, hour, day, month)

Troubleshooting

Review the scenarios below to diagnose problems with your integration.

Authentication Errors (401 Unauthorized)

  • Verify your access token is valid - Tokens expire after the time specified in the initial response

  • Request a new token - Use the OAuth endpoint with your Client ID and Client Secret

  • Check credentials - Ensure Client ID and Client Secret are correct

  • Verify token format - Include "Bearer " prefix in Authorization header

Gateway Number Changed

  • Navigate to Settings > Integrations > Atrius API

  • Click on your gateway to view the current Gateway Number in the URL

  • Update your scripts with the new Gateway Number

API Credentials Changed

  • Generate new credentials at https://buildingos.com/developers/

  • Update your scripts and applications with new Client ID and Client Secret

  • Request a new access token using updated credentials

Data Not Appearing in Atrius

  • Verify meter UUID - Ensure you're using the correct UUID from the meter creation response

  • Check timestamp format - Use ISO 8601 format with timezone (e.g., "2024-01-15T10:00:00Z")

  • Verify values are numeric - Strings, null values, or blank values will not be ingested

  • Check reading type - Ensure reading type (instantaneous vs cumulative) matches your data

  • Wait and refresh - Data may take a few minutes to appear; refresh your browser

Network Connectivity Issues

  • Verify DNS resolution - Test with ping api.buildingos.com

  • Check network routing - Use traceroute/tracert to api.buildingos.com

    • Windows: tracert api.buildingos.com

    • Linux/Mac: traceroute api.buildingos.com

  • Verify firewall rules - Ensure outbound HTTPS (port 443) is allowed

  • Check proxy settings - If behind a proxy, configure your API client accordingly

Invalid JSON Payload

  • Validate JSON syntax - Use a JSON validator before sending requests

  • Check data types - Ensure numbers are not quoted, booleans are true/false (not strings)

  • Verify required fields - All required fields must be included in meter creation

  • Check unit codes - Ensure unit codes are valid (see Unit Reference)

Rate Limiting

If you receive rate limit errors:

  • Reduce request frequency - Implement delays between requests

  • Batch data points - Send multiple readings in a single request when possible

  • Contact support - If rate limit errors persist, contact support@atrius.com for assistance

Best Practices

  • Security - Store API credentials securely

  • Use environment variables - Store Client ID and Client Secret as environment variables

  • Token management - Implement token refresh logic before expiration

  • TLS/SSL - Ensure TLS 1.2 or later is enabled for all API connections

  • Error handling - Implement robust error handling and logging in your scripts

  • Batch requests - Send data for multiple meters in a single request when possible

  • Avoid large payloads - Keep individual requests under reasonable size limits

  • Validate data - Check data quality before pushing to Atrius

  • Monitor integration health - Regularly verify data is flowing correctly

  • Keep credentials updated - Rotate API credentials periodically for security

Automation Examples

Python Script for Pushing Data

python

import requests import json from datetime import datetime  # Configuration CLIENT_ID = 'your_client_id' CLIENT_SECRET = 'your_client_secret' GATEWAY_NUMBER = 'xxxxx' METER_UUID = 'Meter_UUID_Here'  # Get OAuth token def get_token():     url = 'https://api.buildingos.com/o/token/'     data = {         'client_id': CLIENT_ID,         'client_secret': CLIENT_SECRET,         'grant_type': 'client_credentials'     }     response = requests.post(url, data=data)     return response.json()['access_token']  # Push time series data def push_data(token, readings):     url = f'https://api.buildingos.com/gateways/{GATEWAY_NUMBER}/data'     headers = {         'Authorization': f'Bearer {token}',         'Content-Type': 'application/json'     }     payload = {         'meta': {'naive_timestamp_utc': False},         'data': {METER_UUID: readings}     }     response = requests.post(url, headers=headers, json=payload)     return response.status_code  # Example usage token = get_token() readings = [     ["2024-01-15T10:00:00Z", 72.5],     ["2024-01-15T10:15:00Z", 73.2] ] status = push_data(token, readings) print(f"Data push status: {status}")

Schedule with Cron (Linux/Mac)

# Run every hour 0 * * * * /usr/bin/python3 /path/to/push_data.py

Schedule with Task Scheduler (Windows)

  1. Open Task Scheduler

  2. Create a new task

  3. Set trigger (e.g., hourly)

  4. Set action to run your Python script

  5. Save and enable

Additional Resources

🚧 Forward to Additional Contacts

Please forward this information to any additional IT, Development, or Integration points of contact at your organization for implementation support.
​

👍 Contact Customer Support

For additional questions regarding your integration with Atrius, please contact Customer Support at support@atrius.com

Frequently Asked Questions

Q: How long do access tokens last? A: Access tokens typically expire after 10 hours (36,000 seconds). Implement token refresh logic in your applications.

Q: Can I create multiple meters in a single request? A: No, meters must be created individually. However, you can push data for multiple meters in a single data push request.

Q: What timestamp format should I use? A: Use ISO 8601 format with timezone information (e.g., "2024-01-15T10:00:00Z" or "2024-01-15T10:00:00-05:00").

Q: Can I update existing meter metadata? A: Yes, use a PATCH or PUT request to the meter endpoint with the meter UUID.

Q: What's the difference between instantaneous and cumulative reading types? A: Instantaneous represents the current value at each timestamp (e.g., temperature). Cumulative represents accumulated totals (e.g., total energy consumed).

Q: How do I find the correct unit codes? A: Refer to the API Unit Reference for a complete list of supported units.

Q: Can I backfill historical data? A: Yes, you can push historical data by including past timestamps in your data payload.

Q: Is there a limit on how much data I can push at once? A: While there's no strict limit, keep payloads reasonable (recommend < 1000 data points per request) for optimal performance.

Q: How do I delete a meter? A: Contact Customer Support for assistance with deleting meters or modifying integration configurations.

Related Articles
Atrius CSV
EC-Net Facilities & Niagara 4 (N4)
Developer API
Atrius Energy & Sustainability Standard Integrations
Atrius CSV (SFTP Method)
Did this answer your question?