Jetstream API
General

FAQ

16min

What is Jetstream?

Jetstream is Terso’s Device Management API. It allows you to easily control and configure Terso devices all over the world and easily bring data from those devices into your applications.

How do I get started with Jetstream?

Contact us to get started! A member of our team will reach out to help you get started with everything you need to begin integration. For more information, check out our Getting Started article.

Can I manage my own users in my Jetstream application?

No, but additional users can be added any time by the Terso support team. When a new user is added, they will receive an email with login details for jetstreamrfid.com. Each user will get their own User Access Key and queue, giving them their own copies of your application’s events.

Is Jetstream a push or pull system?

Jetstream uses event queues from which you pull events into your system. You can retrieve events (FIFO) with a Get Events call in batches from 1-512 events at a time, though the default is 100. After successful processing in your application, send a Device Types call with the Batch Id to delete those events from the queue, and continue this process until the queue is empty, or at regularly scheduled intervals.

How long are events stored in my Jetstream queue?

Events stay in your Jetstream queue for 14 days before they are auto-cleared. However, once you have pulled an event in a Get Events call, the removal will occur in 4 days.

Can I choose which events I want to receive?

Yes, you can filter your Get Events call to only include/exclude events based on any parameter (event type, device, event time, etc.). See the "Search" portion of the API Basicspage for more information. You can also edit the configuration parameters on your devices to send fewer events, or send them based on different triggers, via policies.

How is API access authenticated?

Every request must include your unique User Access Key (a 36-character ID) in the header. This key is auto-generated for you. You can reset or delete your user access key by contacting the Terso Support team.

How quickly can I get the data from the devices into my application?

If the device is online, the transfer of the data from the device to Jetstream happens immediately. Depending on where you and the device are geographically, this data takes between 1-6 seconds (faster in North America, slower in Asia Pacific) to travel from the device to your Jetstream queue. Once it is in your Jetstream queue, you can pull the data in the form of events as frequently as desired for your use case.

Do you have an on-premise/hosted version?

Yes, we call this Jetstream Ground. It is a packaged VM running a complete copy of the Jetstream API that can then be installed anywhere. It also comes with our Jetstream management tool, Device Console, which allows you to manage your on-premise Jetstream users. Please note that Jetstream Ground has a much more expensive licensing structure, requires you to provide IT support and maintenance, and limits the level of real-time, proactive support Terso can offer. For more information on Jetstream Ground, contact Terso Solutions.

What does Jetstream cost?

Access to Jetstreamrfid.com, Unlimited API Calls, and Unlimited Jetstream Users are all included with the monthly data services fee for each Terso RFID Device, which varies by device. Our SDK (software development kit) is available on Github, and our API Documentation is accessible from jetstreamrfid.com and Jetstream Documentation.

How reliable is Jetstream?

We guarantee >99.9% uptime. Jetstream is hosted redundantly across AWS data centers in multiple geographic regions of the US and around the world. Every component of Jetstream can run autonomously if a failure occurs in another component. Data backups are performed hourly.

We share the status of Jetstream and notify of any planned or unplanned outages via status.tersosolutions.com. Finally, in the case of any disruption between a device and Jetstream, devices can locally store up to 30 days of events, to ensure no data loss.

How many devices can Jetstream support?

As many as you need! We have customers with thousands of devices all over the world and can readily support tens of thousands more.

How many API calls can Jetstream support?

Jetstream is able to support up to 60 API calls per minute, per application. If your application has more extreme needs than this, please contact us, and we will work with you on a solution.

How do you protect confidential data (such as PHI)?

Jetstream is designed to not transfer any patient or confidential data. Jetstream refers to data objects simply by ID or Jetstream Name, which your application can then tie to the business data safely within your own systems. All data from the device firmware through Jetstream to your application is encrypted in motion using at least TLSv1.2.

What does the integration process look like?

When you embark on a Jetstream integration, your development team will each be granted a login to jetstreamrfid.com and access keys for development application in Jetstream. We recommend the short-term lease of the devices you intend to integrate for your development teams hands-on use. After the delivery of the development devices, Terso will lead a 1-day design workshop on-site or remotely with your development team, answer questions throughout the implementation, and conduct a readiness assessment on the integration you develop. Integrations typically take between 3-6 months from initial meeting to production readiness. This time varies widely depending on a variety of factors including: the scope of the functionality being integrated, the number of dedicated developers, and their level of experience with API integration into your system.

Can I buy a Terso RFID device and not have it go through Jetstream?

No, our hardware and firmware are built to work with Jetstream to provide the most flexible, cohesive, and reliable RFID solution available. Every device sends similarly formatted events, and responds to similar commands, vastly reducing the complexity of managing a wide variety of devices. Jetstream as the relay between the devices and your systems also grants Terso the ability to offer a wide variety of support services and software to ensure the success of your RFID deployment.

Can I update firmware or change settings remotely?

Yes, while every device ships out the latest firmware and our recommended settings, practically every aspect of a Terso device can be configured remotely in seconds via the API, or with the assistance of our Technical Support team.

What data format does Jetstream use?

Messages are returned in JSON format. See the jetstreamrfid.com API documentation for examples.

My device is online but my command is not returning an immediate response. What does this mean?

Some commands take a long time to execute. To maintain the responsive nature of Jetstream not all commands will return results immediately.

For example, the Get All RFID Tags command may take more than a minute before the data is returned, since the device must do several deep scans to gather the RFID tag list. In this case, the command will be executed, but the results will not be returned to the caller in the response body; they will be published to Get Events as if the device were offline in the form of a CommandCompletionEvent.

If your device is offline, commands will be queued awaiting device retrieval for up to 24 hours. If the device does not come online within 24 hours, the queued command will be cleared and a "Command Timed Out" exception will be returned in the CommandCompletionEvent.

How many commands can I send to a device simultaneously?

There is no exact limit; the device is perfectly capable of queuing commands and executing them in the order they were received, but we recommend sending one command at a time, waiting for the command completion, then sending the next command. This is particularly true for commands that take longer to execute, such as Restart a Device.

I accidentally deleted an event without processing it. Is there a way to get it back?

We recommend when designing your event retrieval process that you wait to delete events until you have successfully processed or saved a copy of the events. If even after these precautions, events were not processed, or processed incompletely, our Terso Support team can retrieve the details of these events and share this information with you manually. Events cannot be re-created into your event queue.

Do I have to manage my device's policies through the API?

While we recommend integrating policy management into your application for maximum control and customizability, Terso Support can assist you with creating, editing, and applying policies to your devices as part of our standard service offering.

How do I know my device's serial number or device definition?

Each device is shipped with a label which includes the devices unique serial number, it's model type, and the FW version it shipped with. This info can also be provided to you electronically at time of shipment by your Terso Account Manager.