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 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 contains detailed documentation of the various Jetstream API command and configuration endpoints, including descriptions, parameters, examples, and version changes.

The Event Types section contains descriptions, parameters, examples, and version changes for all events Jetstream may return in a Get Events call.

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.

Run in Postman

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, request 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

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.

A remotely deployed Terso RFID device initiates communications on its own as well as responds to communications from API requests.

Jetstream will, then, publish the event to the events queue of your Jetstream application. Your in-house developed application can, then, retrieve the queued events, via a Get Events API request. How your application uses the events is up to the business logic you’ve coded in. For example, the information extracted from a HeartbeatEvent event could be used to update when a device last communicated and, thus, could serve as an indication that the device has internet connectivity. This information would be useful on some sort of devices dashboard.

command

Your in-house application can communicate with a Terso RFID device via command API requests. Since Jetstream supports many different Terso RFID devices, each with its own unique capabilities, Device Definitions are used to define the commands and configuration values each device supports in Jetstream. For example, to query for a device’s current network configuration, a Get a Device's Configuration Parameters command API request can be made. When a command request is made, Jetstream determines if the device is online. If the device:

  • Is online, the command is executed immediately.
  • Is offline, the command is queued in Jetstream for the device to pick up and execute the next time it establishes communications or polls for queueable commands.

Once a command is executed, if the command:

  • Is not synchronous, results are published and can be viewed in a CommandCompletionEvent event, via Get Events. The CommandCompletionEvent event is published to the events queue of your Jetstream application after the command executes. If there:
    • Is no issue executing the command, the Output Parameter List will be populated with data, if applicable to the command.
    • Is an issue executing the command, exceptions will appear in the Exception List.

      The most common command exception is "Command Timed Out". If a command is not retrieved by a device within 24 hours (1,440 minutes), Jetstream will clear the command from the queue and return this exception in the CommandCompletionEvent.

In the end, your in-house application will work with a combination of Command Responses and CommandCompletionEvents to complete communications with a Terso RFID device.

command


Whereas command API requests are meant to communicate with your Terso RFID devices, configuration API requests are meant to communicate with your Jetstream application.

Configuration API requests allow you to manage and maintain the resources (e.g., devices, device definitions, policies, events) pertaining to your Jetstream application. Within your Jetstream application, you can Create a Device, Create a Policy, Add a Policy to a Device, Get All Devices, and more. Get Events, which has already been mentioned above, is also a configuration API request.

When making a configuration API request, results are returned immediately and can be viewed in the Response Body.

command

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.

VerbDescription
POSTCreate a new resource.
GETRead/retrieve a resource.
PUTUpdate/replace a resource.
DELETEDelete a resource.
PATCHDelete a resource.

Response

The Jetstream API returns data as JSON.

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

Status CodeDescription
200 OK

Successful GET, PUT, and POST requests pertaining to:

  • Reading/retrieving resources
  • Updating/replacing resources
  • Configuring resources (e.g., creating, modifying, or deleting device credentials, aliases)
  • Commanding resources (e.g., restart a device, lock a device, unlock a device)
201 Created

Successful POST requests pertaining to:

  • Creating new resources
  • Configuring resources (e.g., adding a policy to a device)
204 No Content

Successful DELETE requests pertaining to:

  • Deleting resources
  • Configuring resources (e.g., removing a policy from a device)

Note: No message body is returned.

400 Bad Request

Pertains to:

  • Requests with errors (e.g., malformed syntax, missing required parameters, invalid parameter values)
  • Requests failing due to conditions not being met
  • Requests failing due to an invalid URI

Note: See the error message(s) given in the response message body for more details.

401 Unauthorized

Pertains to:

  • Requests failing due to a missing or invalid access key
404 Not Found

Pertains to:

  • Requests failing due to the requested resource not existing or not being found
  • Requests failing due to the resource(s) relating to the requested resource not existing or not being found – see the error message(s) given in the response message body for more details
  • Requests failing due to an invalid URI
500 Internal Server ErrorSomething went wrong on our end – we do our best to avoid these situations. Try your request again later. If this error persists, please contact us.

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 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?

What’s been replaced?


What’s been deprecated?

  • Execute a Proprietary Command