IoT APIv1beta1

Download OpenAPI

Introduction

Scaleway IoT Hub is a PaaS enabling device-to-device and device-to-Scaleway communication, you can see it as a managed message broker.

Main features:

  • Pub/Sub architecture
  • MQTT protocol, with or without TLS, with or without WebSockets
  • Mutual authentication available on TLS connections
  • High Availability and Scalability
  • Routes to Scaleway's ecosystem for data ingestion
  • Multiple other IoT Networks such as SigFox or LoRa
  • Usage metrics

We have planned a lot of other exciting features, do not hesitate to reach out to us and say what you would like to see next!

Where to reach us ?

We are available on Scaleway Community Slack on the #iot-hub channel.

Current Technical Limitations

  • A single region is supported, your hub will be located in Paris, France (fr-par).

Online documentation

Please refer to our online documentation to get more information.

IoT Hubs

Managed message brokers

List hubs

GET
/iot/v1beta1/regions/{region}/hubs
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Query Parameters
page
number
Page number. The default value is 1.
page_size
number
Page size. The maximum value is 100. The default value is 20.
order_by
string
Ordering of requested hub. Possible values are name_asc, name_desc, status_asc, status_desc, product_plan_asc, product_plan_desc, created_at_asc, created_at_desc, updated_at_asc and updated_at_desc. The default value is name_asc.
organization_id
nullable string
Filter on the organization.
name
nullable string
Filter on the name.
200 Response
total_count
number
Total number of hubs.
hubs
array
A page of hubs.
id
string
Hub ID.
name
string
Hub name.
status
string
Current status of the Hub. Possible values are error, enabling, ready, disabling and disabled. The default value is error.
product_plan
string
Hub feature set. Possible values are plan_unknown, plan_shared, plan_dedicated and plan_ha. The default value is plan_unknown.
enabled
boolean
Whether the hub has been enabled.
device_count
number
Number of registered devices.
connected_device_count
number
Number of currently connected devices.
endpoint
string
Devices should be connected to this host, port may be 1883 (MQTT), 8883 (MQTT over TLS), 80 (MQTT over Websocket) or 443 (MQTT over Websocket over TLS).
events_enabled
boolean
Wether Hub events are enabled or not.
events_topic_prefix
string
Hub events topic prefix.
region
string
Region of the Hub.
created_at
string
Hub creation date.
updated_at
string
Hub last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "total_count": 42,
  "hubs": [
    {
      "id": "string",
      "name": "string",
      "status": "error",
      "product_plan": "plan_unknown",
      "enabled": "boolean",
      "device_count": 42,
      "connected_device_count": 42,
      "endpoint": "string",
      "events_enabled": "boolean",
      "events_topic_prefix": "string",
      "region": "string",
      "created_at": "string",
      "updated_at": "string",
      "organization_id": "string"
    }
  ]
}

Create a hub

POST
/iot/v1beta1/regions/{region}/hubs
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
name
required string
Hub name (up to 255 characters).
organization_id
required string
Organization owning the resource.
product_plan
required string
Hub feature set. Possible values are plan_unknown, plan_shared, plan_dedicated and plan_ha. The default value is plan_shared.
disable_events
nullable boolean
Disable Hub events (default false).
events_topic_prefix
nullable string
Hub events topic prefix (default '$SCW/events').
Request Example
{
  "name": "string",
  "organization_id": "string",
  "product_plan": "plan_shared",
  "disable_events": "boolean",
  "events_topic_prefix": "string"
}
200 Response
id
string
Hub ID.
name
string
Hub name.
status
string
Current status of the Hub. Possible values are error, enabling, ready, disabling and disabled. The default value is error.
product_plan
string
Hub feature set. Possible values are plan_unknown, plan_shared, plan_dedicated and plan_ha. The default value is plan_unknown.
enabled
boolean
Whether the hub has been enabled.
device_count
number
Number of registered devices.
connected_device_count
number
Number of currently connected devices.
endpoint
string
Devices should be connected to this host, port may be 1883 (MQTT), 8883 (MQTT over TLS), 80 (MQTT over Websocket) or 443 (MQTT over Websocket over TLS).
events_enabled
boolean
Wether Hub events are enabled or not.
events_topic_prefix
string
Hub events topic prefix.
region
string
Region of the Hub.
created_at
string
Hub creation date.
updated_at
string
Hub last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "product_plan": "plan_unknown",
  "enabled": "boolean",
  "device_count": 42,
  "connected_device_count": 42,
  "endpoint": "string",
  "events_enabled": "boolean",
  "events_topic_prefix": "string",
  "region": "string",
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Get a hub

GET
/iot/v1beta1/regions/{region}/hubs/{hub_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
hub_id
required string
Hub ID.
200 Response
id
string
Hub ID.
name
string
Hub name.
status
string
Current status of the Hub. Possible values are error, enabling, ready, disabling and disabled. The default value is error.
product_plan
string
Hub feature set. Possible values are plan_unknown, plan_shared, plan_dedicated and plan_ha. The default value is plan_unknown.
enabled
boolean
Whether the hub has been enabled.
device_count
number
Number of registered devices.
connected_device_count
number
Number of currently connected devices.
endpoint
string
Devices should be connected to this host, port may be 1883 (MQTT), 8883 (MQTT over TLS), 80 (MQTT over Websocket) or 443 (MQTT over Websocket over TLS).
events_enabled
boolean
Wether Hub events are enabled or not.
events_topic_prefix
string
Hub events topic prefix.
region
string
Region of the Hub.
created_at
string
Hub creation date.
updated_at
string
Hub last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "product_plan": "plan_unknown",
  "enabled": "boolean",
  "device_count": 42,
  "connected_device_count": 42,
  "endpoint": "string",
  "events_enabled": "boolean",
  "events_topic_prefix": "string",
  "region": "string",
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Update a hub

PATCH
/iot/v1beta1/regions/{region}/hubs/{hub_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
hub_id
required string
Hub ID.
Body
name
nullable string
Hub name (up to 255 characters).
product_plan
string
Hub feature set. Possible values are plan_unknown, plan_shared, plan_dedicated and plan_ha. The default value is plan_unknown.
disable_events
nullable boolean
Disable Hub events.
events_topic_prefix
nullable string
Hub events topic prefix.
Request Example
{
  "name": "string",
  "product_plan": "plan_unknown",
  "disable_events": "boolean",
  "events_topic_prefix": "string"
}
200 Response
id
string
Hub ID.
name
string
Hub name.
status
string
Current status of the Hub. Possible values are error, enabling, ready, disabling and disabled. The default value is error.
product_plan
string
Hub feature set. Possible values are plan_unknown, plan_shared, plan_dedicated and plan_ha. The default value is plan_unknown.
enabled
boolean
Whether the hub has been enabled.
device_count
number
Number of registered devices.
connected_device_count
number
Number of currently connected devices.
endpoint
string
Devices should be connected to this host, port may be 1883 (MQTT), 8883 (MQTT over TLS), 80 (MQTT over Websocket) or 443 (MQTT over Websocket over TLS).
events_enabled
boolean
Wether Hub events are enabled or not.
events_topic_prefix
string
Hub events topic prefix.
region
string
Region of the Hub.
created_at
string
Hub creation date.
updated_at
string
Hub last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "product_plan": "plan_unknown",
  "enabled": "boolean",
  "device_count": 42,
  "connected_device_count": 42,
  "endpoint": "string",
  "events_enabled": "boolean",
  "events_topic_prefix": "string",
  "region": "string",
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Delete a hub

DELETE
/iot/v1beta1/regions/{region}/hubs/{hub_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
hub_id
required string
Hub ID.
Body
delete_devices
nullable boolean
Force deletion of devices added to this hub instead of rejecting operation.
Request Example
{
  "delete_devices": "boolean"
}
204 Response
Empty response

Disable a hub

POST
/iot/v1beta1/regions/{region}/hubs/{hub_id}/disable
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
hub_id
required string
Hub ID.
200 Response
id
string
Hub ID.
name
string
Hub name.
status
string
Current status of the Hub. Possible values are error, enabling, ready, disabling and disabled. The default value is error.
product_plan
string
Hub feature set. Possible values are plan_unknown, plan_shared, plan_dedicated and plan_ha. The default value is plan_unknown.
enabled
boolean
Whether the hub has been enabled.
device_count
number
Number of registered devices.
connected_device_count
number
Number of currently connected devices.
endpoint
string
Devices should be connected to this host, port may be 1883 (MQTT), 8883 (MQTT over TLS), 80 (MQTT over Websocket) or 443 (MQTT over Websocket over TLS).
events_enabled
boolean
Wether Hub events are enabled or not.
events_topic_prefix
string
Hub events topic prefix.
region
string
Region of the Hub.
created_at
string
Hub creation date.
updated_at
string
Hub last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "product_plan": "plan_unknown",
  "enabled": "boolean",
  "device_count": 42,
  "connected_device_count": 42,
  "endpoint": "string",
  "events_enabled": "boolean",
  "events_topic_prefix": "string",
  "region": "string",
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Enable a hub

POST
/iot/v1beta1/regions/{region}/hubs/{hub_id}/enable
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
hub_id
required string
Hub ID.
200 Response
id
string
Hub ID.
name
string
Hub name.
status
string
Current status of the Hub. Possible values are error, enabling, ready, disabling and disabled. The default value is error.
product_plan
string
Hub feature set. Possible values are plan_unknown, plan_shared, plan_dedicated and plan_ha. The default value is plan_unknown.
enabled
boolean
Whether the hub has been enabled.
device_count
number
Number of registered devices.
connected_device_count
number
Number of currently connected devices.
endpoint
string
Devices should be connected to this host, port may be 1883 (MQTT), 8883 (MQTT over TLS), 80 (MQTT over Websocket) or 443 (MQTT over Websocket over TLS).
events_enabled
boolean
Wether Hub events are enabled or not.
events_topic_prefix
string
Hub events topic prefix.
region
string
Region of the Hub.
created_at
string
Hub creation date.
updated_at
string
Hub last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "product_plan": "plan_unknown",
  "enabled": "boolean",
  "device_count": 42,
  "connected_device_count": 42,
  "endpoint": "string",
  "events_enabled": "boolean",
  "events_topic_prefix": "string",
  "region": "string",
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Get a hub's metrics

GET
/iot/v1beta1/regions/{region}/hubs/{hub_id}/metrics
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
hub_id
required string
Hub ID.
Query Parameters
period
required string
Period over which the metrics span. Possible values are hour, day, week, month and year. The default value is hour.
200 Response
metrics
array
Metrics for a hub or a device, over the requested period.
name
string
Metric name.
values
array
Metric values over the selected period.
time
string
Timestamp for the value.
value
number
Numeric value.
Response Example
{
  "metrics": [
    {
      "name": "string",
      "values": [
        {
          "time": "string",
          "value": 42
        }
      ]
    }
  ]
}

IoT Devices

Devices allowed to connect to a Hub

List devices

GET
/iot/v1beta1/regions/{region}/devices
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Query Parameters
page
number
Page number. The default value is 1.
page_size
number
Page size. The maximum value is 100. The default value is 20.
order_by
string
Ordering of requested devices. Possible values are name_asc, name_desc, status_asc, status_desc, hub_id_asc, hub_id_desc, created_at_asc, created_at_desc, updated_at_asc, updated_at_desc, allow_insecure_asc and allow_insecure_desc. The default value is name_asc.
organization_id
nullable string
Filter on the organization.
name
nullable string
Filter on the name.
hub_id
nullable string
Filter on the hub.
enabled
deprecated boolean
Deprecated, ignored filter.
allow_insecure
nullable boolean
Filter on the allow_insecure flag.
is_connected
deprecated boolean
Deprecated, ignored filter.
200 Response
total_count
number
Total number of devices.
devices
array
A page of devices.
id
string
Device ID, also used as MQTT Client ID or Username.
name
string
Device name.
status
string
Device status. Possible values are error, enabled and disabled. The default value is error.
hub_id
string
Hub ID.
last_activity_at
string
Device last connection/activity date.
is_connected
boolean
Whether the device is connected to the Hub or not.
allow_insecure
boolean
Whether to allow device to connect without TLS mutual authentication.
allow_multiple_connections
boolean
Whether to allow multiple physical devices to connect with this device's credentials.
message_filters
object
Filter-sets to restrict the topics the device can publish/subscribe to.
publish
object
Filter-set to restrict topics the device can publish to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
subscribe
object
Filter-set to restrict topics the device can subscribe to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
created_at
string
Device add date.
updated_at
string
Device last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "total_count": 42,
  "devices": [
    {
      "id": "string",
      "name": "string",
      "status": "error",
      "hub_id": "string",
      "last_activity_at": "string",
      "is_connected": "boolean",
      "allow_insecure": "boolean",
      "allow_multiple_connections": "boolean",
      "message_filters": {
        "publish": {
          "policy": "unknown",
          "topics": [
            "string"
          ]
        },
        "subscribe": {
          "policy": "unknown",
          "topics": [
            "string"
          ]
        }
      },
      "created_at": "string",
      "updated_at": "string",
      "organization_id": "string"
    }
  ]
}

Add a device

POST
/iot/v1beta1/regions/{region}/devices
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
name
required string
Device name.
hub_id
required string
ID of the device's hub.
allow_insecure
boolean
Allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones.
allow_multiple_connections
boolean
Allow multiple physical devices to connect with this device's credentials.
message_filters
object
Filter-sets to authorize or deny the device to publish/subscribe to specific topics.
publish
object
Filter-set to restrict topics the device can publish to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
subscribe
object
Filter-set to restrict topics the device can subscribe to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
Request Example
{
  "name": "string",
  "hub_id": "string",
  "allow_insecure": "boolean",
  "allow_multiple_connections": "boolean",
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  }
}
200 Response
device
object
Created device information.
id
string
Device ID, also used as MQTT Client ID or Username.
name
string
Device name.
status
string
Device status. Possible values are error, enabled and disabled. The default value is error.
hub_id
string
Hub ID.
last_activity_at
string
Device last connection/activity date.
is_connected
boolean
Whether the device is connected to the Hub or not.
allow_insecure
boolean
Whether to allow device to connect without TLS mutual authentication.
allow_multiple_connections
boolean
Whether to allow multiple physical devices to connect with this device's credentials.
message_filters
object
Filter-sets to restrict the topics the device can publish/subscribe to.
publish
object
Filter-set to restrict topics the device can publish to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
subscribe
object
Filter-set to restrict topics the device can subscribe to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
created_at
string
Device add date.
updated_at
string
Device last modification date.
organization_id
string
Organization owning the resource.
crt
string
Device certificate.
key
string
Device certificate key.
Response Example
{
  "device": {
    "id": "string",
    "name": "string",
    "status": "error",
    "hub_id": "string",
    "last_activity_at": "string",
    "is_connected": "boolean",
    "allow_insecure": "boolean",
    "allow_multiple_connections": "boolean",
    "message_filters": {
      "publish": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      },
      "subscribe": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      }
    },
    "created_at": "string",
    "updated_at": "string",
    "organization_id": "string"
  },
  "crt": "string",
  "key": "string"
}

Get a device

GET
/iot/v1beta1/regions/{region}/devices/{device_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
device_id
required string
Device ID.
200 Response
id
string
Device ID, also used as MQTT Client ID or Username.
name
string
Device name.
status
string
Device status. Possible values are error, enabled and disabled. The default value is error.
hub_id
string
Hub ID.
last_activity_at
string
Device last connection/activity date.
is_connected
boolean
Whether the device is connected to the Hub or not.
allow_insecure
boolean
Whether to allow device to connect without TLS mutual authentication.
allow_multiple_connections
boolean
Whether to allow multiple physical devices to connect with this device's credentials.
message_filters
object
Filter-sets to restrict the topics the device can publish/subscribe to.
publish
object
Filter-set to restrict topics the device can publish to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
subscribe
object
Filter-set to restrict topics the device can subscribe to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
created_at
string
Device add date.
updated_at
string
Device last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "hub_id": "string",
  "last_activity_at": "string",
  "is_connected": "boolean",
  "allow_insecure": "boolean",
  "allow_multiple_connections": "boolean",
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Update a device

PATCH
/iot/v1beta1/regions/{region}/devices/{device_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
device_id
required string
Device ID.
Body
name
nullable string
Device name.
allow_insecure
nullable boolean
Allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones.
allow_multiple_connections
nullable boolean
Allow multiple physical devices to connect with this device's credentials.
message_filters
object
Filter-sets to restrict the topics the device can publish/subscribe to.
publish
object
Filter-set to restrict topics the device can publish to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
subscribe
object
Filter-set to restrict topics the device can subscribe to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
hub_id
nullable string
Change Hub for this device, additional fees may apply, see IoT Hub pricing.
Request Example
{
  "name": "string",
  "allow_insecure": "boolean",
  "allow_multiple_connections": "boolean",
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "hub_id": "string"
}
200 Response
id
string
Device ID, also used as MQTT Client ID or Username.
name
string
Device name.
status
string
Device status. Possible values are error, enabled and disabled. The default value is error.
hub_id
string
Hub ID.
last_activity_at
string
Device last connection/activity date.
is_connected
boolean
Whether the device is connected to the Hub or not.
allow_insecure
boolean
Whether to allow device to connect without TLS mutual authentication.
allow_multiple_connections
boolean
Whether to allow multiple physical devices to connect with this device's credentials.
message_filters
object
Filter-sets to restrict the topics the device can publish/subscribe to.
publish
object
Filter-set to restrict topics the device can publish to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
subscribe
object
Filter-set to restrict topics the device can subscribe to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
created_at
string
Device add date.
updated_at
string
Device last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "hub_id": "string",
  "last_activity_at": "string",
  "is_connected": "boolean",
  "allow_insecure": "boolean",
  "allow_multiple_connections": "boolean",
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Remove a device

DELETE
/iot/v1beta1/regions/{region}/devices/{device_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
device_id
required string
Device ID.
204 Response
Empty response

Disable a device

POST
/iot/v1beta1/regions/{region}/devices/{device_id}/disable
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
device_id
required string
Device ID.
200 Response
id
string
Device ID, also used as MQTT Client ID or Username.
name
string
Device name.
status
string
Device status. Possible values are error, enabled and disabled. The default value is error.
hub_id
string
Hub ID.
last_activity_at
string
Device last connection/activity date.
is_connected
boolean
Whether the device is connected to the Hub or not.
allow_insecure
boolean
Whether to allow device to connect without TLS mutual authentication.
allow_multiple_connections
boolean
Whether to allow multiple physical devices to connect with this device's credentials.
message_filters
object
Filter-sets to restrict the topics the device can publish/subscribe to.
publish
object
Filter-set to restrict topics the device can publish to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
subscribe
object
Filter-set to restrict topics the device can subscribe to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
created_at
string
Device add date.
updated_at
string
Device last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "hub_id": "string",
  "last_activity_at": "string",
  "is_connected": "boolean",
  "allow_insecure": "boolean",
  "allow_multiple_connections": "boolean",
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Enable a device

POST
/iot/v1beta1/regions/{region}/devices/{device_id}/enable
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
device_id
required string
Device ID.
200 Response
id
string
Device ID, also used as MQTT Client ID or Username.
name
string
Device name.
status
string
Device status. Possible values are error, enabled and disabled. The default value is error.
hub_id
string
Hub ID.
last_activity_at
string
Device last connection/activity date.
is_connected
boolean
Whether the device is connected to the Hub or not.
allow_insecure
boolean
Whether to allow device to connect without TLS mutual authentication.
allow_multiple_connections
boolean
Whether to allow multiple physical devices to connect with this device's credentials.
message_filters
object
Filter-sets to restrict the topics the device can publish/subscribe to.
publish
object
Filter-set to restrict topics the device can publish to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
subscribe
object
Filter-set to restrict topics the device can subscribe to.
policy
string
Possible values are unknown, accept and reject. The default value is unknown.
topics
nullable array
created_at
string
Device add date.
updated_at
string
Device last modification date.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "status": "error",
  "hub_id": "string",
  "last_activity_at": "string",
  "is_connected": "boolean",
  "allow_insecure": "boolean",
  "allow_multiple_connections": "boolean",
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "created_at": "string",
  "updated_at": "string",
  "organization_id": "string"
}

Get a device's metrics

GET
/iot/v1beta1/regions/{region}/devices/{device_id}/metrics
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
device_id
required string
Device ID.
Query Parameters
period
required string
Period over which the metrics span. Possible values are hour, day, week, month and year. The default value is hour.
200 Response
metrics
array
Metrics for a hub or a device, over the requested period.
name
string
Metric name.
values
array
Metric values over the selected period.
time
string
Timestamp for the value.
value
number
Numeric value.
Response Example
{
  "metrics": [
    {
      "name": "string",
      "values": [
        {
          "time": "string",
          "value": 42
        }
      ]
    }
  ]
}

IoT Routes

Managed routes

List routes

GET
/iot/v1beta1/regions/{region}/routes
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Query Parameters
page
number
Page number. The default value is 1.
page_size
number
Page size. The maximum value is 100. The default value is 20.
order_by
string
Ordering of requested routes. Possible values are name_asc, name_desc, hub_id_asc, hub_id_desc, type_asc, type_desc, created_at_asc and created_at_desc. The default value is name_asc.
organization_id
nullable string
Filter on the organization.
hub_id
nullable string
Filter on the hub.
name
nullable string
Filter on route's name.
200 Response
total_count
number
Total number of routes.
routes
array
A page of routes.
id
string
Route ID.
name
string
Route name.
organization_id
string
Organization owning the resource.
hub_id
string
ID of the route's hub.
topic
string
Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters.
type
string
Route type. Possible values are unknown, s3, database and rest. The default value is unknown.
created_at
string
Route creation date.
Response Example
{
  "total_count": 42,
  "routes": [
    {
      "id": "string",
      "name": "string",
      "organization_id": "string",
      "hub_id": "string",
      "topic": "string",
      "type": "unknown",
      "created_at": "string"
    }
  ]
}

Create a Database route

Create a route that will record subscribed MQTT messages into your database.

You need to manage the database by yourself.
POST
/iot/v1beta1/regions/{region}/routes/database
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
name
required string
Name of the route.
hub_id
required string
ID of the route's hub.
topic
required string
Topic the route subscribes to (wildcards allowed). It must be a valid MQTT topic and up to 65535 characters.
query
required string
SQL query to be executed ($TOPIC and $PAYLOAD variables are available, see documentation).
database
required object
Database settings.
host
required string
Database host.
port
required number
Database port.
dbname
required string
Database name.
username
required string
Database username. Make sure this account can execute the provided query.
password
required string
Database password.
Request Example
{
  "name": "string",
  "hub_id": "string",
  "topic": "string",
  "query": "string",
  "database": {
    "host": "string",
    "port": 42,
    "dbname": "string",
    "username": "string",
    "password": "string"
  }
}
200 Response
id
string
Route ID.
name
string
Route name.
organization_id
string
Organization owning the route.
hub_id
string
ID of the route's hub.
topic
string
Topic the route subscribes to (wildcards allowed). It must be a valid MQTT topic and up to 65535 characters.
created_at
string
Route creation date.
query
string
SQL query to be executed ($TOPIC and $PAYLOAD variables are available, see documentation).
database
object
Database settings.
host
required string
Database host.
port
required number
Database port.
dbname
required string
Database name.
username
required string
Database username. Make sure this account can execute the provided query.
password
required string
Database password.
Response Example
{
  "id": "string",
  "name": "string",
  "organization_id": "string",
  "hub_id": "string",
  "topic": "string",
  "created_at": "string",
  "query": "string",
  "database": {
    "host": "string",
    "port": 42,
    "dbname": "string",
    "username": "string",
    "password": "string"
  }
}

Get a Database route

GET
/iot/v1beta1/regions/{region}/routes/database/{route_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
route_id
required string
Route ID.
200 Response
id
string
Route ID.
name
string
Route name.
organization_id
string
Organization owning the route.
hub_id
string
ID of the route's hub.
topic
string
Topic the route subscribes to (wildcards allowed). It must be a valid MQTT topic and up to 65535 characters.
created_at
string
Route creation date.
query
string
SQL query to be executed ($TOPIC and $PAYLOAD variables are available, see documentation).
database
object
Database settings.
host
required string
Database host.
port
required number
Database port.
dbname
required string
Database name.
username
required string
Database username. Make sure this account can execute the provided query.
password
required string
Database password.
Response Example
{
  "id": "string",
  "name": "string",
  "organization_id": "string",
  "hub_id": "string",
  "topic": "string",
  "created_at": "string",
  "query": "string",
  "database": {
    "host": "string",
    "port": 42,
    "dbname": "string",
    "username": "string",
    "password": "string"
  }
}

Delete a Database route

DELETE
/iot/v1beta1/regions/{region}/routes/database/{route_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
route_id
required string
Route ID.
204 Response
Empty response

Create a Rest route

Create a route that will call a REST API on received subscribed MQTT messages.

POST
/iot/v1beta1/regions/{region}/routes/rest
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
name
required string
Name of the route.
hub_id
required string
ID of the route's hub.
topic
required string
Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters.
verb
string
HTTP Verb used to call REST URI. Possible values are get, post, put, patch and delete. The default value is get.
uri
string
URI of the REST endpoint.
headers
map
HTTP call extra headers.
<headerKey>
string
Request Example
{
  "name": "string",
  "hub_id": "string",
  "topic": "string",
  "verb": "get",
  "uri": "string",
  "headers": {
    "<headerKey>": "string"
  }
}
200 Response
id
string
Route ID.
name
string
Route name.
organization_id
string
Organization owning the route.
hub_id
string
ID of the route's hub.
topic
string
Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters.
created_at
string
Route creation date.
verb
string
HTTP Verb used to call REST URI. Possible values are get, post, put, patch and delete. The default value is get.
uri
string
URI of the REST endpoint.
headers
map
HTTP call extra headers.
<headerKey>
string
Response Example
{
  "id": "string",
  "name": "string",
  "organization_id": "string",
  "hub_id": "string",
  "topic": "string",
  "created_at": "string",
  "verb": "get",
  "uri": "string",
  "headers": {
    "<headerKey>": "string"
  }
}

Get a Rest route

GET
/iot/v1beta1/regions/{region}/routes/rest/{route_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
route_id
required string
Route ID.
200 Response
id
string
Route ID.
name
string
Route name.
organization_id
string
Organization owning the route.
hub_id
string
ID of the route's hub.
topic
string
Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters.
created_at
string
Route creation date.
verb
string
HTTP Verb used to call REST URI. Possible values are get, post, put, patch and delete. The default value is get.
uri
string
URI of the REST endpoint.
headers
map
HTTP call extra headers.
<headerKey>
string
Response Example
{
  "id": "string",
  "name": "string",
  "organization_id": "string",
  "hub_id": "string",
  "topic": "string",
  "created_at": "string",
  "verb": "get",
  "uri": "string",
  "headers": {
    "<headerKey>": "string"
  }
}

Delete a Rest route

DELETE
/iot/v1beta1/regions/{region}/routes/rest/{route_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
route_id
required string
Route ID.
204 Response
Empty response

Create an S3 route

Create a route that will put subscribed MQTT messages into an S3 bucket. You need to create the bucket yourself and grant us write access:

> s3cmd setacl s3://<my-bucket> --acl-grant=write:555c69c3-87d0-4bf8-80f1-99a2f757d031:555c69c3-87d0-4bf8-80f1-99a2f757d031
POST
/iot/v1beta1/regions/{region}/routes/s3
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
name
string
Name of the route.
hub_id
required string
ID of the route's hub.
topic
required string
Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters.
bucket_region
required string
Region of the S3 route's destination bucket (eg 'fr-par').
bucket_name
required string
Name of the S3 route's destination bucket.
object_prefix
string
Optional string to prefix object names with.
strategy
required string
How the S3 route's objects will be created: one per topic or one per message. Possible values are per_topic and per_message. The default value is per_topic.
Request Example
{
  "name": "string",
  "hub_id": "string",
  "topic": "string",
  "bucket_region": "string",
  "bucket_name": "string",
  "object_prefix": "string",
  "strategy": "per_topic"
}
200 Response
id
string
Route ID.
name
string
Route name.
organization_id
string
Organization owning the route.
hub_id
string
ID of the route's hub.
topic
string
Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters.
created_at
string
Route creation date.
bucket_region
string
Region of the S3 route's destination bucket (eg 'fr-par').
bucket_name
string
Name of the S3 route's destination bucket.
object_prefix
string
Optional string to prefix object names with.
strategy
string
How the S3 route's objects will be created: one per topic or one per message. Possible values are per_topic and per_message. The default value is per_topic.
Response Example
{
  "id": "string",
  "name": "string",
  "organization_id": "string",
  "hub_id": "string",
  "topic": "string",
  "created_at": "string",
  "bucket_region": "string",
  "bucket_name": "string",
  "object_prefix": "string",
  "strategy": "per_topic"
}

Get an S3 route

GET
/iot/v1beta1/regions/{region}/routes/s3/{route_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
route_id
required string
Route ID.
200 Response
id
string
Route ID.
name
string
Route name.
organization_id
string
Organization owning the route.
hub_id
string
ID of the route's hub.
topic
string
Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters.
created_at
string
Route creation date.
bucket_region
string
Region of the S3 route's destination bucket (eg 'fr-par').
bucket_name
string
Name of the S3 route's destination bucket.
object_prefix
string
Optional string to prefix object names with.
strategy
string
How the S3 route's objects will be created: one per topic or one per message. Possible values are per_topic and per_message. The default value is per_topic.
Response Example
{
  "id": "string",
  "name": "string",
  "organization_id": "string",
  "hub_id": "string",
  "topic": "string",
  "created_at": "string",
  "bucket_region": "string",
  "bucket_name": "string",
  "object_prefix": "string",
  "strategy": "per_topic"
}

Delete an S3 route

DELETE
/iot/v1beta1/regions/{region}/routes/s3/{route_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
route_id
required string
Route ID.
204 Response
Empty response

IoT Networks

Links to external IoT networks

List the Networks

GET
/iot/v1beta1/regions/{region}/networks
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Query Parameters
page
number
Page number. The default value is 1.
page_size
number
Page size. The maximum value is 100. The default value is 20.
order_by
string
Ordering of requested routes. Possible values are name_asc, name_desc, type_asc, type_desc, created_at_asc and created_at_desc. The default value is name_asc.
organization_id
nullable string
Filter on the organization.
name
nullable string
Filter on Network name.
hub_id
nullable string
Filter on the hub.
topic_prefix
nullable string
Filter on the topic prefix.
200 Response
total_count
number
Total number of Networks.
networks
array
A page of networks.
id
string
Network ID.
name
string
Network name.
type
string
Type of network to connect with. Possible values are unknown, sigfox and rest. The default value is unknown.
endpoint
string
Endpoint to use for interacting with the network.
hub_id
string
Hub ID to connect the Network to.
created_at
string
Network creation date.
topic_prefix
string
This prefix will be prepended to all topics for this Network.
region
string
Region of the Network.
organization_id
string
Organization owning the resource.
Response Example
{
  "total_count": 42,
  "networks": [
    {
      "id": "string",
      "name": "string",
      "type": "unknown",
      "endpoint": "string",
      "hub_id": "string",
      "created_at": "string",
      "topic_prefix": "string",
      "region": "string",
      "organization_id": "string"
    }
  ]
}

Create a new Network

POST
/iot/v1beta1/regions/{region}/networks
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
name
required string
Network name.
organization_id
deprecated string
Will always be assigned to the organization owning the IoT hub.
type
required string
Type of network to connect with. Possible values are unknown, sigfox and rest. The default value is unknown.
hub_id
required string
Hub ID to connect the Network to.
topic_prefix
required string
Topic prefix for the Network.
Request Example
{
  "name": "string",
  "organization_id": "string",
  "type": "unknown",
  "hub_id": "string",
  "topic_prefix": "string"
}
200 Response
network
object
Created network.
id
string
Network ID.
name
string
Network name.
type
string
Type of network to connect with. Possible values are unknown, sigfox and rest. The default value is unknown.
endpoint
string
Endpoint to use for interacting with the network.
hub_id
string
Hub ID to connect the Network to.
created_at
string
Network creation date.
topic_prefix
string
This prefix will be prepended to all topics for this Network.
region
string
Region of the Network.
organization_id
string
Organization owning the resource.
secret
string
Endpoint Key to keep secret. This cannot be retrieved later.
Response Example
{
  "network": {
    "id": "string",
    "name": "string",
    "type": "unknown",
    "endpoint": "string",
    "hub_id": "string",
    "created_at": "string",
    "topic_prefix": "string",
    "region": "string",
    "organization_id": "string"
  },
  "secret": "string"
}

Retrieve a specific Network

GET
/iot/v1beta1/regions/{region}/networks/{network_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
network_id
required string
Network ID.
200 Response
id
string
Network ID.
name
string
Network name.
type
string
Type of network to connect with. Possible values are unknown, sigfox and rest. The default value is unknown.
endpoint
string
Endpoint to use for interacting with the network.
hub_id
string
Hub ID to connect the Network to.
created_at
string
Network creation date.
topic_prefix
string
This prefix will be prepended to all topics for this Network.
region
string
Region of the Network.
organization_id
string
Organization owning the resource.
Response Example
{
  "id": "string",
  "name": "string",
  "type": "unknown",
  "endpoint": "string",
  "hub_id": "string",
  "created_at": "string",
  "topic_prefix": "string",
  "region": "string",
  "organization_id": "string"
}

Delete a Network

DELETE
/iot/v1beta1/regions/{region}/networks/{network_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
network_id
required string
Network ID.
204 Response
Empty response