API Basics

Overview

The Jetstream API enables you, a developer, to configure and query your Terso RFID devices and Jetstream application – allowing you to quickly enhance your business applications with RFID inventory tracking and management capabilities.

Navigating the API Documentation

The page tree on the left helps you quickly jump between different sections and pages.

The table of contents on the right helps you quickly jump between different sections within the current page.

The search bar in the top right can be used to search on any content, on any page, for any version of the API.

The API Basics page contains everything you need to know about how to get requests to and responses from Jetstream, along with reference information like version changes and a glossary.

The Device Types section of the API Documentation tells you more about the various types of Terso RFID Devices that can be managed via Jetstream, including their commands, configuration parameters, logentryevents, and sensors.

The API Endpoints section contain detailed documentation of the various Jetstream API command and configuration endpoints, including descriptions, parameters, examples, and version changes.

Finally, the Events section details the purpose, fields, examples, and version changes for each type of event.

You can quickly flip between Jetstream API Versions using the API Version Selector in the top right. We always recommend using the latest version.

Exploring Jetstream with Postman

Postman is a powerful tool that allows easy testing and experimenting of APIs. To start using Jetstream in Postman, first download and install Postman.

Once installed, click the "Run in Postman" button. Select the installed Postman application from the prompt.

Postman will open, and the collection of API endpoints will be imported. This collection contains all available endpoints in the API along with comments on the purpose of each endpoint.

An environment named "Jetstream" will also have been imported. This collection uses two global variables, "BaseUrl" and "UserAccessKey." The "BaseUrl" variable will be initialized to the url of the Jetstream API. The "UserAccessKey" variable will be initialized to the your current user access key if you are logged in. This can be changed in Postman if you desire to use a different key. If you do not have a key, sign up for one. (See Postman's documentation for more info on altering environment variables.)

Tools

A .NET SDK and Service Base are available on Github.

Additional Resources

• Release Notes
• Guides for Common Workflows

How It Works

Jetstream facilitates communication:

1. Between your remotely deployed Terso RFID device and your in-house developed application that consumes Jetstream messages.
2. Between your Jetstream application and your in-house developed application that consumes Jetstream messages.

Let’s take a look at each communication path in more detail.

Request

Base URL

The base URL for this version of the Jetstream API is https://api.jetstreamrfid.com/3. Note the current version number in the URL, as well as the new domain name.

All requests to the Jetstream API must be made over HTTPS with TLS 1.2 or higher. HTTP requests and HTTPS requests using TLS 1.1 or earlier will not work.

Authentication

All requests to the Jetstream API require authentication via a user access key. In the request header, set a 'AccessKey' key with your user access key as the value. A user access key is provided during user account sign up and is associated to a Jetstream application. A user access key is unique to a user and should be securely stored.

Data Format

The Jetstream API accepts and sends data as JSON. For endpoints that send JSON data, define the header request’s ‘Content-Type’ key with a value of ‘application/json’.

HTTP Verbs

The below HTTP verbs are used by the Jetstream API.

Response

The Jetstream API returns data as JSON.

The below HTTP status codes are used by the Jetstream API.

Search & Sort

Searching and/or sorting allows you to slim down the returned data, ensuring you only focus on the data you need.

Search and/or sort large result sets via passing parameters in the URL by including a query string. The details for each query type are outlined below.

Search 

Search can be used on its own, separate from sort, as follows:

Search on One Property

In this example, we will be using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application containing the name "beer". Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=beer

Notes

• The "https://api.jetstreamrfid.com/3/devices" section of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The "name" parameter is a property of the Device resource. Not all properties of a resource are searchable. See the Parameters table for each endpoint to determine which properties are searchable.
• The returned search results will contain devices with a name containing AND equal to "beer".

What if you wanted to find all devices in your Jetstream application containing the names "beer" and "cheese"? It’s possible and here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=beer,cheese

Notes

• The "," character is used to separate multiple values. There should be no space following the comma.
• The returned search results will contain:
  • Devices with a name containing AND equal to "beer"
  AND
  • Devices with a name containing AND equal to "cheese"

Search on Multiple Properties

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application containing the name "beer", the serial number "1234", and the region "US". Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=beer&serialnumber=1234&region=us

Notes

• The "https://api.jetstreamrfid.com/3/devices" section of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The "name", "serial number", and "region" parameters are all properties of the Device resource. Not all properties of a resource are searchable. See the Parameters table for each endpoint to determine which properties are searchable.
• The "&" character is used to separate multiple parameters. There should be no spaces preceding or following the ampersand.
• The returned search results will contain:
  • Devices with a name containing AND equal to "beer"
  AND
  • Devices with a serial number containing AND equal to "1234"
  AND
  • Devices with a region containing AND equal to "us"

What if you wanted to find all devices in your Jetstream application containing the names "beer" and "cheese", the serial numbers "1234" and "4321", and the regions "US" and "AP"? It’s possible and here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=beer,cheese&serialnumber=1234,4321&region=us,ap

Notes

• The "," character is used to separate multiple values. There should be no space following the comma.
• The returned search results will contain:
  • Devices with a name containing AND equal to "beer"
  AND
  • Devices with a name containing AND equal to "cheese"
  AND
  • Devices with a serial number containing AND equal to "1234"
  AND
  • Devices with a serial number containing AND equal to "4321"
  AND
  • Devices with a region containing AND equal to "us"
  AND
  • Devices with a region containing AND equal to "ap"

Search Exclusion on One Property

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application not containing the name "beer". Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=!beer

Notes

• The "https://api.jetstreamrfid.com/3/devices" section of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The "name" parameter is a property of the Device resource. Not all properties of a resource are searchable. See the Parameters table for each endpoint to determine which properties are searchable.
• The "!" character is used to exclude results. It must precede the value to be excluded.
• The returned search results will contain devices with names that do not contain or are not equal to "beer".

What if you wanted to find all devices in your Jetstream application not containing the names "beer" and "cheese"? It’s possible and here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=!beer,cheese

Notes

• The "!" character is used to exclude results. It must precede the first value to be excluded, and you only need one "!" before all excluded values.
• The "," character is used to separate multiple values. There should be no space following the comma.
• The returned search results will contain:
  • Devices with a name neither containing NOR equal to "beer"
  AND
  • Devices with a name neither containing NOR equal to "cheese"

Search Exclusion on Multiple Properties

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application that do not contain the name "beer", the serial number "1234", and the region "US". Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=!beer&serialnumber=!1234&region=!us

Notes

• The "https://api.jetstreamrfid.com/3/devices" section of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The "name", "serial number", and "region" parameters are all properties of the Device resource. Not all properties of a resource are searchable. See the Parameters table for each endpoint to determine which properties are searchable.
• The "!" character is used to exclude results. It must precede the first value to be excluded, and you only need one "!" before all excluded values.
• The "&" character is used to separate multiple parameters. There should be no spaces preceding or following the ampersand.
• The returned search results will contain:
  • Devices with a name neither containing NOR equal to "beer"
  AND
  • Devices with a serial number neither containing NOR equal to "1234"
  AND
  • Devices with a region neither containing NOR equal to "us"

What if you wanted to find all devices in your Jetstream application that do not contain the names "beer" and "cheese", the serial numbers "1234" and "4321", and the regions "US" and "AP"? It’s possible and here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=!beer,cheese&serialnumber=!1234,4321&region=!us,ap

Notes

• The "!" character is used to exclude results. It must precede the first value to be excluded, and you only need one "!" before all excluded values.
• The "," character is used to separate multiple values. There should be no space following the comma.
• The returned search results will contain:
  • Devices with a name neither containing NOR equal to "beer"
  AND
  • Devices with a name neither containing NOR equal to "cheese"
  AND
  • Devices with a serial number neither containing NOR equal to "1234"
  AND
  • Devices with a serial number neither containing NOR equal to "4321"
  AND
  • Devices with a region neither containing NOR equal to "us"
  AND
  • Devices with a region neither containing NOR equal to "ap"

Sort 

Sort can be used on its own, separate from search, as follows:

Sort on One Property

In this example, we will be using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application and sort by the "name" property. Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?sort=name

Notes

• The "https://api.jetstreamrfid.com/3/devices" section of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The “name” value is a property of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
• The returned results will contain devices ordered by their "name" property, in ascending order.

Sort on Multiple Properties

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application and sort, first, by the "devicedefinition" property and, then, by the “region” property. Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?sort=devicedefinition,region

Notes

• The "https://api.jetstreamrfid.com/3/devices" section of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The "devicedefinition" and "region" values are properties of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
• The "," character is used to separate multiple values. There should be no space following the comma.
• The returned results will contain devices ordered by their "devicedefinition" property first, and then, by their "region" property within each "devicedefinition", in ascending order.

Sort Descending on One Property

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application and sort by the “name” property, in descending order. Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?sort=-name

Notes

• The "https://api.jetstreamrfid.com/3/devices" part of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The "-" character is used to sort the results in descending order – it must precede the value.
• The "name" value is a property of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
• The returned results will contain devices ordered by their "name" property, in descending order.

Sort Descending on Multiple Properties

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application and sort, first, by the "devicedefinition" property and, then, by the "region" property, in descending order. Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?sort=-devicedefinition,-region

Notes

• The "https://api.jetstreamrfid.com/3/devices" section of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The "-" character is used to sort the results in descending order – it must precede each value.
• The "devicedefinition" and "region" values are properties of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
• The "," character is used to separate multiple values. There should be no space following the comma.
• The returned results will contain devices ordered, first, by their "devicedefinition" property and, then, by their "region" property within each "devicedefinition", in descending order.

Search & Sort

Search and sort can be used together as follows:

In this example, we will be using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application containing the name "beer" and sort by the "region" property. Here’s how to do so:

https://api.jetstreamrfid.com/3/devices?name=beer&sort=region

Notes

• The "https://api.jetstreamrfid.com/3/devices" section of the URL indicates the Get All Devices endpoint.
• The "?" separator indicates the start of the query string used for searching.
• The "name" parameter is a property of the Device resource. Not all properties of a resource are searchable. See the Parameters table for each endpoint to determine which properties are searchable.
• The "&" character is used to separate multiple parameters. There should be no spaces preceding nor following the ampersand. In this case, it separates the search and sort parts of the query.
• The "region" value is a property of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
• The returned results will contain devices with a name containing AND equal to "beer", ordered by their “region” property, in ascending order.

The key is to combine the search and sort parts of the query via the "&" character. Above is only one possible combination of search and sort to create a query. Reference the separate search and sort possibilities and combine them to create even more ways to search and sort.

Version Changes

What's New?

• Data-Interchange Format
  • JSON is now the data-interchange format used by Jetstream, replacing XML.
• Searching and Sorting
  • Searching and sorting are available on the following Jetstream API endpoints that return large result sets:
    • Get All Device Definitions
    • Get All Devices
    • Get All Policies
• New Endpoints
  • Get a Device
  • Replace All Passes
  • Get a Device's Policy
  • Get a Policy

What's Been Replaced?

What's Been Deprecated

• DeviceFailureEvent
• DeviceRestoreEvent

Glossary

Agent 

A device’s component firmware that communicates with Jetstream.

Application 

An application created within Jetstream, representing a logical boundary containing devices and users. Security is setup and configured at the application level for users. The users within an application can only communicate and interact with the devices within that application.

This should not be confused with your in-house developed application that consumes Jetstream messages.

Command 

A request or query assigned to a Terso RFID device. A command is executed on a device. A command will be one of three types, described below, and will behave differently depending on whether the device is online or offline.

Command Id

A 36-character GUID tying the following pieces of a command request together: Command Response, CommandQueuedEvent, and CommandCompletionEvent. Each of these components will have the same value in their "CommandId" property. Depending on which command type is being handled in a command request, these three parts will be created at different times and may end up buried with many other responses and events.

Using their common "CommandId" property enables you to gather all three pieces to determine if execution of a command on a device was successful or not.

Command Response 

A reply received within the Response Body from a command request being executed. Depending on the command type that was executed, described below, results are returned in the Response Body or not.

Configuration 

A setup, change, or request performed on a Jetstream application. Configuration actions are performed for the maintenance and management of Jetstream resources (e.g., devices, device definitions, policies, events).

Device 

A Terso RFID device. Our intelligent devices come in the form factors of enclosures, mobile cases, kiosks, and hand-helds.

WebSockets capable devices are able to process eligible commands right away, providing near real-time interaction. Currently, devices that are WebSockets capable include enclosures with firmware v4+ and mobile cases. Devices that are not WebSockets capable will poll for and execute queueable commands at a set time interval. At the moment, devices that aren’t WebSockets capable include enclosures with firmware v3 and kiosks.

Device Definition 

A unique collection of settings establishing the identity of a specific Terso RFID device. The settings are a combination of identifiers (e.g., name, firmware version, configuration parameters) for the device and capabilities (e.g., restart, update firmware, scan for RFID tags) the device supports.

Device Specific Command

A command applicable to a specific Terso RFID device. This command is supported by some, but not all, Terso RFID devices. For example, the Unlock a Device’s Door command applies to enclosures with firmware version 4, but not to enclosures with firmware version 3, mobile cases, nor kiosks. See each of the device types pages for the device specific commands supported by each device type.

Event 

A message capturing information pertaining to the single occurrence of a process. An event pertains to a device process and/or a Jetstream process. The table below summarizes the available event types and the process they relate to.

Events provide a window into all that is occurring in your Jetstream application. Below is some, but not all of the questions events can answer:

• What RFID tags were added/removed from a device during the last door open/close?
• What RFID tags are currently in a device?
• What commands have been queued for a device to process?
• What commands have been completed on/processed by a device?
• What devices have been added to a Jetstream application?
• What devices have been removed from a Jetstream application?
• What devices have/don’t have internet connectivity?
• What devices have a low battery?
• What are the temperature readings of a device?

Exception List 

A listing of exceptions while executing a command on a device or any issues in queuing/dequeuing the command.

Immediate Results 

Results associated with the execution of a command on a device. These results are returned to the calling system immediately. In these circumstances, the calling system will receive a Command Response as well as a CommandCompletionEvent.

Offline 

A connection status of a device indicating that it is not connected to Jetstream. Either the device is not WebSockets enabled/capable or has lost power/internet connectivity.

Online 

A connection status of a device indicating that it is connected to Jetstream. The device is WebSockets enabled and/or has power and internet connectivity.

Output Parameter List 

A listing of key-value/parameter-value settings resulting from the execution of a command on a device.

Policy 

A unique collection of settings to manage a device’s configuration values (the configuration parameters are defined by the device’s definition). A policy may be added to a device to apply its configuration settings. Conversely, a policy may be removed from a device to revoke its configuration settings.

Published Results 

Results associated with the execution of a command on a device. These results are published to Get Events for retrieval. In these circumstances, the calling system will receive a Command Response but the results will only be made available in CommandCompletionEvent which, along with CommandQueuedEvent, can be retrieved via Get Events.

Region 

A geographic region where a device is being placed. This is used to create the most reliable and lowest latency connection to the device. Possible locations include the following:

• US (United States)
• EU (Europe)
• AP (Asia Pacific)
• USGOV (United States - to meet U.S. government compliance requirements)

Standard Command

A typical command that can be, but doesn’t have to be, supported by any Terso RFID device. This is a stock command that is well defined with variables required to support the command. See Devices Types Documentation for the standard commands supported by each device type.

Unique 

An indicator that the value of a property is distinct and there cannot be another instance of the property with the same value.

User 

A person using the Jetstream API. During user account sign up, a user is provided a unique access key and is associated to a Jetstream application. Multiple users may be associated to one Jetstream application. A user must use their access key to make Jetstream API requests and these requests pertain to the user’s Jetstream application.