Jetstream API
General

FAQ

15min
what is jetstream? jetstream is terso’s device management api it allows you to easily control and configure terso devices https //www tersosolutions com/search all sensors/ all over the world and easily bring data from those devices into your applications how do i get started with jetstream? contact us https //www tersosolutions com/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 docid\ bbifqiuixnd5iafmrebbi 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 http //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 docid\ exupifhp3manjooqyjsiz all in batches from 1 512 events at a time, though the default is 100 after successful processing in your application, send a delete events docid\ iw1owil7sel8rw3kseuhf 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 basics docid\ jp52npktg jscledbma4p page 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 https //www tersosolutions com/support/ 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 https //www tersosolutions com/contact us/ what does jetstream cost? access to jetstreamrfid com http //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 https //github com/tersosolutions , and our api documentation is accessible from jetstreamrfid com http //jetstreamrfid com/ and jetstream api docid\ ib9yl2j4 h0 ka3oqeamm 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 http //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 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 http //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 https //www tersosolutions com/contact us/ what data format does jetstream use? messages are returned in json format see the openapi documentation for jetstream docid 3iuriinzplfzdui4xgjcu page 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 docid 7onvtntdtfl9ptdal2nvo 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 docid\ exupifhp3manjooqyjsiz as if the device were offline in the form of a commandcompletionevent docid\ sj1tshbqvf4fri6az1ywg 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 docid\ ww54y7kiqnfvyk8zyqakv 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 https //www tersosolutions com/contact us/ 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 https //www tersosolutions com/contact us/ 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, its 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 customer success manager