IoT Hubs

Send and receive messages from connected IoT devices through managed message brokers

List hubs

GET

https://api.scaleway.com

/iot/v1/regions/{region}/hubs

List all Hubs in the specified zone. By default, returned Hubs are ordered by creation date in ascending order, though this can be modified via the order_by field.

List hubs › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

List hubs › query Parameters

page

integer · int32

Page number to return, from the paginated results.

page_size

integer · uint32

Number of Hubs to return within a page. Maximum value is 100.

order_by

string · enum

Sort order of Hubs in the response.

Enum values:

name_asc

name_desc

status_asc

status_desc

product_plan_asc

product_plan_desc

created_at_asc

created_at_desc

Default: name_asc

project_id

string

Only list Hubs of this Project ID.

organization_id

string

Only list Hubs of this Organization ID.

name

string

Hub name.

List hubs › Responses

200

scaleway.iot.v1.ListHubsResponse

total_count

integer · uint32

Total number of Hubs.

scaleway.iot.v1.Hub[]

A page of hubs.

GET/iot/v1/regions/{region}/hubs

curl -X GET \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/iot/v1/regions/{region}/hubs"

Example Responses

{
  "total_count": 0,
  "hubs": [
    {
      "id": "id",
      "name": "name",
      "status": "unknown",
      "product_plan": "plan_unknown",
      "enabled": true,
      "device_count": 0,
      "connected_device_count": 0,
      "endpoint": "endpoint",
      "disable_events": true,
      "events_topic_prefix": "events_topic_prefix",
      "region": "region",
      "created_at": "2022-03-22T12:34:56.123456Z",
      "updated_at": "2022-03-22T12:34:56.123456Z",
      "project_id": "project_id",
      "organization_id": "organization_id",
      "enable_device_auto_provisioning": true,
      "has_custom_ca": true,
      "twins_graphite_config": {
        "push_uri": "push_uri"
      }
    }
  ]
}

json

application/json

Create a hub

POST

https://api.scaleway.com

/iot/v1/regions/{region}/hubs

Create a new Hub in the targeted region, specifying its configuration including name and product plan.

Create a hub › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

Create a hub › Request Body

name

string · required

Hub name (up to 255 characters).

project_id

string · required

Project/Organization ID to filter for, only Hubs from this Project/Organization will be returned.

product_plan

string · enum · required

Hub product plan.

Enum values:

plan_unknown

plan_shared

plan_dedicated

plan_ha

Default: plan_unknown

disable_events

boolean

Disable Hub events.

events_topic_prefix

string

Topic prefix (default '$SCW/events') of Hub events.

object

BETA - not implemented yet.

Create a hub › Responses

200

scaleway.iot.v1.Hub

id

string

Hub ID.

name

string

Hub name.

status

string · enum

Current status of the Hub.

Enum values:

unknown

error

enabling

ready

disabling

disabled

Default: unknown

product_plan

string · enum

Hub feature set.

Enum values:

plan_unknown

plan_shared

plan_dedicated

plan_ha

Default: plan_unknown

enabled

boolean

Defines whether the hub has been enabled.

device_count

integer · uint64

Number of registered devices.

connected_device_count

integer · uint64

Number of currently connected devices.

endpoint

string

Host to connect your devices to. 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

Defines whether to disable Hub events.

events_topic_prefix

string

Hub events topic prefix.

region

string

Region of the Hub.

created_at

string · date-time

Hub creation date. (RFC 3339 format)

updated_at

string · date-time

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

Defines whether to enable device auto provisioning. 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 certificate 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

Defines whether the hub is using a custom certificate authority. Flag is automatically set to false after Hub creation, as Hub certificates are managed by Scaleway. Once a custom certificate authority is set, the flag will be set to true.

object

BETA - not implemented yet.

POST/iot/v1/regions/{region}/hubs

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "product_plan": "plan_unknown",
    "project_id": "string"
  }' \
  "https://api.scaleway.com/iot/v1/regions/{region}/hubs"

Example Request Body

{
  "name": "name",
  "project_id": "project_id",
  "product_plan": "plan_unknown",
  "disable_events": true,
  "events_topic_prefix": "events_topic_prefix",
  "twins_graphite_config": {
    "push_uri": "push_uri"
  }
}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "status": "unknown",
  "product_plan": "plan_unknown",
  "enabled": true,
  "device_count": 0,
  "connected_device_count": 0,
  "endpoint": "endpoint",
  "disable_events": true,
  "events_topic_prefix": "events_topic_prefix",
  "region": "region",
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "project_id": "project_id",
  "organization_id": "organization_id",
  "enable_device_auto_provisioning": true,
  "has_custom_ca": true,
  "twins_graphite_config": {
    "push_uri": "push_uri"
  }
}

json

application/json

Get a hub

GET

https://api.scaleway.com

/iot/v1/regions/{region}/hubs/{hub_id}

Retrieve information about an existing IoT Hub, specified by its Hub ID. Its full details, including name, status and endpoint, are returned in the response object.

Get a hub › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

hub_id

string · required

Hub ID.

Get a hub › Responses

200

scaleway.iot.v1.Hub

id

string

Hub ID.

name

string

Hub name.

status

string · enum

Current status of the Hub.

Enum values:

unknown

error

enabling

ready

disabling

disabled

Default: unknown

product_plan

string · enum

Hub feature set.

Enum values:

plan_unknown

plan_shared

plan_dedicated

plan_ha

Default: plan_unknown

enabled

boolean

Defines whether the hub has been enabled.

device_count

integer · uint64

Number of registered devices.

connected_device_count

integer · uint64

Number of currently connected devices.

endpoint

string

Host to connect your devices to. 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

Defines whether to disable Hub events.

events_topic_prefix

string

Hub events topic prefix.

region

string

Region of the Hub.

created_at

string · date-time

Hub creation date. (RFC 3339 format)

updated_at

string · date-time

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

has_custom_ca

boolean

object

BETA - not implemented yet.

Delete a hub

DELETE

https://api.scaleway.com

/iot/v1/regions/{region}/hubs/{hub_id}

Delete an existing IoT Hub, specified by its Hub ID. Deleting a Hub is permanent, and cannot be undone.

Delete a hub › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

hub_id

string · required

Hub ID.

Delete a hub › query Parameters

delete_devices

boolean

Defines whether to force the deletion of devices added to this Hub or reject the operation.

Delete a hub › Responses

No data returned

Update a hub

PATCH

https://api.scaleway.com

/iot/v1/regions/{region}/hubs/{hub_id}

Update the parameters of an existing IoT Hub, specified by its Hub ID.

Update a hub › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

hub_id

string · required

ID of the Hub you want to update.

Update a hub › Request Body

name

string

Hub name (up to 255 characters).

product_plan

string · enum

Hub product plan.

Enum values:

plan_unknown

plan_shared

plan_dedicated

plan_ha

Default: plan_unknown

disable_events

boolean

Disable Hub events.

events_topic_prefix

string

Topic prefix of Hub events.

enable_device_auto_provisioning

boolean

Enable device auto provisioning.

object

BETA - not implemented yet.

Update a hub › Responses

200

scaleway.iot.v1.Hub

id

string

Hub ID.

name

string

Hub name.

status

string · enum

Current status of the Hub.

Enum values:

unknown

error

enabling

ready

disabling

disabled

Default: unknown

product_plan

string · enum

Hub feature set.

Enum values:

plan_unknown

plan_shared

plan_dedicated

plan_ha

Default: plan_unknown

enabled

boolean

Defines whether the hub has been enabled.

device_count

integer · uint64

Number of registered devices.

connected_device_count

integer · uint64

Number of currently connected devices.

endpoint

string

Host to connect your devices to. 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

Defines whether to disable Hub events.

events_topic_prefix

string

Hub events topic prefix.

region

string

Region of the Hub.

created_at

string · date-time

Hub creation date. (RFC 3339 format)

updated_at

string · date-time

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

has_custom_ca

boolean

object

BETA - not implemented yet.

PATCH/iot/v1/regions/{region}/hubs/{hub_id}

curl -X PATCH \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/hubs/{hub_id}"

Example Request Body

{
  "name": "name",
  "product_plan": "plan_unknown",
  "disable_events": true,
  "events_topic_prefix": "events_topic_prefix",
  "enable_device_auto_provisioning": true,
  "twins_graphite_config": {
    "push_uri": "push_uri"
  }
}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "status": "unknown",
  "product_plan": "plan_unknown",
  "enabled": true,
  "device_count": 0,
  "connected_device_count": 0,
  "endpoint": "endpoint",
  "disable_events": true,
  "events_topic_prefix": "events_topic_prefix",
  "region": "region",
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "project_id": "project_id",
  "organization_id": "organization_id",
  "enable_device_auto_provisioning": true,
  "has_custom_ca": true,
  "twins_graphite_config": {
    "push_uri": "push_uri"
  }
}

json

application/json

Get the certificate authority of a hub

GET

https://api.scaleway.com

/iot/v1/regions/{region}/hubs/{hub_id}/ca

Get information for a particular PEM-encoded certificate, specified by the Hub ID.

Get the certificate authority of a hub › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

hub_id

string · required

Get the certificate authority of a hub › Responses

200

scaleway.iot.v1.GetHubCAResponse

ca_cert_pem

string

Set the certificate authority of a hub

POST

https://api.scaleway.com

/iot/v1/regions/{region}/hubs/{hub_id}/ca

Set a particular PEM-encoded certificate, specified by the Hub ID.

Set the certificate authority of a hub › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

hub_id

string · required

Hub ID.

Set the certificate authority of a hub › Request Body

ca_cert_pem

string · required

CA's PEM-encoded certificate.

challenge_cert_pem

string · required

Proof of possession of PEM-encoded certificate. Challenge is a PEM-encoded certificate that acts as proof of possession of the CA. It must be signed by the CA, and have a Common Name equal to the Hub ID.

Set the certificate authority of a hub › Responses

200

scaleway.iot.v1.Hub

id

string

Hub ID.

name

string

Hub name.

status

string · enum

Current status of the Hub.

Enum values:

unknown

error

enabling

ready

disabling

disabled

Default: unknown

product_plan

string · enum

Hub feature set.

Enum values:

plan_unknown

plan_shared

plan_dedicated

plan_ha

Default: plan_unknown

enabled

boolean

Defines whether the hub has been enabled.

device_count

integer · uint64

Number of registered devices.

connected_device_count

integer · uint64

Number of currently connected devices.

endpoint

string

Host to connect your devices to. 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

Defines whether to disable Hub events.

events_topic_prefix

string

Hub events topic prefix.

region

string

Region of the Hub.

created_at

string · date-time

Hub creation date. (RFC 3339 format)

updated_at

string · date-time

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

has_custom_ca

boolean

object

BETA - not implemented yet.

POST/iot/v1/regions/{region}/hubs/{hub_id}/ca

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ca_cert_pem":"string","challenge_cert_pem":"string"}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/hubs/{hub_id}/ca"

Example Request Body

{
  "ca_cert_pem": "ca_cert_pem",
  "challenge_cert_pem": "challenge_cert_pem"
}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "status": "unknown",
  "product_plan": "plan_unknown",
  "enabled": true,
  "device_count": 0,
  "connected_device_count": 0,
  "endpoint": "endpoint",
  "disable_events": true,
  "events_topic_prefix": "events_topic_prefix",
  "region": "region",
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "project_id": "project_id",
  "organization_id": "organization_id",
  "enable_device_auto_provisioning": true,
  "has_custom_ca": true,
  "twins_graphite_config": {
    "push_uri": "push_uri"
  }
}

json

application/json

Disable a hub

POST

https://api.scaleway.com

/iot/v1/regions/{region}/hubs/{hub_id}/disable

Disable an existing IoT Hub, specified by its Hub ID.

Disable a hub › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

hub_id

string · required

Hub ID.

Disable a hub › Request Body

Disable a hub › Responses

200

scaleway.iot.v1.Hub

id

string

Hub ID.

name

string

Hub name.

status

string · enum

Current status of the Hub.

Enum values:

unknown

error

enabling

ready

disabling

disabled

Default: unknown

product_plan

string · enum

Hub feature set.

Enum values:

plan_unknown

plan_shared

plan_dedicated

plan_ha

Default: plan_unknown

enabled

boolean

Defines whether the hub has been enabled.

device_count

integer · uint64

Number of registered devices.

connected_device_count

integer · uint64

Number of currently connected devices.

endpoint

string

Host to connect your devices to. 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

Defines whether to disable Hub events.

events_topic_prefix

string

Hub events topic prefix.

region

string

Region of the Hub.

created_at

string · date-time

Hub creation date. (RFC 3339 format)

updated_at

string · date-time

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

has_custom_ca

boolean

object

BETA - not implemented yet.

POST/iot/v1/regions/{region}/hubs/{hub_id}/disable

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/hubs/{hub_id}/disable"

Example Request Body

{}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "status": "unknown",
  "product_plan": "plan_unknown",
  "enabled": true,
  "device_count": 0,
  "connected_device_count": 0,
  "endpoint": "endpoint",
  "disable_events": true,
  "events_topic_prefix": "events_topic_prefix",
  "region": "region",
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "project_id": "project_id",
  "organization_id": "organization_id",
  "enable_device_auto_provisioning": true,
  "has_custom_ca": true,
  "twins_graphite_config": {
    "push_uri": "push_uri"
  }
}

json

application/json

Enable a hub

POST

https://api.scaleway.com

/iot/v1/regions/{region}/hubs/{hub_id}/enable

Enable an existing IoT Hub, specified by its Hub ID.

Enable a hub › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

hub_id

string · required

Hub ID.

Enable a hub › Request Body

Enable a hub › Responses

200

scaleway.iot.v1.Hub

id

string

Hub ID.

name

string

Hub name.

status

string · enum

Current status of the Hub.

Enum values:

unknown

error

enabling

ready

disabling

disabled

Default: unknown

product_plan

string · enum

Hub feature set.

Enum values:

plan_unknown

plan_shared

plan_dedicated

plan_ha

Default: plan_unknown

enabled

boolean

Defines whether the hub has been enabled.

device_count

integer · uint64

Number of registered devices.

connected_device_count

integer · uint64

Number of currently connected devices.

endpoint

string

Host to connect your devices to. 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

Defines whether to disable Hub events.

events_topic_prefix

string

Hub events topic prefix.

region

string

Region of the Hub.

created_at

string · date-time

Hub creation date. (RFC 3339 format)

updated_at

string · date-time

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

has_custom_ca

boolean

object

BETA - not implemented yet.

POST/iot/v1/regions/{region}/hubs/{hub_id}/enable

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/hubs/{hub_id}/enable"

Example Request Body

{}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "status": "unknown",
  "product_plan": "plan_unknown",
  "enabled": true,
  "device_count": 0,
  "connected_device_count": 0,
  "endpoint": "endpoint",
  "disable_events": true,
  "events_topic_prefix": "events_topic_prefix",
  "region": "region",
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "project_id": "project_id",
  "organization_id": "organization_id",
  "enable_device_auto_provisioning": true,
  "has_custom_ca": true,
  "twins_graphite_config": {
    "push_uri": "push_uri"
  }
}

json

application/json

deprecated

Get a hub's metrics

GET

https://api.scaleway.com

/iot/v1/regions/{region}/hubs/{hub_id}/metrics

Get the metrics of an existing IoT Hub, specified by its Hub ID.

Get a hub's metrics › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

hub_id

string · required

Hub ID.

Get a hub's metrics › query Parameters

start_date

string · date-time

Start date used to compute the best scale for returned metrics. (RFC 3339 format)

Get a hub's metrics › Responses

200

scaleway.iot.v1.GetHubMetricsResponse

scaleway.std.TimeSeries[]

Metrics for a Hub over the requested period.

IoT Devices