IoT APIv1

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!

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).

Please refer to our online documentation to get more information.

Managed message brokers

List hubs

GET
/iot/v1/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.

project_id
nullable string
Filter on project.

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.
Response Example
POST
/iot/v1/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).

project_id
required string
Organization/project 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.

events_topic_prefix
nullable string
Hub events topic prefix (default '$SCW/events').

twins_graphite_config
object
BETA - not implemented yet. Only one of twins_graphite_config may be set.
Request Example
200 Response

id
string
Hub ID.

name
string
Hub name.

status
string
Current status of the Hub. Possible values are unknown, error, enabling, ready, disabling and disabled. The default value is unknown.

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).

disable_events
boolean
Disable Hub events.

events_topic_prefix
string
Hub events topic prefix.

region
string
Region of the Hub.

created_at
string
Hub creation date (RFC 3339 format).

updated_at
string
Hub last modification date (RFC 3339 format).

project_id
string
Project owning the resource.

organization_id
string
Organization owning the resource.

enable_device_auto_provisioning
boolean
When an unknown device connects to your hub using a valid certificate chain, it will be automatically provisioned inside your hub. The hub uses the common name of the device certifcate to find out if a device with the same name already exists. This setting can only be enabled on a hub with a custom certificate authority.

has_custom_ca
boolean
After creating a hub, this flag is set to False as the hub certificates are managed by Scaleway. Once a custom certificate authority is installed, this flag will be set to true.

twins_graphite_config
object
BETA - not implemented yet. Only one of twins_graphite_config may be set.
Response Example
GET
/iot/v1/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 unknown, error, enabling, ready, disabling and disabled. The default value is unknown.

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).

disable_events
boolean
Disable Hub events.

events_topic_prefix
string
Hub events topic prefix.

region
string
Region of the Hub.

created_at
string
Hub creation date (RFC 3339 format).

updated_at
string
Hub last modification date (RFC 3339 format).

project_id
string
Project owning the resource.

organization_id
string
Organization owning the resource.

enable_device_auto_provisioning
boolean
When an unknown device connects to your hub using a valid certificate chain, it will be automatically provisioned inside your hub. The hub uses the common name of the device certifcate to find out if a device with the same name already exists. This setting can only be enabled on a hub with a custom certificate authority.

has_custom_ca
boolean
After creating a hub, this flag is set to False as the hub certificates are managed by Scaleway. Once a custom certificate authority is installed, this flag will be set to true.

twins_graphite_config
object
BETA - not implemented yet. Only one of twins_graphite_config may be set.
Response Example
PATCH
/iot/v1/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.

enable_device_auto_provisioning
nullable boolean
Enable device auto provisioning.

twins_graphite_config
object
BETA - not implemented yet. Only one of twins_graphite_config may be set.
Request Example
200 Response

id
string
Hub ID.

name
string
Hub name.

status
string
Current status of the Hub. Possible values are unknown, error, enabling, ready, disabling and disabled. The default value is unknown.

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).

disable_events
boolean
Disable Hub events.

events_topic_prefix
string
Hub events topic prefix.

region
string
Region of the Hub.

created_at
string
Hub creation date (RFC 3339 format).

updated_at
string
Hub last modification date (RFC 3339 format).

project_id
string
Project owning the resource.

organization_id
string
Organization owning the resource.

enable_device_auto_provisioning
boolean
When an unknown device connects to your hub using a valid certificate chain, it will be automatically provisioned inside your hub. The hub uses the common name of the device certifcate to find out if a device with the same name already exists. This setting can only be enabled on a hub with a custom certificate authority.

has_custom_ca
boolean
After creating a hub, this flag is set to False as the hub certificates are managed by Scaleway. Once a custom certificate authority is installed, this flag will be set to true.

twins_graphite_config
object
BETA - not implemented yet. Only one of twins_graphite_config may be set.
Response Example
DELETE
/iot/v1/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.
Query Parameters

delete_devices
nullable boolean
Force deletion of devices added to this hub instead of rejecting operation.
204 Response

Empty response
GET
/iot/v1/regions/{region}/hubs/{hub_id}/ca
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

hub_id
required string
200 Response

ca_cert_pem
string
Response Example
POST
/iot/v1/regions/{region}/hubs/{hub_id}/ca
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

hub_id
required string
Hub ID.
Body

ca_cert_pem
required string
The CA's PEM-encoded certificate.

challenge_cert_pem
required string
The challenge is a PEM-encoded certificate to prove the possession of the CA. It must be signed by the CA, and have a Common Name equal to the Hub ID.
Request Example
200 Response

id
string
Hub ID.

name
string
Hub name.

status
string
Current status of the Hub. Possible values are unknown, error, enabling, ready, disabling and disabled. The default value is unknown.

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).

disable_events
boolean
Disable Hub events.

events_topic_prefix
string
Hub events topic prefix.

region
string
Region of the Hub.

created_at
string
Hub creation date (RFC 3339 format).

updated_at
string
Hub last modification date (RFC 3339 format).

project_id
string
Project owning the resource.

organization_id
string
Organization owning the resource.

enable_device_auto_provisioning
boolean
When an unknown device connects to your hub using a valid certificate chain, it will be automatically provisioned inside your hub. The hub uses the common name of the device certifcate to find out if a device with the same name already exists. This setting can only be enabled on a hub with a custom certificate authority.

has_custom_ca
boolean
After creating a hub, this flag is set to False as the hub certificates are managed by Scaleway. Once a custom certificate authority is installed, this flag will be set to true.

twins_graphite_config
object
BETA - not implemented yet. Only one of twins_graphite_config may be set.
Response Example
POST
/iot/v1/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.
Body

Request Example
200 Response

id
string
Hub ID.

name
string
Hub name.

status
string
Current status of the Hub. Possible values are unknown, error, enabling, ready, disabling and disabled. The default value is unknown.

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).

disable_events
boolean
Disable Hub events.

events_topic_prefix
string
Hub events topic prefix.

region
string
Region of the Hub.

created_at
string
Hub creation date (RFC 3339 format).

updated_at
string
Hub last modification date (RFC 3339 format).

project_id
string
Project owning the resource.

organization_id
string
Organization owning the resource.

enable_device_auto_provisioning
boolean
When an unknown device connects to your hub using a valid certificate chain, it will be automatically provisioned inside your hub. The hub uses the common name of the device certifcate to find out if a device with the same name already exists. This setting can only be enabled on a hub with a custom certificate authority.

has_custom_ca
boolean
After creating a hub, this flag is set to False as the hub certificates are managed by Scaleway. Once a custom certificate authority is installed, this flag will be set to true.

twins_graphite_config
object
BETA - not implemented yet. Only one of twins_graphite_config may be set.
Response Example
POST
/iot/v1/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.
Body

Request Example
200 Response

id
string
Hub ID.

name
string
Hub name.

status
string
Current status of the Hub. Possible values are unknown, error, enabling, ready, disabling and disabled. The default value is unknown.

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).

disable_events
boolean
Disable Hub events.

events_topic_prefix
string
Hub events topic prefix.

region
string
Region of the Hub.

created_at
string
Hub creation date (RFC 3339 format).

updated_at
string
Hub last modification date (RFC 3339 format).

project_id
string
Project owning the resource.

organization_id
string
Organization owning the resource.

enable_device_auto_provisioning
boolean
When an unknown device connects to your hub using a valid certificate chain, it will be automatically provisioned inside your hub. The hub uses the common name of the device certifcate to find out if a device with the same name already exists. This setting can only be enabled on a hub with a custom certificate authority.

has_custom_ca
boolean
After creating a hub, this flag is set to False as the hub certificates are managed by Scaleway. Once a custom certificate authority is installed, this flag will be set to true.

twins_graphite_config
object
BETA - not implemented yet. Only one of twins_graphite_config may be set.
Response Example
GET
/iot/v1/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

start_date
required string
Start date used to compute the best scale for the returned metrics (RFC 3339 format).
200 Response

metrics
array
Metrics for a hub over the requested period.
Response Example

Devices allowed to connect to a Hub

GET
/iot/v1/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.

name
nullable string
Filter on the name.

hub_id
nullable string
Filter on the hub.

allow_insecure
nullable boolean
Filter on the allow_insecure flag.

status
string
Device status (enabled, disabled, etc.). Possible values are unknown, error, enabled and disabled. The default value is unknown.
200 Response

total_count
number
Total number of devices.

devices
array
A page of devices.
Response Example
POST
/iot/v1/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.

description
nullable string
Device description.
Request Example
200 Response

device
object
Created device information.

certificate
object
Device certificate.
Response Example
GET
/iot/v1/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.

description
string
Device description.

status
string
Device status. Possible values are unknown, error, enabled and disabled. The default value is unknown.

hub_id
string
Hub ID.

last_activity_at
string
Device last connection/activity date (RFC 3339 format).

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.

has_custom_certificate
boolean
Assigning a custom certificate allows a device to authenticate using that specific certificate without checking the hub's CA certificate.

created_at
string
Device add date (RFC 3339 format).

updated_at
string
Device last modification date (RFC 3339 format).
Response Example
PATCH
/iot/v1/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

description
nullable string
Device description.

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.

hub_id
nullable string
Change Hub for this device, additional fees may apply, see IoT Hub pricing.
Request Example
200 Response

id
string
Device ID, also used as MQTT Client ID or Username.

name
string
Device name.

description
string
Device description.

status
string
Device status. Possible values are unknown, error, enabled and disabled. The default value is unknown.

hub_id
string
Hub ID.

last_activity_at
string
Device last connection/activity date (RFC 3339 format).

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.

has_custom_certificate
boolean
Assigning a custom certificate allows a device to authenticate using that specific certificate without checking the hub's CA certificate.

created_at
string
Device add date (RFC 3339 format).

updated_at
string
Device last modification date (RFC 3339 format).
Response Example
DELETE
/iot/v1/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
GET
/iot/v1/regions/{region}/devices/{device_id}/certificate
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

device_id
required string
Device ID.
200 Response

device
object
Created device information.

certificate_pem
string
Device certificate.
Response Example
PUT
/iot/v1/regions/{region}/devices/{device_id}/certificate
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

device_id
required string
Device ID.
Body

certificate_pem
required string
The PEM-encoded custom certificate.
Request Example
200 Response

device
object

certificate_pem
string
Response Example
POST
/iot/v1/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.
Body

Request Example
200 Response

id
string
Device ID, also used as MQTT Client ID or Username.

name
string
Device name.

description
string
Device description.

status
string
Device status. Possible values are unknown, error, enabled and disabled. The default value is unknown.

hub_id
string
Hub ID.

last_activity_at
string
Device last connection/activity date (RFC 3339 format).

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.

has_custom_certificate
boolean
Assigning a custom certificate allows a device to authenticate using that specific certificate without checking the hub's CA certificate.

created_at
string
Device add date (RFC 3339 format).

updated_at
string
Device last modification date (RFC 3339 format).
Response Example
POST
/iot/v1/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.
Body

Request Example
200 Response

id
string
Device ID, also used as MQTT Client ID or Username.

name
string
Device name.

description
string
Device description.

status
string
Device status. Possible values are unknown, error, enabled and disabled. The default value is unknown.

hub_id
string
Hub ID.

last_activity_at
string
Device last connection/activity date (RFC 3339 format).

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.

has_custom_certificate
boolean
Assigning a custom certificate allows a device to authenticate using that specific certificate without checking the hub's CA certificate.

created_at
string
Device add date (RFC 3339 format).

updated_at
string
Device last modification date (RFC 3339 format).
Response Example
GET
/iot/v1/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

start_date
required string
Start date used to compute the best scale for the returned metrics (RFC 3339 format).
200 Response

metrics
array
Metrics for a device over the requested period.
Response Example
POST
/iot/v1/regions/{region}/devices/{device_id}/renew-certificate
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

device_id
required string
Device ID.
Body

Request Example
200 Response

device
object
Created device information.

certificate
object
Device certificate.
Response Example

Managed routes

GET
/iot/v1/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.

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.
Response Example

Multiple route kinds can be created:

  • Database Route. Create a route that will record subscribed MQTT messages into your database.You need to manage the database by yourself.
  • REST Route. Create a route that will call a REST API on received subscribed MQTT messages.
  • S3 Routes. 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. The grant can be done with s3cmd (s3cmd setacl s3://<my-bucket> --acl-grant=write:555c69c3-87d0-4bf8-80f1-99a2f757d031:555c69c3-87d0-4bf8-80f1-99a2f757d031).
POST
/iot/v1/regions/{region}/routes
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.
Body

name
string
Route name.

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.

s3_config
object
If creating S3 Route, S3-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

db_config
object
If creating Database Route, DB-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

rest_config
object
If creating Rest Route, Rest-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.
Request Example
200 Response

id
string
Route ID.

name
string
Route name.

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 (RFC 3339 format).

s3_config
object
When using S3 Route, S3-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

db_config
object
When using Database Route, DB-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

rest_config
object
When using Rest Route, Rest-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

updated_at
string
Route last update date (RFC 3339 format).
Response Example
GET
/iot/v1/regions/{region}/routes/{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.

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 (RFC 3339 format).

s3_config
object
When using S3 Route, S3-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

db_config
object
When using Database Route, DB-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

rest_config
object
When using Rest Route, Rest-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

updated_at
string
Route last update date (RFC 3339 format).
Response Example
PATCH
/iot/v1/regions/{region}/routes/{route_id}
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

route_id
required string
Route id.
Body

name
nullable string
Route name.

topic
nullable string
Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters.

s3_config
object
When updating S3 Route, S3-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

db_config
object
When updating Database Route, DB-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

rest_config
object
When updating Rest Route, Rest-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.
Request Example
200 Response

id
string
Route ID.

name
string
Route name.

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 (RFC 3339 format).

s3_config
object
When using S3 Route, S3-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

db_config
object
When using Database Route, DB-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

rest_config
object
When using Rest Route, Rest-specific configuration fields. Only one of s3_config, db_config and rest_config may be set.

updated_at
string
Route last update date (RFC 3339 format).
Response Example
DELETE
/iot/v1/regions/{region}/routes/{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

Links to external IoT networks

GET
/iot/v1/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.

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.
Response Example
POST
/iot/v1/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.

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
200 Response

network
object
Created network.

secret
string
Endpoint Key to keep secret. This cannot be retrieved later.
Response Example
GET
/iot/v1/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 (RFC 3339 format).

topic_prefix
string
This prefix will be prepended to all topics for this Network.
Response Example
DELETE
/iot/v1/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

Cloud representation of devices

GET
/iot/v1/regions/{region}/twins/{twin_id}
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

twin_id
required string
Twin ID.
200 Response

documents
array
Twin's document list.
Response Example
DELETE
/iot/v1/regions/{region}/twins/{twin_id}
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

twin_id
required string
Twin ID.
204 Response

Empty response
GET
/iot/v1/regions/{region}/twins/{twin_id}/documents/{document_name}
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

twin_id
required string
Twin ID.

document_name
required string
Document name.
200 Response

twin_id
string
Document's parent twin ID.

document_name
string
Document's name.

version
number
Document's new version.

data
object
Document's new data.
Response Example
PUT
/iot/v1/regions/{region}/twins/{twin_id}/documents/{document_name}
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

twin_id
required string
Twin ID.

document_name
required string
Document name.
Body

version
nullable number
If set, ensures that the document's current version matches before persisting the update.

data
object
The new data that will replace the contents of the document.
Request Example
200 Response

twin_id
string
Document's parent twin ID.

document_name
string
Document's name.

version
number
Document's new version.

data
object
Document's new data.
Response Example
PATCH
/iot/v1/regions/{region}/twins/{twin_id}/documents/{document_name}
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

twin_id
required string
Twin ID.

document_name
required string
Document name.
Body

version
nullable number
If set, ensures that the document's current version matches before persisting the update.

data
object
A json data that will be applied on the document's current data. Patching rules: * The patch goes recursively through the patch objects. * If the patch object property is null, then it is removed from the final object. * If the patch object property is a value (number, strings, bool, arrays), it is replaced. * If the patch object property is an object, the previous rules will be applied recursively on it. .
Request Example
200 Response

twin_id
string
Document's parent twin ID.

document_name
string
Document's name.

version
number
Document's new version.

data
object
Document's new data.
Response Example
DELETE
/iot/v1/regions/{region}/twins/{twin_id}/documents/{document_name}
Path Parameters

region
required string
The region you want to target. Possible value is fr-par.

twin_id
required string
Twin ID.

document_name
required string
Document name.
204 Response

Empty response