API Documentation
Summary
The Bluerithm API allows you to programmatically access data from your Bluerithm account and projects.
Authentication
The Bluerithm API uses API keys to authenticate requests. Account Admins view and manage API keys in the new Bluerithm on Home > API keys, or in the legacy web app on the My Company > Admin > API Keys page.
API requests also need to include your Tenant ID in the header (a key called x-tenant-id with your tenant ID as the value). You can find and copy your tenant ID on the same API keys tab, or on the My Company > Admin > API Keys page in the legacy web app. Your API keys carry many privileges and must be stored securely. Do not share your secret API keys.
Authentication to the API is performed via API Key authentication. Provide your API key x-api-key value when making calls to the API.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Rate limits
Requests to the v2 API made with an API key are limited per account. Every key on your account shares the same allowance:
- Up to 4 requests at a time. More wait their turn.
- About 10 requests a second, with short bursts allowed.
- A request that has to wait for its turn counts twice toward the per-second allowance, so many requests sent in parallel reach the limit sooner than the same requests sent one after another.
A request over the limit answers 429 Too Many Requests with a Retry-After header that gives the number of seconds to wait. Wait that long, then send the request again. Integrations running in a browser can read the header too. The limits may change, so always follow Retry-After rather than building in a fixed rate.
Using Bluerithm itself, in the browser or the installed app, is never limited.
When an API key stops working
A key stops working as soon as it is deleted, or as soon as the person who created it is removed from the account or set to Not Active: requests made with it answer 401 Unauthorized . Requests made with a key act as the person who created it, so create a new key while signed in as an active Account Admin to continue.
Miscellaneous
Any “ID” referred to for query parameters will always be a unique ID that matches up to a database record, and not a editable field in Bluerithm. If needed, you can usually find the ID of an item in the url when viewing items in the Bluerithm web app.
Depending on the dataset you want to create with API calls, sometimes you'll need to do recursive API calls to get a complete set if the items you need are children of a parent item.
Endpoint definitions
You can find definitions for all endpoints here:
v2: https://api.bluerithm.com/v2/swagger/index.html
Development and Testing
We recommend a tool like Postman for testing your authentication and calls to the API.