Beam Dynamics | Asset Intelligence Platform

Beam exposes a set of REST APIs for managing various resources. The following guide will explain how to authenticate and interact with these APIs.

min read

Written by

Beam Dynamics

Authentication

API Keys

Beam uses API keys to authenticate requests and determine which resources it can access. Use the API Keys page in the application to create and expire keys.

Create an API Key

In the Beam application, navigate to the API Keys page by going to Configuration > Integrations.
Click “Create API Key”.
Provide the key with a name that you can use to identify it later, assign it a role and a group. Read more in the Permissions section.
Copy the API key to a secure location.

NOTE: API keys are shown only once and are not stored by Beam. There is no way for Beam staff to retrieve or view your keys, so make sure you keep it safe. If you lose it, you will need to create a new one.

Delete an API key

API keys do not currently expire and cannot currently be rolled. If you need to revoke access, you will need to delete the key. If you want to roll a key, you will need to delete the current key and create a new one.

In the Beam application, navigate to the API Keys page by going to Configuration > Integrations.
Open the menu to the right of a key and click “Delete”

Permissions

API keys behave as if they were a user. This means that they can be assigned a role and a user group and will inherit those same permissions. For more information on managing permissions, see the in-app user access guide.

API Reference

Beam provides a Swagger UI detailing the API specification. There is also a JSON OpenAPI spec available.

‍

Make Requests

Authenticating a Request

Requests require a Beam-Api-Key header with a valid API key.

Pagination

The Beam API has list endpoints that can return multiple objects. These endpoints will not return all results at once and pagination can be used to traverse the list.

Limit

Limit how many results you get per page by sending the limit query parameter. This defaults to 20 and the max is 100.

Page

Traverse pages by passing the page query parameter. This defaults to 1.

Response body

Paginated responses will be returned with the following structure:‍

type Response = {
  total: number;
  currentPage: number;
  totalPages: number;
  hasMore: boolean;
  results: unknown[];
};

‍

total : The total number of resources across all pages.
currentPage : The current page number.
totalPages : The total number of pages.
hasMore : True if the current page is not the last, otherwise false.
results : An array of resource objects.

Rate Limits

Beam enforces a rate limit of 20 requests per second. Applications exceeding this limit will receive a 429 Too Many Requests response.

Search and Query Language

Some API resources support searching via a query string. This helps clients narrow down result sets. Not all fields are searchable and the available properties are detailed below.

Search Query Language

Query structure and terminology

A query consists of multiple clause joined by AND . Currently OR is not supported, neither is grouping multiple clause. A clause consists of a field followed by an operator followed by a value .

An example clause :

`clause`	`name:"john"`
`field`	`name`
`operator`	`:`
`value`	`john`

Negating a query

You can negate a query clause by using the - character. For example, the following search returns records that don’t match the name "john": -name:"john"

Value types

Each value must be one of the following types. Different value types have varying operator support, which will be discussed in the Operators section below.

Type	Description	Supported operators
string	Strings must be surrounded by double quotes. E.g. `"john"` . Strings that are not quoted will be rejected. Quotes can be escaped using the `\` character. For example `"Nested \"quote\""`	`:` , `~`
number		`>` , `<` , `=`
boolean	Use `true` or `false`	`:`
null	`null` represents something that does not exist.	`:`
array	You can pass an array of values. Arrays must be all the same type, you cannot mix types. For example: `["one", "two", "three"]` or `[1, 2, 3]` but you cannot do `["one", 2]`	`:` , `~`

Operators

The following operators can be used to change how the value criteria are evaluated.

Operator	Usage	Description	Examples
`:`	`name:"John"`	Exact match, ( case insensitive )	`name:"John"` returns all records where the name is "John" or "john".
`~`	`name~"John"`	Substring match, ( case insensitive )	`name~"John"` returns matches for "John" and "xjohn"
`>` , `<` , `=`	`age>20` `age<20` `age>=20` `age<=20`	Greater than, less than operators.	`age>20` returns all records with an `age` property greater than 20.

Supported query fields by resource

Inventory

Property	Value type	Description
`search`	string	General asset search.
`products.name`	string	Product name.
`products.model`	string	Product model number.
`manufacturer.name`	string	Product manufacturer name.
`serial`	string	Inventory serial number.
`fields.{fieldId}`	mixed	Custom field. Replace `{fieldId}` with the custom field ID and use the appropriate value type for that field.

Products

Property	Value type	Description
`search`	string	General product search.
`name`	string	Product name.
`modelNumber`	string	Product model number.
`manufacturer.name`	string	Product manufacturer name.
`customFields.{fieldId}`	mixed	Custom field. Replace `{fieldId}` with the custom field ID and use the appropriate value type for that field.

Tickets

Property	Value type	Description
`ticketTypeId`	string	The ticket type ID.
`asset.id`	string	Asset/Inventory ID attached to the ticket.