flespi API basics

A comprehensive guide to the flespi API concepts.

Essentials

This article contains the description of flespi API usage. Key points:

  • There are 2 types of API: HTTP REST API and event based MQTT API

  • Flespi UI is built using API: everything you see in flespi UI can be embedded into your solution over API

  • API usage is authorized by tokens

Here is the short overview to quickly compare REST and MQTT APIs:


REST APIMQTT API
Recommended for
  • Singular operations:
    • Issue tokens

    • Provision a new device

    • Send command to a device

  • History data search
  • Find certain items
  •  Live new events consumption:
    • Device telemetry messages

    • Logs

    • Reports

    • Alerts

  • Build live dashboards
How to test

Interactive documentation


MQTT sandbox - MQTT Board

Hint in UI

-icon shows CURL to perform certain action

-icon opens MQTT sandbox with subscription for item’s data

AuthorizationFlespi Token in Authorization HTTP headerFlespi token in MQTT session username or password
Usage logsPlatform logsMQTT Sessions and Logs


REST API

HTTP REST API call consists of: method, headers, URL (with optional query variables) and body.

Header is used to authorize the request like

Authorization: FlespiToken XXXXXXXXX

According to the concepts of REST API, method is used for:

  • GET - receive information - list items, devices, messages, logs, etc. - this is always safe to call as it will not update anything

  • POST - create new item, register message, create a link and so on - any method that creates something

  • DELETE - delete item, delete telemetry, delete link, delete setting value and so on - the most dangerous method

  • PUT - modify existing item, update some fields and do on (PATCH - partly modify only specified fields, usually is used to update only part of configuration

Body is always in JSON format, exact structure and schema varies for each request and specified in the documentation. In GET methods body is empty and request parameters are passed as JSON object within data URL query variable, e.g. ?data={"parameter":"value"}.

URL - consists of:

  • path - hierarchical specification of the request that may include highly customizable REST selectors of the target items

  • fields list to limit the amount of the info of each item be returned in the response

  • pagination options to reduce the number of items 

REST selectors

REST selectors are used to specify the items to apply REST API call to and located in the path part of URL.

There are several ways to select items using REST selectors. Following examples are based on GET /gw/devices/{selectors} request to show the different options to filter devices list:

To select entities by multiple selectors simultaneously specify them as a CSV list: selector1,selector2.
To select entities that satisfy any of selectors combine them inside expression: {selector1 || selector2}

Use-case: select devices thatSelector value
belong to 2 different subaccounts{cid=123 || cid=456}
have can.vehicle.mileage parameter in telemetry{exists("telemetry.can.vehicle.mileage")}
have item-fields plugin field driver.name starts from "Andrew" substringplugins.fields.driver.name=Andrew*
has fleet_id with value 10 in its metadata propertymetadata.fleet_id=10
belong to a group with ID 1234groups.id=1234
device with specific IMEI
configuration.ident="123456789012345"
all Teltonika devicesprotocol_name="teltonika"
all devices of specified type Teltonika FMC640device_type_name="fmc640"
all Concox devices in group with ID 1234groups.id=1234,protocol_name="concox"
all Queclink GV500 devices with engine.ignition.status ONdevice_type_name="gv500",
telemetry.engine.ignition.status=true
not delivered any data to flespi for more than 24 hours{last_active < (now() - 86400)}
located within 100 km from point with latitude 54.72 and longitude 25.26{distance(telemetry.position.latitude, telemetry.position.longitude, 54.72, 25.26) < 100}

The best way to test your selectors is to use corresponding GET method for a call. When you execute API call using GET method you just listing items that available to you filtering them according to specified REST selectors.
For example call to GET /gw/devices/{last_active+86400<now()}?fields=id,name,last_active will return to you JSON array with all devices available to you that didn't connected to the platform more then 24 hours and each device represented as JSON object with parameters: id, name and last_active.

Fields and Pagination

Fields query variable is used to specify the exact number of fields of the items to be returned in response. If the item to be returned has non-plain structure, it is possible to specify comma separated path entries in the fields. E.g. to fetch devices list with ident and phone fields from configuration object and id field this request can be used.

Pagination query variables limit and offset can be used to fetch a limited number of items starting from a specific position. Offset is 0-based, so if you have 20 devices and you want to get them in 2 requests by chunks of 10 items then you should perform the request like

GET /gw/devices/all?limit=10&offset=0

GET /gw/devices/all?limit=10&offset=10

The response would be like:

{

    "result": [{},{},...],

    "pagination": {"limit": X, "offset": Y, "count": Z}

}

Where count is the total amount of items.

Note: Pagination and fields can not be used when requesting device messages and calculated intervals from flespi. For these methods you control number of returned items using call parameters inside data field (fields, max_count, etc).

MQTT API

MQTT protocol is designed for secure and stable telemetry transport. In flespi it might be efficiently utilized to consume live events like device messages, calculated intervals or logs. Code snippets on different programming languages can be found on flespi Github page.

MQTT broker specification

Connection configuration
Hostmqtt.flespi.io
PortMQTT over TCP: 8883 (SSL) or 1883 (non-SSL)
MQTT over WebSockets: 443 (SSL) or 80 (non-SSL)
MQTT version3.1, 3.1.1, 5.0
QoS supportedQoS 0, QoS 1
Authorizationflespi token as username or password
or
username=token ID, password=at least 16 first bytes of the token key


MQTT concepts:

  • client id should be unique within your account space
  • subscription topics may have wildcard masks: + for one level, # for rest till the end
  • non-clean sessions store undelivered messages and deliver it upon session reconnect
  • you can't publish to topic that starts from flespi/ - it is reserved for MQTT API
  • message published with retained flag is stored in broker and delivered upon subscription

Standard flespi topics

All the events published via flespi MQTT API are covered by MQTT Topics Directory tool and listed here.

Topic filtering

Subscription topic may contain special prefix that enables server side message filtering. It allows to reduce the number of messages received by the MQTT client. The common format of the topic is:

$filter/<filter-specification>/original-topic

Messages can be filtered by:

  • subaccount ID. E.g. to get messages published by devices that belong to subaccount with ID=123 the subscription topic is: $filter/cid=123/flespi/message/gw/devices/+
  • publication time. E.g. to receive only messages published after 11/14/2023 22:13:20 GMT subscription topic is $filter/modified_since=1700000000/flespi/message/gw/devices/+
  • payload. When you filter by payload, the filter is executed as expression and must be url-encoded. E.g. if you subscribe for battery.voltage telemetry and want to receive only messages when voltage is higher than 14 volts, then subscription topic is $filter/payload=tonumber%28payload%29%3E14/flespi/state/gw/devices/+/telemetry/battery.voltage . Here the payload is number, filter value is tonumber(payload)>14
  • complex message object expression. Message filter can be filtered by expression that may refer to:
    • topic - a topic string
    • topics - an array with topic words splited by '/'
    • cid - publisher id
    • timestamp - message timestamp
    • user_properties - an object with list of user properties
    • payload - a string with message payload

e.g. we have following topics: temperature/kitchen, temperature/bedroom, temperature/hall. Message payload is a temperature. So we want to receive temperature from kitchen and hall if it is below 20 degrees.

Message filter is: (topics[1]=="kitchen"||topics[1]=="hall")&&tonumber(payload)<20
Subscription with encoded filter is: $filter/message=(topics%5B1%5D%3D%3D%22kitchen%22%7C%7Ctopics%5B1%5D%3D%3D%22hall%22)%26%26tonumber(%22payload%22)%3C20/temperature/+

MQTT over REST

Publish to topic flespi/rest/{method}/{api-uri} to perform REST API call to the flespi platform. {method} should be lowercase and valid for the specified {api-uri}. Optional data parameter may be passed as MQTT message payload. MQTT v5.0 accepts "response topic" parameter with the indication of the topic to which to publish a response to API call. Otherwise, the response is published to the same topic. 

Additional user property "response_cid" allows redirecting the response to another subaccount. This is a special feature helpful when you want to perform an API call on the top-level (from the master account) and redirect its result from the flespi broker directly to one of the subaccounts.       

One more feature is the "response_chunked" user property. If it's "true", the response will be chunked in multiple MQTT messages. A message with the specified "http_code" user property is the indication of the last chunk (message).        

Learn more in the corresponding blog article.

Other options

  • Consume messages in various cloud IoT and telematics platforms in PUSH mode using Streams

  • Set up automation based on events that adopt some conditions using Webhooks

  • Export any REST API call result (all or specific devices, streams, channels, etc) into CSV using API Playground

  • Export Logs or Messages to CSV

Code examples

Our team created few open source scripts and integrations you may review and clone for your needs. Most of them are located in our repository on GitHub:

  • TrackIt - A GPS tracking application based on flespi.io and built with Quasar and Leaflet.js. Shows devices on the map and their telemetry messages. Includes a track player.

  • flespi-io-js - an isomorphic open-source library based on Axios and MQTT.js for easier access and communication with the flespi.io resource.

  • mqtt-telemetry-dashboard - example of using mqtt to receive and display telemetry data from devices with mapview and flespi login widgets.

  • http-stream-receiver - scripts in different programming languages (PHP, PHP+MySQL, Python, Node.js) to deploy on your server to receive the telemetry data from the flespi HTTP stream.

  • flespi_pipeline - Python solution for GDPR compliance that gets messages from a flespi channel via MQTT, applies Private Data Switch algorithm, and publishes to a topic.

  • flespi_receiver - Python module that consumes and custom processes messages from a flespi channel and sends them over MQTT to AWS and HTTP POST handlers.

  • mqtt-message-handler - Python script to aggregate messages coming from the flespi channel into a MySQL database using the gmqtt library.

  • devices-creation-tool - the wizard-like tool to create multiple devices of the same device type in your flespi.io account. Also generates a cURL to paste into the command line.

  • message-converter - node.js and python script to convert device messages to JSON, KML, GPX, GEOJSON, CSV formats.

  • mqtt-client - generic MQTT client usage samples in python, node.js, lua, javascript.

  • snapshots-downloader - python script to download device messages snapshots locally.

  • snapshots-uploader - python script to republish into device messages from locally downloaded snapshot.

  • re-register_messages - python script that may be used to re-register device messages to recalculate plugins for the existing messages or re-send messages via stream.

  • ESP32/ESP8266 channel sender - simple example of how to send data from ESP32/ESP8266 boards to the flespi channel via http/https (with root CA/fingerprint).

  • msg-webhook-plugin-listener - PHP and Node.js webhook plugin listeners that can enhance device message with extra information from your data.

What's next?

The best way to explore all flespi capabilities is to watch detailed videos from our conference. Invest your time into watching them to save much more time and money later, when you will implement your project:


See also
Apply webhooks to events from calculators to invoke your lambda upon an aggregated event happened to the device
A comprehensive overview of video telematics functionality integration into your application with flespi.